Skip to content

armgit / ECC

Public Imported from GitHub
0

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

docs: add discussion response playbook

Affaan Mustafa12ac22e6747c
diff --git a/docs/ECC-2.0-GA-ROADMAP.md b/docs/ECC-2.0-GA-ROADMAP.md
index 6a0d97b7e..3e98cf09c 100644
--- a/docs/ECC-2.0-GA-ROADMAP.md
+++ b/docs/ECC-2.0-GA-ROADMAP.md
@@ -36,7 +36,9 @@ As of 2026-05-18:
`affaan-m/everything-claude-code` has 58 total discussions and 0 without
maintainer touch after May 15 maintainer updates on #73 and #1239; AgentShield,
JARVIS, ECC Tools, and the ECC Tools website have discussions disabled or 0
- total discussions.
+ total discussions. `docs/architecture/discussion-response-playbook.md` now
+ supplies the ITO-59 response categories, public templates, security-escalation
+ path, and readback rules for future discussion batches.
- The current Linear roadmap contains 16 issue lanes (`ITO-44` through
`ITO-59`) and five milestones: Security and Access Baseline, ECC 2.0 Preview
and Publication, AgentShield Enterprise Iteration, ECC Tools Next-Level
@@ -696,7 +698,7 @@ is not complete unless the evidence column exists and has been freshly verified.
| --- | --- | --- | --- |
| Keep public PRs below 20 | Repo-family PR recheck | 0 open PRs across `everything-claude-code`, AgentShield, JARVIS, `ECC-Tools/ECC-Tools`, and `ECC-Tools/ECC-website` on 2026-05-18 after merging PR #1976 and refreshing platform audit evidence | Complete |
| Keep public issues below 20 | Repo-family issue recheck | 0 open issues across `everything-claude-code`, AgentShield, JARVIS, `ECC-Tools/ECC-Tools`, and `ECC-Tools/ECC-website` on 2026-05-18 after the live platform audit refresh | Complete |
-| Manage repository discussions | Repo-family discussion recheck | Platform audit reports 0 discussion maintainer-touch gaps and 0 answerable Q&A missing accepted answers; trunk still has 58 total discussions | Complete |
+| Manage repository discussions | Repo-family discussion recheck plus response playbook | Platform audit reports 0 discussion maintainer-touch gaps and 0 answerable Q&A missing accepted answers; trunk still has 58 total discussions; `docs/architecture/discussion-response-playbook.md` distinguishes support, maintainer coordination, stale/concluded, release, informational, and security-sensitive response paths | Complete |
| Manage PR discussions | PR review/comment closure plus merge/close state | ECC #1976 merged after maintainer follow-up validation; no open tracked PRs remain | Complete |
| Salvage useful stale work | `docs/stale-pr-salvage-ledger.md` plus `docs/legacy-artifact-inventory.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; #1687, #1609, #1563, #1564, and #1565 localization tails are attached to Linear ITO-55 for language-owner review and no automatic import remains release-blocking | Complete; repeat legacy scan before release |
| 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 18 evidence records queue-zero state, #1970/#1971/#1972/#1976 merge batch, supply-chain recheck, defensive-deny IOC scanner hardening, npm no-lifecycle install/audit/signature gates, Linear sync, refreshed operator dashboard, provider-guard validation, ECC-Tools Wrangler OAuth billing readback evidence, successful current-head CI on `04d4d819`, and detached clean-worktree preview-pack smoke digest `59bbf2630a44` | Needs final release approval |
diff --git a/docs/architecture/discussion-response-playbook.md b/docs/architecture/discussion-response-playbook.md
new file mode 100644
index 000000000..e487dcdb8
--- /dev/null
+++ b/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.
diff --git a/docs/releases/2.0.0-rc.1/publication-readiness.md b/docs/releases/2.0.0-rc.1/publication-readiness.md
index ba4b66b3d..5cf1b4b87 100644
--- a/docs/releases/2.0.0-rc.1/publication-readiness.md
+++ b/docs/releases/2.0.0-rc.1/publication-readiness.md
@@ -106,7 +106,7 @@ Record the exact commit SHA and command output before any publication action:
| Release surface | `node tests/docs/ecc2-release-surface.test.js` | 0 failures | `97567a91` evidence refresh: 21/21 passed after public-path sanitization |
| Optional Rust surface | `cd ecc2 && cargo test` | 0 failures or explicit deferral | `publication-evidence-2026-05-16.md`: 462/462 passed, existing warnings only |
| Queue baseline | `node scripts/platform-audit.js --json` across trunk, AgentShield, JARVIS, ECC Tools, and ECC website | Under 20 open PRs and under 20 open issues | `97567a91`: platform audit ready, 0 open PRs, 0 open issues, 0 conflicting PRs, and 0 blocking dirty files |
-| Discussion baseline | `node scripts/platform-audit.js --json` and `node scripts/discussion-audit.js --json` | No unmanaged active discussion queue and no answerable Q&A missing an accepted answer | `97567a91`: platform audit sampled 58 trunk discussions, 0 needing maintainer touch, 0 answerable discussions missing accepted answer |
+| Discussion baseline | `node scripts/platform-audit.js --json` and `node scripts/discussion-audit.js --json` | No unmanaged active discussion queue and no answerable Q&A missing an accepted answer | `97567a91`: platform audit sampled 58 trunk discussions, 0 needing maintainer touch, 0 answerable discussions missing accepted answer; `docs/architecture/discussion-response-playbook.md` records response templates and security escalation rules |
| Linear roadmap | Linear project and issue readback | Detailed roadmap exists with release, security, AgentShield, ECC Tools, legacy, and observability lanes | May 18 Linear comments include ITO-57 `3fe5b2b7-c4fe-401c-a317-b40d72119cb3`; earlier evidence records the project and 16 issue lanes |
| Operator readiness dashboard | `npm run operator:dashboard -- --json` | Current queue state mapped to macro-goal deliverables and incomplete gaps | `97567a91`: generated May 18 dashboard is committed, platform audit ready true, 0 open PRs, 0 open issues, 0 discussion gaps, and publication gates still approval-gated |
| Release URL ledger | `docs/releases/2.0.0-rc.1/release-url-ledger-2026-05-18.md` plus placeholder-marker scan | Live links and approval-gated links are separated before announcement copy is posted | Ledger records public repo/docs/CI/supply-chain/npm/OpenAI Codex documentation URLs and blocks GitHub release/npm/plugin/billing/social URLs until approval-gated checks pass |
diff --git a/tests/docs/ecc2-release-surface.test.js b/tests/docs/ecc2-release-surface.test.js
index 7f83b233e..7caf2ff66 100644
--- a/tests/docs/ecc2-release-surface.test.js
+++ b/tests/docs/ecc2-release-surface.test.js
@@ -231,6 +231,7 @@ test('launch checklist records the ecc2 alpha version policy', () => {
test('publication readiness checklist gates public release actions on evidence', () => {
const source = read('docs/releases/2.0.0-rc.1/publication-readiness.md');
const may15Evidence = read('docs/releases/2.0.0-rc.1/publication-evidence-2026-05-15.md');
+ const discussionPlaybook = read('docs/architecture/discussion-response-playbook.md');
for (const section of [
'## Release Identity Matrix',
@@ -295,6 +296,17 @@ test('publication readiness checklist gates public release actions on evidence',
assert.ok(may15Evidence.includes('| Trunk discussions | GraphQL discussion count and maintainer-touch sweep | 58 total discussions;'));
assert.ok(source.includes('platform audit sampled 58 trunk discussions'));
assert.ok(source.includes('0 needing maintainer touch'));
+ assert.ok(source.includes('discussion-response-playbook.md'));
+ for (const expected of [
+ 'Public Support',
+ 'Maintainer Coordination',
+ 'Stale Or Concluded',
+ 'Release Announcement',
+ 'Security Escalation',
+ 'classified as informational',
+ ]) {
+ assert.ok(discussionPlaybook.includes(expected), `discussion playbook missing ${expected}`);
+ }
assert.ok(may15Evidence.includes('env -u GITHUB_TOKEN'));
assert.ok(may15Evidence.includes('ITO-44'));
assert.ok(may15Evidence.includes('0 open PRs, 0 open issues'));