From 12ac22e6747c6cfa6a6038030f2f56671edfa634 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Mon, 18 May 2026 14:39:11 -0400 Subject: [PATCH] docs: add discussion response playbook --- docs/ECC-2.0-GA-ROADMAP.md | 6 +- .../discussion-response-playbook.md | 90 +++++++++++++++++++ .../2.0.0-rc.1/publication-readiness.md | 2 +- tests/docs/ecc2-release-surface.test.js | 12 +++ 4 files changed, 107 insertions(+), 3 deletions(-) create mode 100644 docs/architecture/discussion-response-playbook.md diff --git a/docs/ECC-2.0-GA-ROADMAP.md b/docs/ECC-2.0-GA-ROADMAP.md index 6a0d97b7..3e98cf09 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 00000000..e487dcdb --- /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 + +``` + +The relevant doc is ``. 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 `` so it does not get lost in the +discussion queue. The next decision is ``. Until that lands, +the supported workaround is ``. + +### Stale Or Concluded + +This thread looks resolved or superseded by ``. I am leaving +it visible for history, but it is no longer an active support queue item. New +repro details should go to ``. + +### Release Announcement + +The current release status is ``. 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 ba4b66b3..5cf1b4b8 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 7f83b233..7caf2ff6 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'));