winter-super-cli 2026.5.32 → 2026.6.5

package/resources/local/ecc/docs/architecture/discussion-response-playbook.md

@@ -0,0 +1,90 @@
+# Discussion Response Playbook
+
+This playbook turns GitHub Discussions into the same operating queue as PRs,
+issues, Linear work, and release evidence. It is an operator guide, not a
+promise that every informational thread needs a public reply.
+
+## Audit Loop
+
+Run these checks before a release, after a major merge batch, and when Linear
+ITO-59 is refreshed:
+
+```bash
+npm run discussion:audit -- --json
+node scripts/platform-audit.js --json
+```
+
+The queue is current only when:
+
+- discussion fetch errors are explained or fixed;
+- `needsMaintainerTouch` is zero for support-like discussion categories;
+- answerable Q&A discussions either have an accepted answer or a clear routing
+  note; and
+- any product-scope thread is linked to a GitHub issue, Linear issue, roadmap
+  row, or explicit deferral.
+
+Informational threads such as announcements, references, show-and-tell, or
+maintainer-authored updates can remain visible without becoming response debt.
+
+## Categories
+
+| Category | Route | Required readback |
+| --- | --- | --- |
+| Product support or install confusion | Reply with the exact command/doc path; mark accepted answer for Q&A when the fix is complete | Discussion URL plus accepted-answer URL when applicable |
+| Bug report | Ask for a minimal repro, version, harness, and logs; create or link a GitHub issue when reproducible | Issue URL or deferral reason |
+| Feature request | Acknowledge the desired outcome and link the closest roadmap issue; do not imply commitment unless scoped | Linear/GitHub roadmap link |
+| Security concern | Move exploit details and secrets to a private channel; keep the public reply short and non-operational | Private escalation note plus public safety reply |
+| Release or billing question | Answer from the release URL ledger and publication-readiness gates; do not claim unpublished URLs, billing readiness, or plugin availability | Evidence artifact or blocker link |
+| Show-and-tell, reference, or announcement | Leave as informational unless there is a direct question or a product-scope signal | Optional roadmap link if useful |
+| Stale or concluded thread | Summarize the current state and link the durable doc/issue; avoid reviving low-signal threads | Closure note or explicit no-action rationale |
+
+## Templates
+
+### Public Support
+
+Thanks for the report. The current supported path is:
+
+```bash
+<command>
+```
+
+The relevant doc is `<doc path or URL>`. If this does not match your setup,
+please reply with the harness, OS, package manager, and the exact error text.
+
+### Maintainer Coordination
+
+I am routing this into `<issue or Linear key>` so it does not get lost in the
+discussion queue. The next decision is `<specific decision>`. Until that lands,
+the supported workaround is `<workaround or "none">`.
+
+### Stale Or Concluded
+
+This thread looks resolved or superseded by `<doc/issue/release>`. I am leaving
+it visible for history, but it is no longer an active support queue item. New
+repro details should go to `<issue/discussion path>`.
+
+### Release Announcement
+
+The current release status is `<rc/beta/GA state>`. Live URLs are recorded in
+`docs/releases/2.0.0-rc.1/release-url-ledger-2026-05-18.md`. Anything marked
+pending there should not be announced as shipped yet.
+
+### Security Escalation
+
+Thanks for flagging this. Please do not post exploit steps, tokens, customer
+data, or secret values in the public thread. I am routing this through the
+security response path and will keep the public thread limited to safe status
+updates.
+
+## Recording Outcomes
+
+For each high-signal discussion, record one of these outcomes:
+
+- replied publicly and accepted answer read back;
+- linked to a GitHub issue or Linear issue;
+- routed to the security response path;
+- classified as informational; or
+- explicitly deferred with a reason.
+
+Mirror the summary into ITO-59 when the batch closes, and include the counts in
+the next operator dashboard or publication evidence refresh.

package/resources/local/ecc/docs/architecture/evaluator-rag-prototype.md

@@ -0,0 +1,158 @@
+# Evaluator RAG Prototype
+
+ECC 2.0 needs a self-improving harness loop that can learn from real work
+without blindly mutating a user's Claude, Codex, OpenCode, dmux, Zed, or
+terminal setup. This prototype defines the smallest read-only artifact set for
+that loop.
+
+The fixture set lives in
+[`examples/evaluator-rag-prototype/`](../../examples/evaluator-rag-prototype/).
+It started with the May 2026 stale-PR cleanup and salvage lane because that
+lane has real inputs, real accepted work, and real rejected work. The corpus now
+also includes a billing/Marketplace readiness scenario so launch copy cannot
+treat dry-run release evidence or roadmap intent as live billing state. A
+CI-failure diagnosis scenario adds the log-first workflow needed before an
+agent proposes fixes for red checks. A harness-config quality scenario keeps
+MCP, plugin, hook, command, agent, and adapter recommendations tied to the
+adapter matrix before they mutate setup guidance. An AgentShield policy
+exception scenario gates security exceptions on SARIF/report evidence, owner
+fields, expiry state, and remediation-versus-exception decisions. A
+skill-quality evidence scenario requires observed failure or feedback evidence,
+working examples, reference-set gaps, and validation commands before a skill
+amendment can be promoted. A deep-analyzer evidence scenario requires analyzer
+corpus cases, expected-output comparisons, and risk-taxonomy proof before
+repository or commit-analysis behavior can change.
+
+## Reference Pressure
+
+- Meta-Harness: treat the harness itself as an experiment with scenario specs,
+  verifier results, and promoted playbooks.
+- Autocontext: store traces, reports, artifacts, and reusable improvements
+  before changing installed agent assets.
+- Claude HUD: expose context, tools, todos, agent activity, checks, and risk so
+  an evaluator can judge a run after the fact.
+- Hermes Agent: keep skills, memories, scheduler-like follow-ups, and terminal
+  gateway behavior explicit instead of hiding local commands.
+- dmux, Orca, Superset, and Ghast: preserve worktree/session state so parallel
+  agent work can be compared, resumed, or closed cleanly.
+- ECC Tools: route evaluator findings into PR comments, check runs, and Linear
+  backlog items without flooding GitHub.
+
+## Artifact Contract
+
+Every evaluator/RAG run is read-only until a verifier promotes a playbook.
+
+| Artifact | Purpose | Fixture |
+| --- | --- | --- |
+| Scenario spec | Declares the objective, allowed evidence, forbidden actions, and pass/fail gates. | `scenario.json` |
+| Trace | Captures observation, retrieval, proposal, verification, and promotion events. | `trace.json` |
+| Report | Summarizes scores, evidence coverage, risks, and recommended next action. | `report.json` |
+| Candidate playbook | Describes the maintainer-owned workflow that could be reused later. | `candidate-playbook.md` |
+| Verifier result | Accepts or rejects candidates with concrete reasons and rollback notes. | `verifier-result.json` |
+
+The prototype deliberately separates retrieval from action. A run can retrieve
+closed PR diffs, Linear status, CI history, and local docs, but it cannot close,
+merge, publish, tag, or rewrite configs as part of the evaluator pass.
+
+## Phase Model
+
+1. Observe the current queue, dirty worktrees, branch state, open PRs/issues,
+   discussions, CI state, and release gates.
+2. Retrieve relevant reference evidence: stale-salvage ledger rows, prior
+   maintainer PRs, current docs, analyzer findings, CI failures, and harness
+   adapter rules.
+3. Propose one or more playbooks with source attribution and expected
+   validation gates.
+4. Verify each playbook against explicit acceptance and rejection rules.
+5. Promote only the candidate that improves the scenario without widening blast
+   radius.
+6. Record rollback guidance and unresolved manual-review tails.
+
+## First Scenario
+
+The first scenario is `stale-pr-salvage-maintainer-branch`.
+
+It models the rule Affaan set during the May 2026 cleanup: stale closure is
+queue hygiene, not loss of useful work. Useful closed PR work should be ported
+into maintainer-owned PRs with attribution/backlinks, while generated churn,
+bulk localization, and ambiguous translator work stay out of blind
+cherry-picks.
+
+The verifier accepts a maintainer salvage branch that:
+
+- credits source PRs;
+- avoids raw private context and personal paths;
+- does not import stale bulk localization without translator review;
+- records a durable ledger update;
+- runs the same validation gates as a normal code, docs, or catalog change;
+- leaves release publication actions approval-gated.
+
+The verifier rejects a blind cherry-pick proposal that:
+
+- imports stale translation/doc churn wholesale;
+- skips the current catalog/install architecture;
+- lacks attribution;
+- lacks tests or ledger updates;
+- mutates release or plugin publication state.
+
+## Corpus Fixtures
+
+The root fixture files preserve the original
+`stale-pr-salvage-maintainer-branch` prototype. Additional scenarios can live in
+subdirectories when they reuse the same five-artifact contract.
+
+Current corpus:
+
+- `stale-pr-salvage-maintainer-branch`: recovers useful closed PR work through
+  maintainer-owned branches with attribution and validation.
+- `billing-marketplace-readiness`: verifies billing, App, and Marketplace
+  launch claims before public copy says they are live.
+- `ci-failure-diagnosis`: requires failed-job logs, changed-file scope, and a
+  named regression command before a CI fix playbook can be promoted.
+- `harness-config-quality`: requires adapter state, install/onramp path,
+  verification commands, risk notes, and config-preservation behavior before a
+  harness setup recommendation can be promoted.
+- `agentshield-policy-exception`: requires AgentShield SARIF or report
+  evidence, policy-pack source, owner/ticket/scope/expiry fields, and expired
+  exception enforcement before a policy exception can be promoted.
+- `skill-quality-evidence`: requires focused skill scope, observed failure or
+  user-feedback evidence, examples/reference-set coverage, validation commands,
+  and publication safety before a skill amendment can be promoted.
+- `deep-analyzer-evidence`: requires maintained analyzer corpus cases,
+  expected-output comparisons, representative repository/commit histories, and
+  regression commands before deep-analysis behavior can be promoted.
+
+## ECC Tools Mapping
+
+ECC Tools already flags missing RAG/evaluator evidence for retrieval,
+embedding, ranking, and evaluator changes. This prototype gives those checks a
+target shape:
+
+- `scenario.json` maps to analyzer corpus inputs.
+- `trace.json` maps to golden traces and run telemetry.
+- `report.json` maps to PR comment summaries and Linear backlog summaries.
+- `candidate-playbook.md` maps to the suggested follow-up PR body.
+- `verifier-result.json` maps to pass/fail check-run evidence.
+
+Future ECC Tools work should consume these artifacts as fixture shape before it
+adds hosted retrieval or model-backed judging. The local prototype is enough to
+prove the contract before any paid API or vector store is introduced.
+
+## Promotion Rules
+
+A candidate can be promoted only when:
+
+- the verifier result is `accepted`;
+- at least one rejected candidate proves the verifier can say no;
+- every source PR or reference artifact has attribution;
+- the proposed action is maintainer-owned and reversible;
+- validation commands are named;
+- unresolved translator, release, billing, or publication items remain blocked
+  until separately approved.
+
+## Next Expansion
+
+The local evaluator/RAG corpus now covers the current evidence buckets. Future
+work should consume these fixtures from ECC Tools before adding hosted
+retrieval, vector storage, model-backed judging, or automated check-run
+promotion.

package/resources/local/ecc/docs/architecture/harness-adapter-compliance.md

@@ -0,0 +1,105 @@
+# Harness Adapter Compliance Matrix
+
+This matrix is the public onramp for teams that want to use ECC across more
+than one coding harness. It turns the cross-harness architecture into a
+practical scorecard: what works today, what is instruction-only, what needs an
+adapter, and what evidence an operator should collect before trusting a setup.
+
+ECC's durable units stay in shared sources:
+
+- `skills/*/SKILL.md`
+- `rules/`
+- `commands/`
+- `hooks/hooks.json`
+- `scripts/hooks/`
+- MCP reference configs
+- session and observability contracts
+
+Harness-specific files should only adapt loading, event shape, command names,
+or platform limits.
+
+## Compliance States
+
+| State | Meaning |
+| --- | --- |
+| Native | ECC can install or verify the surface directly for this harness. |
+| Adapter-backed | ECC has a thin adapter, plugin, or package surface, but parity differs by harness. |
+| Instruction-backed | ECC can provide the guidance and files, but the harness does not expose the runtime hook/session surface ECC needs for enforcement. |
+| Reference-only | The tool is useful as a design pressure or external runtime, but ECC does not yet ship a direct installer or adapter for it. |
+
+## Matrix
+
+The matrix below is rendered from
+`scripts/lib/harness-adapter-compliance.js` and verified by
+`npm run harness:adapters -- --check`.
+
+<!-- harness-adapter-compliance:matrix-start -->
+| Harness or runtime | State | Supported assets | Unsupported or different surfaces | Install or onramp | Verification command | Risk notes |
+| --- | --- | --- | --- | --- | --- | --- |
+| Claude Code | Native | Claude plugin assets; skills; commands; hooks; MCP config; local rules; statusline-oriented workflows | Claude-native hooks do not imply parity in other harnesses | `./install.sh --profile minimal --target claude`; Claude plugin install | `npm run harness:audit -- --format json`; `node scripts/session-inspect.js --list-adapters` | Avoid loading every skill by default; keep hooks opt-in and inspectable. |
+| Codex | Instruction-backed | `AGENTS.md`; Codex plugin metadata; skills; MCP reference config; command patterns | Native hook enforcement and Claude slash-command semantics are not equivalent | `./install.sh --profile minimal --target codex`; repo-local `AGENTS.md` review | `npm run harness:audit -- --format json` | Treat hooks as policy text unless a native Codex hook surface exists. |
+| OpenCode | Adapter-backed | OpenCode package/plugin metadata; shared skills; MCP config; event adapter patterns | Event names, plugin packaging, and command dispatch differ from Claude Code | OpenCode package or plugin surface from this repo | `node tests/scripts/build-opencode.test.js`; `npm run harness:audit -- --format json` | Keep hook logic in shared scripts and adapt only event shape at the edge. |
+| Cursor | Adapter-backed | Cursor rules; project-local skills; hook adapter; shared scripts | Cursor hook events and rule loading differ from Claude Code | `./install.sh --profile minimal --target cursor` | `node tests/lib/install-targets.test.js`; `npm run harness:audit -- --format json` | Cursor adapters must preserve existing project rules and avoid silent overwrite. |
+| Gemini | Instruction-backed | Gemini project-local instructions; shared skills; rules; compatibility docs | No full ECC hook parity; ecosystem ports must document drift from upstream ECC | `./install.sh --profile minimal --target gemini` | `node tests/lib/install-targets.test.js` | Treat Gemini ports as ecosystem adapters until validated end to end inside Gemini CLI. |
+| Zed | Adapter-backed | Zed project settings; flattened project rules; shared skills; commands; agents | Zed external agents and native Agent Panel permissions are not Claude hooks | `./install.sh --profile minimal --target zed` | `node tests/lib/install-targets.test.js`; `npm run harness:audit -- --format json` | Keep project settings conservative and do not copy BYOK/OpenRouter secrets into `.zed/`. |
+| dmux | Adapter-backed | session snapshots; tmux/worktree orchestration status; handoff exports | dmux is an orchestration runtime, not an install target for skills/rules | `node scripts/session-inspect.js --list-adapters`; dmux session target inspection | `node tests/lib/session-adapters.test.js` | Treat dmux events as session/runtime signals, not as a replacement for repo validation. |
+| Orca | Reference-only | worktree lifecycle; review state; notification; provider-identity design pressure | No ECC installer or direct adapter today | Use as a comparison target for worktree/session state requirements | `npm run observability:ready` | Do not import product-specific assumptions; convert lessons into ECC event fields. |
+| Superset | Reference-only | workspace presets; parallel-agent review loops; worktree isolation design pressure | No ECC installer or direct adapter today | Use as a comparison target for workspace preset taxonomy | `npm run observability:ready` | Keep ECC portable; do not require a desktop workspace to get basic value. |
+| Ghast | Reference-only | terminal-native pane grouping; cwd grouping; search; notifications | No ECC installer or direct adapter today | Use as a comparison target for terminal-first session grouping | `node scripts/session-inspect.js --list-adapters` | Preserve terminal ergonomics before adding visual UI assumptions. |
+| Terminal-only | Native | skills; rules; commands; scripts; harness audit; observability readiness; handoffs | No external UI, no automatic session control unless scripts are run explicitly | Clone repo; run commands directly; use minimal profile for project installs | `npm run harness:audit -- --format json`; `npm run observability:ready` | This is the fallback contract; every higher-level adapter should degrade to it. |
+<!-- harness-adapter-compliance:matrix-end -->
+
+## Scorecard Onramp
+
+Use this sequence before asking ECC to make a team or repo setup more
+autonomous:
+
+```bash
+npm run harness:adapters -- --check
+npm run harness:audit -- --format json
+npm run observability:ready
+node scripts/session-inspect.js --list-adapters
+node scripts/loop-status.js --json --write-dir .ecc/loop-status
+```
+
+Read the result as a setup scorecard, not a product badge:
+
+- `harness:adapters -- --check` proves this public matrix still matches the
+  adapter source data and required evidence fields.
+- `harness:audit` scores tool coverage, context efficiency, quality gates,
+  memory persistence, eval coverage, security guardrails, and cost efficiency.
+- `observability:ready` proves the repo still exposes the local status,
+  session, tool-activity, risk-ledger, and release-onramp signals.
+- `session-inspect --list-adapters` shows which session surfaces are actually
+  inspectable in the current environment.
+- `loop-status --json` creates a machine-readable handoff/status payload for
+  longer autonomous runs.
+
+## Data-Backed Scorecard Contract
+
+Each adapter record exposes:
+
+- `id`
+- `state`
+- `supported_assets`
+- `unsupported_surfaces`
+- `install_or_onramp`
+- `verification_commands`
+- `risk_notes`
+- `last_verified_at`
+- `owner`
+- `source_docs`
+
+The validator fails if a public adapter claim has no install path,
+verification command, risk note, owner, source doc, or verification date.
+
+## Operating Rules
+
+- Prefer small, additive adapters over harness-specific forks of the same
+  workflow.
+- Do not call a harness native until the adapter has an install path and a
+  verification command.
+- Keep Codex, Gemini, and Zed surfaces honest when enforcement is
+  instruction-backed rather than runtime-backed.
+- Treat reference-only tools as design pressure until ECC has a direct adapter.
+- Keep the terminal-only path healthy; it is the portability floor.

package/resources/local/ecc/docs/architecture/hud-status-session-control.md

@@ -0,0 +1,80 @@
+# HUD Status And Session Control Contract
+
+This contract defines the portable status payload ECC uses for local operator
+surfaces, handoffs, and future HUDs. It is intentionally harness-neutral: a
+Claude Code statusline, Codex pane, dmux session, OpenCode run, or terminal-only
+workflow can emit partial data without changing field names.
+
+The canonical example lives at
+[`examples/hud-status-contract.json`](../../examples/hud-status-contract.json).
+
+## Payload Shape
+
+Every status payload uses `schema_version: "ecc.hud-status.v1"` and keeps these
+top-level sections stable:
+
+| Field | Purpose | Primary Source |
+|---|---|---|
+| `context` | Model, harness, repo, branch, worktree, session id, and context-window pressure | statusline stdin, git, session adapters |
+| `toolCalls` | Recent tool counts, pending calls, stale calls, and last tool event | `loop-status`, `tool-usage.jsonl`, hook bridge |
+| `activeAgents` | Current workers/subagents, runtime state, branch, worktree, objective, and handoff paths | dmux/orchestration snapshots |
+| `todos` | Current in-progress task and todo counts | Claude todos, local task files, plan metadata |
+| `checks` | Local and remote validation status with command/check URLs when available | CI, local commands, release gates |
+| `cost` | Session spend, token counts, budget, and trend | cost tracker, metrics bridge |
+| `risk` | Attention state, conflict pressure, stale calls, dirty worktree, and manual-review flags | readiness gates, git, queue state |
+| `queueState` | GitHub PR/issue/discussion counts, conflict queue, merge queue, and stale-salvage queue | GitHub sync, work items |
+| `sessionControls` | Supported operator actions for the current target | ECC CLI, dmux, git/GitHub |
+| `sync` | Linear, GitHub, and handoff publication state | status updates, work items, handoff writer |
+
+Fields can be `null`, empty arrays, or `"unknown"` when a harness cannot expose
+the signal. Producers should not invent incompatible names. Consumers should
+render missing sections as unavailable, not as green.
+
+## Session Controls
+
+The minimum session-control vocabulary is:
+
+| Control | Meaning |
+|---|---|
+| `create` | Start a new isolated run, worktree, or orchestration plan |
+| `resume` | Reattach to an existing session or historical target |
+| `status` | Emit the current payload without mutating state |
+| `stop` | Request a graceful stop or mark the session completed |
+| `diff` | Show current working-tree or worker diff |
+| `pr` | Open or inspect the linked pull request |
+| `mergeQueue` | Show merge-ready, blocked, and waiting-check items |
+| `conflictQueue` | Show dirty/conflicting PRs or worktrees needing integration |
+
+`sessionControls.supported` lists the controls available for the current
+harness. `sessionControls.blocked` explains unavailable controls, for example a
+missing GitHub token, no tmux session, or a read-only adapter.
+
+## Sync Contract
+
+The sync section separates durable trackers:
+
+- `Linear` records project status update id, health, and whether issue creation
+  is blocked by workspace capacity.
+- `GitHub` records the current repo, PR/issue/discussion queue counts, and the
+  latest merged or open PR tied to the session.
+- `handoff` records the durable Markdown handoff path and whether it has been
+  written after the latest batch.
+
+This makes real-time progress tracking explicit without requiring every run to
+create Linear issues or GitHub comments. When Linear issue capacity is blocked,
+the status payload can still prove progress through project updates and repo
+handoffs.
+
+## Current Implementations
+
+- `ecc status --json` exposes readiness, active sessions, skill runs, install
+  health, governance, and linked work items from the SQLite state store.
+- `ecc loop-status --json --write-dir <dir>` writes live transcript snapshots
+  and attention signals for long-running loops.
+- `ecc session-inspect <target> --write <path>` emits canonical session
+  snapshots from dmux and Claude-history adapters.
+- `scripts/hooks/ecc-statusline.js` renders compact model, task, cost, tool,
+  file, duration, directory, and context pressure signals inside Claude Code.
+
+The `ecc.hud-status.v1` payload is the common outer contract these surfaces can
+project into before ECC grows a dedicated full-screen HUD.

package/resources/local/ecc/docs/architecture/observability-readiness.md

@@ -0,0 +1,85 @@
+# ECC 2.0 Observability Readiness
+
+ECC 2.0 should be observable before it becomes more autonomous. The local
+default is an opt-in, repo-owned readiness gate that checks whether the core
+signals are present without sending telemetry anywhere.
+
+Run:
+
+```bash
+npm run observability:ready
+node scripts/observability-readiness.js --format json
+```
+
+The gate is deterministic and safe to run in CI. It only checks repository
+files and reports whether the release surface can expose the signals an
+operator needs.
+
+## Signal Model
+
+- Live status: `scripts/loop-status.js` can emit JSON, watch active loops, and
+  write snapshots for dashboards or handoffs.
+- HUD/status contract: `docs/architecture/hud-status-session-control.md` and
+  `examples/hud-status-contract.json` define the portable payload for context,
+  tool calls, active agents, todos, checks, cost, risk, queues, session
+  controls, and tracker sync.
+- Session traces: `scripts/session-inspect.js` can inspect Claude, dmux, and
+  adapter-backed sessions, then write canonical snapshots.
+- Harness baseline: `scripts/harness-audit.js` provides a repeatable scorecard
+  for tool coverage, context efficiency, quality gates, memory persistence,
+  eval coverage, security guardrails, and cost efficiency.
+- Tool activity: `scripts/hooks/session-activity-tracker.js` records local
+  `tool-usage.jsonl` events that ECC2 can sync.
+- Risk ledger: `ecc2/src/observability/mod.rs` scores tool calls and stores a
+  paginated 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.
+- Release safety: `docs/releases/2.0.0-rc.1/publication-readiness.md`,
+  post-hardening evidence, supply-chain incident response, workflow-security
+  validation, npm pack checks, and release-surface tests must be present before
+  any public tag, package publish, plugin submission, or announcement action.
+
+## Reference Pressure
+
+The current agent-tooling ecosystem is converging on the same operating needs:
+
+- dmux, Orca, and Superset emphasize isolated worktrees plus one place to see
+  agent state and merge/review work.
+- Claude HUD makes context, tool activity, agent activity, and todo progress
+  visible inside the coding loop.
+- Autocontext records every run as durable traces, reports, artifacts, and
+  reusable improvements.
+- Meta-Harness treats the harness itself as something to evaluate and improve,
+  which requires clean logs of proposer behavior and outcomes.
+- Zed and OpenCode emphasize agent control surfaces, reviewable changes, and
+  harness-specific configuration that should still preserve portable project
+  knowledge.
+
+ECC's answer is not a hosted analytics dependency by default. The first
+release-candidate gate is local and file-backed. Hosted telemetry can come
+later, but only after the local event model is useful enough to trust.
+
+## Operator Workflow
+
+1. Run `npm run observability:ready`.
+2. Run `npm run harness:audit -- --format json` for the broader harness
+   scorecard.
+3. Run `node scripts/loop-status.js --json --write-dir .ecc/loop-status`
+   during longer autonomous batches.
+4. Review `examples/hud-status-contract.json` before wiring a new HUD or
+   operator dashboard.
+5. Run `node scripts/session-inspect.js --list-adapters` to confirm which
+   session surfaces are available.
+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 handoff
+   review before increasing autonomy.
+8. Re-run the release-safety evidence checks before any public release action:
+   publication readiness, supply-chain incident response, workflow-security
+   validation, package surface, and release-surface tests.
+
+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, a local risk ledger, and a progress-sync contract that
+keeps GitHub, Linear, handoffs, and roadmap evidence from drifting apart.

package/resources/local/ecc/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.

package/resources/local/ecc/docs/business/metrics-and-sponsorship.md

@@ -0,0 +1,74 @@
+# Metrics and Sponsorship Playbook
+
+This file is a practical script for sponsor calls and ecosystem partner reviews.
+
+## What to Track
+
+Use four categories in every update:
+
+1. **Distribution** — npm packages and GitHub App installs
+2. **Adoption** — stars, forks, contributors, release cadence
+3. **Product surface** — commands/skills/agents and cross-platform support
+4. **Reliability** — test pass counts and production bug turnaround
+
+## Pull Live Metrics
+
+### npm downloads
+
+```bash
+# Weekly downloads
+curl -s https://api.npmjs.org/downloads/point/last-week/ecc-universal
+curl -s https://api.npmjs.org/downloads/point/last-week/ecc-agentshield
+
+# Last 30 days
+curl -s https://api.npmjs.org/downloads/point/last-month/ecc-universal
+curl -s https://api.npmjs.org/downloads/point/last-month/ecc-agentshield
+```
+
+### GitHub repository adoption
+
+```bash
+gh api repos/affaan-m/everything-claude-code \
+  --jq '{stars:.stargazers_count,forks:.forks_count,contributors_url:.contributors_url,open_issues:.open_issues_count}'
+```
+
+### GitHub traffic (maintainer access required)
+
+```bash
+gh api repos/affaan-m/everything-claude-code/traffic/views
+gh api repos/affaan-m/everything-claude-code/traffic/clones
+```
+
+### GitHub App installs
+
+GitHub App install count is currently most reliable in the Marketplace/App dashboard.
+Use the latest value from:
+
+- [ECC Tools Marketplace](https://github.com/marketplace/ecc-tools)
+
+## What Cannot Be Measured Publicly (Yet)
+
+- Claude plugin install/download counts are not currently exposed via a public API.
+- For partner conversations, use npm metrics + GitHub App installs + repo traffic as the proxy bundle.
+
+## Suggested Sponsor Packaging
+
+Use these as starting points in negotiation:
+
+- **Pilot Partner:** `$200/month`
+  - Best for first partnership validation and simple monthly sponsor updates.
+- **Growth Partner:** `$500/month`
+  - Includes roadmap check-ins and implementation feedback loop.
+- **Strategic Partner:** `$1,000+/month`
+  - Multi-touch collaboration, launch support, and deeper operational alignment.
+
+## 60-Second Talking Track
+
+Use this on calls:
+
+> ECC is now positioned as an agent harness performance system, not a config repo.
+> We track adoption through npm distribution, GitHub App installs, and repository growth.
+> Claude plugin installs are structurally undercounted publicly, so we use a blended metrics model.
+> The project supports Claude Code, Cursor, OpenCode, and Codex app/CLI with production-grade hook reliability and a large passing test suite.
+
+For launch-ready social copy snippets, see [`social-launch-copy.md`](./social-launch-copy.md).