Skip to content

docs: describe shipped behavior, define reviewer enums, guard locale parity (2.1.2) - #62

Merged
wei18 merged 7 commits into
mainfrom
docs/health-check
Nov 14, 2026
Merged

wei18 merged 7 commits into
mainfrom
docs/health-check

Conversation

@wei18

@wei18 wei18 commented Nov 14, 2026 •

Copy link
Copy Markdown
Owner

What

Documentation and reviewer-prompt health check. The action's code is unchanged; the only code added is a test.

  • docs/*/design.md (5 locales): describes shipped behavior only. Removed retry with backoff, the report.issue_label config key, perceptual hashing and other claims the code does not implement; completed the config schema (reviewers.<name>.paths, .rubric); code blocks are now byte-identical across locales.
  • reviewers/en and reviewers/zh-TW: every enum value is defined in a table (category, severity, confidence, ssot_direction incl. stale_a / stale_b), related is defined, each rubric bullet names its category, and the "target files only" rule no longer reads as a ban on reading other files. The JSON contract is unchanged: no field renamed, added or removed.
  • test/locale-parity.test.ts (new): reviewers en/zh-TW stay in structural and code-token parity, enum tables equal the constants in src/types.ts, rubric categories are valid, prompt examples pass the validators, docs code blocks and file sets match across the five locales.
  • docs/<locale>/plans/: 20 locale copies of archived plans collapsed into one copy at docs/archive/plans/ with a "historical record, do not execute" banner (about 15k lines removed).
  • CLAUDE.md: adds the change and release procedure and the locale sync rules.
  • Small accuracy fixes in README (5 locales), SKILL.md, SECURITY.md, CONTRIBUTING.md, and descriptions/comments in action.yml and .github/.
  • Plugin version 2.1.1 to 2.1.2 (plugin.json, marketplace.json), because shipped reviewer prompts changed.

Why

Two independent audits (a deep review and a cold-reader pass) found docs claiming behavior the code lacks, and reviewer prompts with undefined enum values that a small model would have to guess. The goal is docs and prompts that a small model can follow as well as a strong one.

Checklist

  • npm ci && npm run build && npm test pass locally: 29 files, 208 tests
  • Mutation checks: extra or missing enum row, category typo, unterminated fence, differing enum token, extra locale doc, changed YAML in a block each fail the new test; a stray .DS_Store does not
  • .github/ and action.yml changes are comments and descriptions only
  • Both version files say 2.1.2
  • CI green on this PR
  • Self-audit run on this branch (run 43602887514, head a3b006c): all six reviewers and synthesis returned status: ok with output that passed the validators. Finding counts: 0 on this branch; the last run on main (2026-11-09) had 2 low-severity code_hygiene findings in files this PR does not touch. One run does not show whether that is model variance or lower recall from the new prompt wording.

After merge

Tag v2.1.2 and publish a release. The rolling v2 tag is not moved in this step: that waits for the owner, given the open recall question above.

Open items for the owner (no action needed to merge)

  • src/config.ts still parses the unused report.issue_label key, and src/prompt-bundle.ts:30 still emits the heading "review ONLY these"; code was out of scope, the docs and prompts now explain both.
  • claude-opus-4-8 appears as the default model in 11 files with no single source; left as is.
  • Second-pass test nits, not applied: LOCALES names two different sets in the two suites (lines 114, 159); enumTables never clears field (lines 89-100); rubricCategories is a prose heuristic (lines 103-109).
  • The "when v2 moves" and "what triggers a version bump" rules in CLAUDE.md are inferred from tag history.

Review

  • pstack:thermo-nuclear-review-subagent: fixed 6, declined 0, unique: one-directional enum-table test, unchecked rubric categories, .DS_Store brittleness, positional related vs consolidate sort, false "leaves a log entry" claim
  • pstack:thermo-nuclear-code-quality-review-subagent: fixed 4, declined 1 (exporting a template helper from src/ for the test: no shipped-code change for a test's convenience), unique: hard-coded docs inventory, loops inside one it
  • /security-review: not run as a separate pass; the .github/ and action.yml diff is comments and descriptions only, confirmed by the thermo reviewer

🤖 Generated with Claude Code

(Claude)

wei18 and others added 7 commits November 14, 2026 21:39
The original implementation plans lived in five translated copies under
docs/<locale>/plans/ (about 20k lines) and each opened with an imperative
to execute it.

- Keep the English copy at docs/archive/plans/.
- Add a banner to each plan: historical record, do not execute, current
  behavior is in docs/en/design.md.
- Remove the zh-TW, zh-CN, ja and ko copies.
- The self-audit ignore glob (docs/*/plans/**) still covers the new path;
  only its comment changes.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
design.md called itself the SSOT but described behavior the code does not
have. Fix the doc, not the code, in all five locales:

- Remove the API retry/backoff row; no retry exists.
- Remove report.issue_label from the audit.yml example; nothing reads it.
  The label is the issue_label workflow input.
- "All reviewers fail" now says what happens: the run completes and the
  issue carries an incomplete-run warning.
- Section 7 no longer promises chunking, summarizing, downscaling or a
  "not inspected" list. oversizedText is a flag in the inventory.
- Triggers: the reusable workflow is workflow_call only; the caller owns
  the trigger and there are no scope inputs.
- Drop machine-specific paths and the local directory name.
- Section 11 is "out of scope", without the second meaning of "v2".
- Add reviewers.<name>.paths and reviewers.<name>.rubric to section 5,
  with one line per key.
- Define stale_a / stale_b and list every allowed enum value in section 4.
- Point at docs/archive/plans/ instead of docs/<locale>/plans/.

Fenced code blocks in the four translated files are now byte-identical to
the English ones, as CLAUDE.md requires. Explanations that lived in
translated block comments moved to prose below each block.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The reviewer prompts left a smaller model guessing in several places.
The JSON field names and allowed values are unchanged; src/findings.ts
and src/synthesis.ts still accept the same output.

Shared reviewer prompt:
- "Work only within your target files" read as a ban on opening the
  other side of a comparison. It now says: report only on target files,
  read any other repo file as evidence.
- Enum values were written as one pipe-joined string inside the JSON
  example. The example now shows one concrete value per field, and a
  table per field lists the allowed values with the criterion for each
  (category, severity, confidence, ssot_direction).
- stale_a means `file` is the outdated side; stale_b means the first
  entry of `related` is. `related` is defined.
- Each inventory field is defined, including what to do when
  oversizedText is true.
- The turn budget no longer quotes a default that max_turns can change.

Rubrics: every "what to look for" bullet names the category to use.
docs_staleness and convention say which field carries the direction
and the cited rule. Synthesis prompt gets the same enum treatment.

The recorded contract sample marked a lagging translation as stale_b
although the translation was `file`; it is stale_a under the definition.

test/locale-parity.test.ts checks that reviewers/en and reviewers/zh-TW
hold the same files with the same line structure and JSON contract,
that the contract examples pass the pipeline validators, and that docs
code blocks are byte-identical across the five locales.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
- Add a numbered change and release procedure taken from what the repo
  does: PR against main, build + test (same as CI), plugin version bump,
  squash merge, Dependabot auto-merge, version tag + release, rolling v2.
- Say when v2 moves (a change to what @v2 callers run) and give the
  non-interactive command with the tag's existing message.
- Move the two-file plugin version rule out of a long sentence into its
  own list.
- Name the English base files of the 5-locale docs.
- Add the reviewers/en <-> reviewers/zh-TW sync rule and point both sync
  rules at test/locale-parity.test.ts.
- docs/archive/plans/ and docs/superpowers/ are historical records;
  docs/en/design.md is the current truth.
- Drop the local directory name, which is not true of every checkout.
- The finalize helpers live in src/finalize.ts, not src/report.ts.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
All README, overview and why-reusable-workflow changes are mirrored in
the five locales.

- README and skill: document the --keep-work flag of local-audit.sh.
- Skill: the required --out step is its own numbered step instead of a
  clause inside a paragraph; say when not to use the skill and which
  script lines show progress.
- README and overview reviewer tables: code_hygiene and visual_icon now
  list what the rubrics check, not "commented-out blocks" or "branding".
- README link text shows the real path (docs/en/..., docs/<locale>/...).
- README names the config key report.min_severity, as design.md does.
- why-reusable-workflow: checkout@v7 and @v2 in the examples, matching
  the README; drop "as of v2.1".
- rubric_lang descriptions say "en or zh-TW"; any other value fails.
- SECURITY: matrix-job isolation is true only for the reusable workflow;
  state the tool allowlist that holds for all three entry points.
- CONTRIBUTING: docs/superpowers/ is not English-only; add the reviewer
  locale sync rule.
- self-audit comment no longer claims coverage of reviewers/<locale>/.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
The reviewer prompts and the skill text changed. Both version fields
move together: plugin.json and marketplace.json.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
Review follow-up.

test/locale-parity.test.ts:
- Parse each enum table of the reviewer prompt on its own and require
  exactly the values of the matching constant in src/types.ts, so a
  missing row or an extra row fails.
- Require every category a rubric names to be in FINDING_CATEGORIES.
- Compare the backticked tokens of each line between en and zh-TW, so a
  sentence that names a different value fails.
- Derive the docs file list from docs/en and require each locale
  directory to hold the same set (plus README.md).
- List only .md files, share one fence helper, and throw on an
  unterminated fence.
- One test case per file or locale (it.each) instead of loops.

Prompts and docs:
- zh-TW reviewer and synthesis prompts: two lines now name the same
  code tokens as the English lines.
- Reviewer prompt: the inventory entries sit under the `files` key.
- design.md (5 locales): the order of `related` is meaningful only in
  findings/<reviewer>.json; Consolidate sorts it. Drop "leaves a log
  entry" for an empty inventory; nothing logs it.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
@wei18
wei18 merged commit 2ba1c12 into main Nov 14, 2026
11 checks passed
@wei18
wei18 deleted the docs/health-check branch November 14, 2026 14:13
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant