The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: gate ECC progress sync readiness
Affaan Mustafa63f9bfc33f9d
diff --git a/docs/ECC-2.0-GA-ROADMAP.md b/docs/ECC-2.0-GA-ROADMAP.mdindex ae05626a8..84a77b63c 100644--- a/docs/ECC-2.0-GA-ROADMAP.md+++ b/docs/ECC-2.0-GA-ROADMAP.md@@ -30,10 +30,15 @@ As of 2026-05-13:Linear project status updates remain the active tracking surfaces until theworkspace is upgraded or issue capacity is freed.- `npm run harness:audit -- --format json` reports 70/70 on current `main`.-- `npm run observability:ready` reports 16/16 readiness on current `main`.+- `npm run observability:ready` reports 18/18 readiness on current `main`,+ including the GitHub/Linear/handoff/roadmap progress-sync contract.- PR #1846 merged as `797f283036904128bb1b348ae62019eb9f08cf39` and madenpm registry signature verification a durable workflow-security gate:workflows that run `npm audit` now need `npm audit signatures`.+- PR #1848 merged as `cbecf5689d8d1bd5915e7031697a1d56aac538f2` and added+ `docs/security/supply-chain-incident-response.md`, plus a workflow-security+ validator rule blocking `pull_request_target` workflows from restoring or+ saving shared dependency caches.- `docs/architecture/harness-adapter-compliance.md` maps Claude Code, Codex,OpenCode, Cursor, Gemini, Zed-adjacent, dmux, Orca, Superset, Ghast, andterminal-only support to install paths, verification commands, and risk@@ -56,6 +61,8 @@ As of 2026-05-13:release-readiness evidence refresh: 70/70 harness audit, adapter compliancePASS, 16/16 observability readiness, 2376/2376 root Node tests, markdownlint,release-surface and npm publish-surface tests, and 462/462 `ecc2` Rust tests.+- After #1848, `node tests/run-all.js` reports 2377/2377 and the current+ observability gate reports 18/18.- A detached clean worktree at`bfacf37715b39655cbc2c48f12f2a35c67cb0253` verified Claude plugin tagdry-run without `--force`, local marketplace discovery, temp-home local@@ -218,10 +225,10 @@ is not complete unless the evidence column exists and has been freshly verified.| Prompt requirement | Required artifact or gate | Current evidence | Status || --- | --- | --- | --- |-| Keep public PRs below 20 | Repo-family PR recheck | 0 open PRs across the tracked public repos on 2026-05-13 after merging #1846 | Complete for this checkpoint |+| Keep public PRs below 20 | Repo-family PR recheck | 0 open PRs across the tracked public repos on 2026-05-13 after merging #1848 | Complete for this checkpoint || Keep public issues below 20 | Repo-family issue recheck | 0 open issues across the tracked public repos on 2026-05-13 | Complete for this checkpoint || Manage repository discussions | Repo-family discussion recheck | Latest trunk discussion GraphQL sweep returned closed discussions only; satellite repos remain disabled or empty | Complete for this checkpoint |-| Manage PR discussions | PR review/comment closure plus merge/close state | #1846 merged after current-head CI; no open PRs remain | Complete for this checkpoint |+| Manage PR discussions | PR review/comment closure plus merge/close state | #1848 merged after current-head CI; no open PRs remain | Complete for this checkpoint || Salvage useful stale work | `docs/stale-pr-salvage-ledger.md` | Ledger records salvaged, superseded, skipped, and manual-review tails; #1815-#1818 added cost tracking, skill scout, frontend design guidance, code-reviewer false-positive guardrails, and the May 12 gap pass | Complete except translation/manual review tail || ECC 2.0 preview pack ready | Release docs, quickstart, publication readiness, release notes | `docs/releases/2.0.0-rc.1/` and readiness docs are in-tree; May 13 evidence refresh records harness, adapter, observability, Node, lint, release-surface, npm publish-surface, and Rust checks | Needs final clean-checkout release approval || Hermes specialized skills included safely | Hermes setup/import docs and sanitized skill surface | Hermes setup and import playbook are public; secrets stay local | Needs final release review |@@ -230,20 +237,21 @@ is not complete unless the evidence column exists and has been freshly verified.| Articles, tweets, and announcements | X thread, LinkedIn copy, GitHub release copy, push checklist | Draft launch collateral exists under rc.1 release docs | Needs URL-backed refresh || AgentShield enterprise iteration | Policy gates, SARIF, packs, provenance, corpus, HTML reports, exception lifecycle audit, baseline drift Action/CLI surfaces, enterprise research roadmap | PRs #53, #55-#64 landed with test evidence; native PDF export deferred in favor of self-contained HTML plus print-to-PDF until explicit enterprise demand appears; `docs/architecture/agentshield-enterprise-research-roadmap.md` selects baseline drift as the first control-plane slice | Baseline-drift Action and CLI write surfaces landed; evidence-pack routing remains || ECC Tools next-level app | Billing audit, PR checks, deep analyzer, sync backlog, evaluator/RAG corpus | PRs #26-#40 landed with test evidence | Needs capacity-backed Linear rollout |-| GitGuardian/Dependabot/CodeRabbit-style checks | Non-blocking taxonomy and deterministic follow-up checks | ECC-Tools risk taxonomy check plus follow-up signals landed, including Skill Quality, Deep Analyzer Evidence, Analyzer Corpus Evidence, RAG/Evaluator Evidence, and PR Review/Salvage Evidence | Partially complete |+| GitGuardian/Dependabot/CodeRabbit-style checks | Non-blocking taxonomy, deterministic follow-up checks, and local supply-chain gates | ECC-Tools risk taxonomy check plus follow-up signals landed, including Skill Quality, Deep Analyzer Evidence, Analyzer Corpus Evidence, RAG/Evaluator Evidence, and PR Review/Salvage Evidence; #1846 added npm registry signature gates; #1848 added the supply-chain incident-response playbook and `pull_request_target` cache-poisoning validator guard | Partially complete || Harness-agnostic learning system | Audit, adapter matrix, observability, traces, promotion loop | Audit/adapters/observability gates plus `docs/architecture/evaluator-rag-prototype.md`, `examples/evaluator-rag-prototype/`, and ECC-Tools PR #40 define read-only stale-salvage, billing-readiness, CI-failure-diagnosis, harness-config-quality, AgentShield policy-exception, skill-quality evidence, deep-analyzer evidence, and RAG/evaluator comparison scenarios with trace, report, playbook, verifier, and predictive-check artifacts | Local corpus complete; hosted integration remains future || Linear roadmap is detailed | Linear project status plus repo mirror | Repo mirror exists; issue creation was retried on 2026-05-12 and remains blocked by the workspace free issue limit | Needs recurring status updates after each merge batch |-| Flow separation and progress tracking | Flow lanes with owner artifacts and update cadence | This roadmap defines lanes below | Active |-| Realtime Linear sync | Project updates while issue limit is blocked; issues later | ECC-Tools #39 implements opt-in Linear API sync for deferred follow-up backlog items | Needs workspace capacity/config rollout |-| Observability for self-use | Local readiness gate, traces, status snapshots, HUD/status contract, risk ledger | `npm run observability:ready` reports 16/16 | Complete for local gate |+| Flow separation and progress tracking | Flow lanes with owner artifacts and update cadence | This roadmap defines lanes below and `docs/architecture/progress-sync-contract.md` makes GitHub/Linear/handoff/roadmap sync part of the readiness gate | Active |+| Realtime Linear sync | Project updates while issue limit is blocked; issues later | ECC-Tools #39 implements opt-in Linear API sync for deferred follow-up backlog items; `docs/architecture/progress-sync-contract.md` defines the local file-backed realtime boundary while issue capacity is blocked | Needs workspace capacity/config rollout |+| Observability for self-use | Local readiness gate, traces, status snapshots, HUD/status contract, risk ledger, progress-sync contract | `npm run observability:ready` reports 18/18 | Complete for local gate || Proper release and notifications | Release tag, npm publish state, plugin state, social posts | Publication readiness gate exists with May 12 dry-run and May 13 readiness evidence | Not complete; approval/live URLs required |## Execution Lanes And Tracking ContractUntil Linear issue capacity is cleared, this document is the durable execution-ledger and Linear receives project status updates only. When capacity is-available, each lane below should become a small set of Linear issues linked-back to the repo evidence and merge commits.+ledger and Linear receives project status updates only. The sync contract lives+at `docs/architecture/progress-sync-contract.md`. When capacity is available,+each lane below should become a small set of Linear issues linked back to the+repo evidence and merge commits.| Lane | Source of truth | Next tracked artifact | Update cadence || --- | --- | --- | --- |@@ -253,7 +261,7 @@ back to the repo evidence and merge commits.| Evaluation and RAG | Reference-set validation, harness audit, traces, ECC-Tools corpus | Read-only evaluator/RAG prototype plus stale-salvage, billing-readiness, CI-failure-diagnosis, harness-config-quality, AgentShield policy-exception, skill-quality evidence, deep-analyzer evidence, and RAG/evaluator comparison fixtures | Hosted retrieval/check-run automation plan || AgentShield enterprise | AgentShield PR evidence and roadmap notes | Baseline-drift evidence-pack and backlog sync follow-up | Next implementation batch || ECC Tools app | ECC-Tools PR evidence, billing audit, risk taxonomy, evaluator/RAG corpus | Capacity-backed Linear rollout | Next implementation batch |-| Linear progress | Linear project status updates and this mirror | Status update with queue/evidence/missing gates | Every significant merge batch |+| Linear progress | Linear project status updates, `docs/architecture/progress-sync-contract.md`, and this mirror | Status update with queue/evidence/missing gates | Every significant merge batch |The project status update should always include:diff --git a/docs/architecture/observability-readiness.md b/docs/architecture/observability-readiness.mdindex c0f0ce317..08bfdd77c 100644--- a/docs/architecture/observability-readiness.md+++ b/docs/architecture/observability-readiness.md@@ -32,6 +32,9 @@ operator needs.`tool-usage.jsonl` events that ECC2 can sync.- Risk ledger: `ecc2/src/observability/mod.rs` scores tool calls and stores apaginated ledger for review.+- Progress sync: `docs/architecture/progress-sync-contract.md` defines how+ GitHub, Linear, local handoffs, the repo roadmap, and `scripts/work-items.js`+ stay aligned during merge batches and release-gate reviews.## Reference Pressure@@ -64,9 +67,12 @@ later, but only after the local event model is useful enough to trust.operator dashboard.5. Run `node scripts/session-inspect.js --list-adapters` to confirm whichsession surfaces are available.-6. Use ECC2 tool logs for risky operations, conflict analysis, and handoff+6. Run `node scripts/work-items.js sync-github --repo <owner/repo>` before+ relying on local work-item status for a tracked repository.+7. Use ECC2 tool logs for risky operations, conflict analysis, and handoffreview before increasing autonomy.The end-state is practical: before asking ECC to run larger multi-agent loops,the operator can prove the system has live status, durable session traces,-baseline scorecards, and a local risk ledger.+baseline scorecards, a local risk ledger, and a progress-sync contract that+keeps GitHub, Linear, handoffs, and roadmap evidence from drifting apart.diff --git a/docs/architecture/progress-sync-contract.md b/docs/architecture/progress-sync-contract.mdnew file mode 100644index 000000000..8830e6157--- /dev/null+++ b/docs/architecture/progress-sync-contract.md@@ -0,0 +1,67 @@+# Progress Sync Contract++ECC 2.0 tracks execution state across GitHub, Linear, local handoffs, and the+repo roadmap. This contract defines the minimum evidence required before a+status update can claim a lane is current.++## Sources Of Truth++| Surface | Role | Current rule |+| --- | --- | --- |+| GitHub PRs/issues/discussions | Public queue and review state | Recheck live counts before every significant merge batch and before release approval. |+| Linear project | Executive roadmap and stakeholder status update | Post project status updates while issue capacity blocks issue creation. Create/reuse issues only when workspace capacity is available. |+| Local handoff | Durable operator continuity | Update the active handoff after every merge batch, queue drain, skipped release gate, or blocked external action. |+| Repo roadmap | Auditable planning mirror | Keep `docs/ECC-2.0-GA-ROADMAP.md` aligned to merged PR evidence and unresolved gates. |+| `scripts/work-items.js` | Local tracker bridge | Sync GitHub PRs/issues into the SQLite work-items store for status snapshots and blocked follow-up. |++## Flow Lanes++The repo mirror uses these flow lanes so ECC work does not collapse into one+undifferentiated backlog:++- Queue hygiene and stale-work salvage+- Release, naming, plugin publication, and announcements+- Harness adapter compliance+- Local observability, HUD/status, and session control+- Evaluator/RAG and self-improving harness loops+- AgentShield enterprise security platform+- ECC Tools billing, PR-risk checks, deep analysis, and Linear sync+- Legacy artifact audit and translator/manual-review tails++Each flow lane needs one owner artifact, one current evidence source, and one+next action. A lane is not current if any of those three fields are missing.++## Significant Merge Batch Update++After a significant merge batch, update Linear and the handoff with:++1. Current public queue counts for tracked GitHub repos.+2. Merged PR numbers, commit IDs, and validation evidence.+3. Changed release gates, if any.+4. Deferred or skipped work and the explicit reason.+5. The next one or two implementation slices.++When Linear issue capacity is unavailable, use a project status update instead+of creating placeholder issues. When issue capacity is available, create or+reuse exact-title issues and link them to the repo evidence.++## Realtime Boundary++The local realtime path is file-backed by default:++- `node scripts/work-items.js sync-github --repo <owner/repo>` imports current+ GitHub PR and issue state into the SQLite work-items store.+- `node scripts/status.js --json` and `node scripts/work-items.js list --json`+ expose local state for a HUD, handoff, or later Linear sync.+- Linear remains the external status surface; the repo does not require hosted+ telemetry to be release-ready.++Hosted telemetry such as PostHog can be added later, but it must consume the+same event model rather than becoming a second source of truth.++## Release Gate++Do not publish, tag, announce, submit marketplace packages, or claim plugin+availability from this contract alone. Release readiness still requires the+publication-readiness evidence documents, fresh queue checks, package checks,+plugin checks, and explicit maintainer approval.diff --git a/scripts/observability-readiness.js b/scripts/observability-readiness.jsindex 97d4bd159..e90321b32 100644--- a/scripts/observability-readiness.js+++ b/scripts/observability-readiness.js@@ -124,6 +124,9 @@ function buildChecks(rootDir) {const sessionManagerRust = readText(rootDir, 'ecc2/src/session/manager.rs');const readinessDoc = readText(rootDir, 'docs/architecture/observability-readiness.md');const hudStatusContract = readText(rootDir, 'docs/architecture/hud-status-session-control.md');+ const progressSyncContract = readText(rootDir, 'docs/architecture/progress-sync-contract.md');+ const gaRoadmap = readText(rootDir, 'docs/ECC-2.0-GA-ROADMAP.md');+ const workItems = readText(rootDir, 'scripts/work-items.js');const hudStatusFixture = safeParseJson(readText(rootDir, 'examples/hud-status-contract.json')) || {};const quickstart = readText(rootDir, 'docs/releases/2.0.0-rc.1/quickstart.md');const releaseNotes = readText(rootDir, 'docs/releases/2.0.0-rc.1/release-notes.md');@@ -238,6 +241,40 @@ function buildChecks(rootDir) {&& releaseNotes.includes('observability-readiness.md'),fix: 'Add the observability readiness doc and link it from rc.1 release docs.'},+ {+ id: 'progress-sync-contract',+ category: 'Tracker Sync',+ points: 2,+ path: 'docs/architecture/progress-sync-contract.md',+ description: 'Linear, GitHub, handoff, and roadmap progress sync has an evidence-backed contract',+ pass: fileExists(rootDir, 'docs/architecture/progress-sync-contract.md')+ && includesAll(progressSyncContract, [+ 'Linear',+ 'GitHub',+ 'handoff',+ 'work-items',+ 'issue capacity',+ 'status update',+ 'queue counts',+ 'release gate',+ 'flow lanes',+ 'evidence'+ ])+ && includesAll(gaRoadmap, [+ 'Execution Lanes And Tracking Contract',+ 'docs/architecture/progress-sync-contract.md',+ 'Linear progress',+ 'Every significant merge batch'+ ])+ && includesAll(workItems, [+ 'sync-github',+ 'github-pr',+ 'github-issue',+ 'sourceClosedAt',+ 'ecc-work-items-sync-github'+ ]),+ fix: 'Add the progress sync contract, link it from the GA roadmap, and preserve work-items GitHub sync.'+ },{id: 'package-exposes-readiness-gate',category: 'Packaging',diff --git a/tests/scripts/observability-readiness.test.js b/tests/scripts/observability-readiness.test.jsindex d2e1b6bf7..c4e4c07e8 100644--- a/tests/scripts/observability-readiness.test.js+++ b/tests/scripts/observability-readiness.test.js@@ -57,11 +57,22 @@ function seedMinimalRepo(rootDir, overrides = {}) {'scripts/session-inspect.js': '--list-adapters --write inspectSessionTarget','scripts/lib/session-adapters/registry.js': 'module.exports = {};','scripts/harness-audit.js': 'Deterministic harness audit --format overall_score',+ 'scripts/work-items.js': 'sync-github github-pr github-issue sourceClosedAt ecc-work-items-sync-github','scripts/hooks/session-activity-tracker.js': 'tool-usage.jsonl session_id tool_name','ecc2/src/observability/mod.rs': 'ToolCallEvent RiskAssessment ToolLogger','ecc2/src/session/store.rs': 'insert_tool_log query_tool_logs','ecc2/src/session/manager.rs': 'sync_tool_activity_metrics tool-usage.jsonl','docs/architecture/observability-readiness.md': 'node scripts/observability-readiness.js --format json',+ 'docs/architecture/progress-sync-contract.md': [+ 'Linear GitHub handoff work-items issue capacity status update',+ 'queue counts release gate flow lanes evidence'+ ].join('\n'),+ 'docs/ECC-2.0-GA-ROADMAP.md': [+ 'Execution Lanes And Tracking Contract',+ 'docs/architecture/progress-sync-contract.md',+ 'Linear progress',+ 'Every significant merge batch'+ ].join('\n'),'docs/architecture/hud-status-session-control.md': ['context toolCalls activeAgents todos checks cost risk queueState','create resume status stop diff pr mergeQueue conflictQueue',@@ -230,6 +241,23 @@ function runTests() {}})) passed++; else failed++;+ if (test('missing progress sync contract fails without disturbing core tool checks', () => {+ const projectRoot = createTempDir('observability-readiness-sync-fail-');++ try {+ seedMinimalRepo(projectRoot, {+ 'docs/architecture/progress-sync-contract.md': null+ });+ const report = buildReport(projectRoot);++ assert.strictEqual(report.ready, false);+ assert.ok(report.checks.some(check => check.id === 'progress-sync-contract' && !check.pass));+ assert.ok(report.checks.some(check => check.id === 'loop-status-live-signal' && check.pass));+ } finally {+ cleanup(projectRoot);+ }+ })) passed++; else failed++;+console.log('\nResults:');console.log(` Passed: ${passed}`);console.log(` Failed: ${failed}`);