AL-33: strip GSD vocabulary leaks + wire external-audience-auditor#27
Merged
Conversation
…s (AL-33) Externally-facing artifacts inherited internal GSD/Jira/requirement vocabulary (AL-XX, BHV/RT/AGT/CLI/CAT/INST IDs, Phase numbers, bare ADR-NN refs, .planning/ paths) by accident — copy-pasted from internal phase summaries or written while in plan-execute mode. Public readers (and the project owner excerpting into blog/email/agentlinux.org) cannot resolve those. This pass strips the leaks and rephrases the surrounding prose. Files modified: - README.md: drop AGT-02 token, drop .planning/REQUIREMENTS.md link, contextualize bare ADR-006 reference with the decision-record link. - CONTRIBUTING.md: drop the BHV/RT/AGT/CLI/CAT/INST/HRN/TST/DOC-XX list from PR guidance; rephrase to "describe what behavior changed and which bats test files cover it"; drop "cites the relevant requirement ID". - docs/STABILITY-MODEL.md: replace bare ADR-011 TL;DR token with a one-breath substance + decision-record link; drop AGT-02 / TST-08 / Phase 6 / ADR-012 tokens; clean up bare ADR-NNN prefixes in Related list (substance is already in the link text). - docs/README.md: drop "GSD workflow state" from the lede (internal harness vocabulary); drop "ADR-001..ADR-010 seeded in Phase 1"; rephrase HARNESS.md section descriptors to plain prose. - docs/internals/playwright.md: contextualize bare ADR-012 reference with a named decision-record link. - plugin/cli/src/index.ts: drop "(CLI-06)" from the `agentlinux upgrade` Commander description and "(CLI-07)" from the `agentlinux pin` Commander description — these surface in `--help` output. Kept on purpose: - Catalog agent name `gsd` and the npm package name `get-shit-done-cc` — these are the actual installable identifiers users type. - "GSD workflow CLI for Claude Code" in catalog example output and in catalog.json — that's the user-visible product description. - Source-comment references inside plugin/**, packaging/**, tests/** — out of audit scope per the external-audience-auditor (only user-visible strings are audited under packaging/, not source comments). - ADR-NNN references inside docs/decisions/** — internal-only by audit scope (cross-refs between ADRs are appropriate). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…ch (AL-33) Adds a new dispatch row under "Review Loop" for externally-facing artifacts (top-level README, CONTRIBUTING, docs/internals/, docs/HARNESS.md, docs/STABILITY-MODEL.md, docs/README.md, public release notes, blog/email drafts, agentlinux.org copy, user-visible packaging strings). The external-audience-auditor agent flags leakage of internal vocabulary — AL Jira keys, GSD plan filenames, BHV/RT/AGT/CLI/CAT/INST/HRN/TST/DOC requirement IDs, Phase/Plan numbering, bare ADR cross-refs, GSD orchestrator/executor/planner vocabulary, Claude Code self-references — that public readers cannot resolve. The new row sits alongside (not replacing) the per-file-type reviewers; for externally-facing docs both fire. Skip-list documented inline so contributors know which trees are internal-only by audit scope (.planning/, docs/decisions/, docs/audits/, docs/research/, .claude/, source under plugin/packaging/tests/). This complements the leak-scrubbing pass in the prior commit: the auditor catches future regressions automatically when externally-facing artifacts appear in the review scope. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Two findings from the post-merge review pass: 1. CLAUDE.md dispatch row was 11 lines vs ~1 line for siblings — split into a compact bullet plus a short paragraph below the dispatch list, mirroring the dev-docs-auditor explanatory paragraph pattern already present in the file. 2. STABILITY-MODEL.md TL;DR blockquote display text said `docs/decisions/011-...` while the relative link target was `decisions/011-...`. Aligned both to `decisions/...` since the file is itself in `docs/`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
.planning/paths) from user-facing surfaces — README, CONTRIBUTING,docs/internals/playwright.md,docs/STABILITY-MODEL.md,docs/README.md, and theagentlinux upgrade/agentlinux pinCommander help strings.external-audience-auditorreviewer into theCLAUDE.mdReview Loop dispatch table as a new "Externally-facing artifacts" row, with an explicit skip-list (.planning/,docs/decisions/,docs/audits/,docs/research/,.claude/, source comments underplugin//packaging//tests/).Closes AL-33.
Why
Internal workflow vocabulary (GSD plan filenames, requirement IDs like
CLI-06,Phase 4, bareADR-NNNtokens) was leaking into public-facing artifacts where readers cannot resolve them. The fix is twofold: (1) strip the existing leaks once, (2) wire a reviewer agent so the next leak is caught at the PR boundary instead of in published copy.Verify
agentlinux upgrade --helpandagentlinux pin --helpno longer surface(CLI-06)/(CLI-07)parentheticals.Kept on purpose
gsdand npm packageget-shit-done-cc— public installable identifiers users type at the CLI.plugin//packaging//tests/carrying requirement-ID references — explicitly out of audit scope (only user-visible strings are in scope).Co-Authored-By: Claudetrailers in commit messages — project convention; commit messages are not user-visible per the auditor's rules.Deferred
docs/HARNESS.mdis in the auditor's scope but its phase / ADR / requirement-ID load is structurally part of what the document explains. A separate ticket is the right vehicle for that scrub.Reviewers run before merge request
external-audience-auditor(self-applied on post-fix tree)technical-writerai-deslop463b95aTest plan
agentlinux --help/agentlinux upgrade --help/agentlinux pin --helpshow clean public-facing proseREADME.mdrenders without broken links on GitHubdocs/STABILITY-MODEL.mdTL;DR blockquote link resolves🤖 Generated with Claude Code