Repository navigation
docs: visuals, reader-facing rewrite, methodology conformance, protected-artifacts check - #21
Merged
Merged
Conversation
Install page: dependency table and a table of what install adds versus what commands write. Workflow page: per-stage reads, writes, executable checks and human decisions. Design-gate page: canary and evidence/PASS flowcharts with their failure paths. Guide: component map of which entrypoints call the agents and gate tools. Plugin README: Node is no longer claimed to come with Claude Code; Build and Test gate rows match the stage files; link to the map. These five pages also carry the earlier uncommitted documentation rewrite of the same files. Audit records, proposals, verification and preview assets are under docs/plans/2026-09-04-documentation-visuals/. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q5VN7i5DVhkqXfSHwVZttx
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Q5VN7i5DVhkqXfSHwVZttx
README leads with the mascot and the problem statement, then the six stages and the refusing design gate; quickstart, when-to-use, plan-workspace and interop are rewritten against the inventory in docs/documentation-inventory.md, which records each page's reader, the facts it must preserve and the discrepancies found against the scripts and stage files (quick-plan is an audited draft, not a Stage 2 pass; the validator checks MET citations, not meaning; install scope must be explicit; interop no longer claims nobody else reads plan folders). The help, plan-status, quick-audit and Stage 2 surfaces gain the kitchen translation next to each canonical gate token (PASS, NOT PASS, MET, UNMET, N_A); the tokens themselves are unchanged. Assets: only the two PNGs the pages reference and the prompts that produced them. The other mascot and banner variants stay out of the tree. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fx5CCdiv5HdUrakHhCfMAq
METHODOLOGY.md now separates active instruction, narrow executable checks, conditional inputs, compatibility paths and retired products. Claims about the removed scanner, scoring, guard and CI-generator components are labelled historical; enforced/guaranteed/proven wording is narrowed to what the evidence validator, canary and hooks actually check; the critical-test waiver and one-page Design checkpoint claims are withdrawn; citations are replaced with primary sources. Every heading, anchor, section number, lint rule text and historical weight is retained. Outcome: qualified conformance, not an unconditional PASS. Six owner decisions (D1-D6: shortcut gate contract, test-author ownership, external input writes, release completion meaning, immutable records versus living state, historical-match fix reuse) are recorded in findings.md and not resolved here. Audit records, traceability matrix, source audit, industry alignment and verification are under docs/plans/2026-09-04-methodology-conformance/. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fx5CCdiv5HdUrakHhCfMAq
snapshots/ and changes/CR-*.md have been declared immutable in prose for three releases with nothing enforcing it. .github/protected-artifacts.sh checks the one boundary every route to the tree crosses, the git diff: additions pass; modifications, deletions, renames and type changes fail. No bypass flag. Modes: local (staged index or working tree vs HEAD) and ci, which picks its range from the GitHub event. Pull requests diff from the merge-base so base-branch commits are not blamed on the PR; pushes refuse a zero or unresolvable before-SHA (exit 2) instead of narrowing the range. The suite job checks out with fetch-depth 0 for that reason. tests/protected-artifacts-test.sh runs 20 cases against scratch clones and is layer 8 of tests/run-all.sh; the testing methodology note lists it. The suite's single-layer argument parser still accepts only 1-7; that pre-existing mismatch is not addressed here. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01Fx5CCdiv5HdUrakHhCfMAq
krwhynot
changed the title
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
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.
Five commits on top of the 11.0.1 release, all documentation and CI; no plugin behavior changes.
Documentation visuals (
35d3854,9dd785f)The first six diagrams from the visuals audit: install tables, per-stage workflow table, canary and evidence/PASS flowcharts on the design-gate page, and the component map in the guide. The plugin README no longer claims Node ships with Claude Code. Records under
docs/plans/2026-09-04-documentation-visuals/. V5 through V11 remain drafts there.Reader-facing rewrite (
35dff3d)README, quickstart, when-to-use, plan-workspace and interop rewritten in the head-chef voice against
docs/documentation-inventory.md, which records each page's reader, the facts it must preserve and the discrepancies found against the scripts and stage files. The help, plan-status, quick-audit and Stage 2 surfaces add the kitchen translation beside each canonical gate token; the tokens are unchanged. Only the two referenced PNGs and their prompts are committed.Methodology conformance audit (
520b756)METHODOLOGY.mdnow separates active instruction from narrow executable checks and retired products, and withdraws enforcement claims the code does not back. Every heading, anchor, lint rule and historical weight is retained. Outcome is qualified conformance, not an unconditional PASS: six owner decisions (D1 to D6) are recorded indocs/plans/2026-09-04-methodology-conformance/findings.mdand left open.Protected artifacts check (
261f8b1).github/protected-artifacts.shrefuses modification, deletion, rename or retype ofdocs/plans/*/snapshots/**anddocs/plans/*/changes/CR-*.mdat the git diff; additions pass; no bypass flag. Newprotected-artifactsjob insuite.ymlwithfetch-depth: 0; 20-case test as suite layer 8.Verification
bash tests/run-all.sh: 8 of 8 layers passed on the working tree before committing.bash .github/protected-artifacts.sh local --worktree: exit 0.tests/run-all.shruns layers 1 to 8 by default but its single-layer argument parser accepts only 1 to 7.🤖 Generated with Claude Code
https://claude.ai/code/session_01Fx5CCdiv5HdUrakHhCfMAq