elias/everything-claude-code
1
0
Fork 0
mirror of https://github.com/affaan-m/everything-claude-code.git synced 2026-05-14 02:10:07 +08:00
Code Issues Packages Projects Releases Wiki Activity
everything-claude-code/docs/architecture/progress-sync-contract.md
Affaan Mustafa 63f9bfc33f
docs: gate ECC progress sync readiness 
Make the ECC 2.0 GitHub/Linear/handoff/roadmap progress-sync model part of the local observability readiness gate instead of leaving it as roadmap prose only.

- add `docs/architecture/progress-sync-contract.md` for GitHub, Linear, handoff, roadmap, and work-items sync
- add a `Tracker Sync` check to `scripts/observability-readiness.js`
- update observability tests with passing and missing-contract coverage
- update observability and GA roadmap docs so the local readiness gate is now 18/18 and records #1848 supply-chain hardening evidence

Validation:
- node tests/scripts/observability-readiness.test.js (9 passed, 0 failed)
- npm run observability:ready -- --format json (18/18, ready true)
- npx markdownlint-cli 'docs/architecture/progress-sync-contract.md' 'docs/architecture/observability-readiness.md' 'docs/ECC-2.0-GA-ROADMAP.md'
- git diff --check
- node tests/docs/ecc2-release-surface.test.js (18 passed)
- node tests/run-all.js (2378 passed, 0 failed)
- GitHub CI for #1849 green across Ubuntu, Windows, and macOS

No release, tag, npm publish, plugin tag, marketplace submission, or announcement was performed.
2026-05-13 00:38:18 -04:00

3.2 KiB
Raw Blame History

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.