feat: memory-to-docs codification — move 6 conventions from agent memory to repo - #52
Merged
Conversation
Full sweep of 14 personal-memory entries against project thesis "AI agents can't silently bypass undocumented conventions". 6 entries classified as A-class codification candidates; §10.A captures finalized 1-PR / 9-commit plan after maintainer audit dialogue 2026-05-13. Prior-art: skipped — research patch only, no new capability; classifies existing memory entries against codification opportunities. Six pivots recorded in §10.A relative to pre-audit §10 recommendation.
Promote project-wide policy (referenced in 10+ orchestrator prompts and research patches but with no canonical home in README/CLAUDE.md) to a load-bearing invariant. Operational expansion ships separately as .claude/rules/no-paid-llm-in-ci.md in the following commit. Prior-art: skipped — README invariant addition, no new capability; surfaces existing project policy as design invariant per Artifact Ownership Contract.
Companion to README invariant added in previous commit. Captures scope (CI surface), rationale, escape-hatch process (per-session operator override with explicit budget cap), AI-agnostic sub-agent fallback pattern, and three named anti-patterns: #paid-llm-creep, #subscription-conflation, #policy-bypass-via-cron. Adds .claude/rules/no-paid-llm-in-ci.md to REQUIRED_HEADER_DOCS in packages/core/principles/09-doc-authority-hierarchy.ts so principle 09 mechanically enforces the doc-authority header on the new rule. §1.7: forward-check applied — doc-authority-hierarchy.md:38 header format spec (§3) followed; phase-research-coverage.md:37 §1.7 substance arm requires file:line citations (this trailer complies); ai-laziness-traps.md:1 trap catalogue cited in §6 anti-patterns; backward-check sweep — REQUIRED_HEADER_DOCS in 09-doc-authority-hierarchy.ts:36 extended; existing rules .claude/rules/phase-research-coverage.md:1 + .claude/rules/doc-authority-hierarchy.md:1 retain valid headers verified by principle 09 test pass. Prior-art: context7 queries on no-paid-LLM enforcement patterns surfaced no direct production analog (subscription-bundle vs metered-API distinction is project-specific architecture). Sub-agent pattern itself adopted from existing agents/*.md precedents (Wave 8.1b PR #39).
Memory-codification incident PR #51 (2026-05-13): AI session filled visible TODO placeholders in Forward+Backward sections for a mechanical maintenance PR, producing theatre-shaped bullets that passed length gate but had no substance. The Skipped alternative existed only in the HTML comment, where it was invisible to most-visible-CTA bias. Inverting the default: Skipped line is now visibly default, Forward+Backward are in the HTML comment as «use if introducing/extending rule semantics». This shifts the most-visible CTA to the safer choice and forces conscious opt-in to substantive sections. Prior-art: skipped — UX inversion of existing template, no new capability; addresses fill-most-visible-TODO bias documented in memory entry.
Memory-codification gap: discipline-self-check.yml enforces substance on Forward-check (≥1 file:line citation, Wave 8.1) but only length on Backward-check (≥40 chars). This allows prose-only theatre in Backward sections — exactly the failure mode of PR #51 backward sweep. Adds symmetric file:line citation requirement on Backward-check + extends sanity-stub-fails-substance to also verify Backward section (paired- negative arm for both gates in one job). Prior-art: skipped — CI extension of existing substance arm (Wave 8.1 pattern) to Backward parity; no new capability, mirror of established Forward substance arm.
Codifies orchestrator discipline previously held only in personal AI memory. Atomic-umbrella discipline parallel to atomic-commit discipline: one concern per PR. Incident origin: PR #33 (2026-05-11) opened drive-by during PR #32 work; maintainer surfaced as discipline gap. Prior-art: skipped — convention addition to CLAUDE.md, no new capability; formalizes orchestrator-side scope discipline previously documented only in agent memory.
Codifies reviewer/orchestrator role separation previously held only in personal AI memory. Self-contained project rule — global skill at ~/.claude/skills/reviewer/SKILL.md is optional personal aid, not required for the rule to apply. Incident origin 2026-05-07: reviewer session role-swapped to orchestrator and made strategic decision about architecture.md §2.3 v1-vs-v2 status. Should have surfaced as decision-needed. Three anti-patterns codified: #role-swap-mid-session, #strategy-decided-by-reviewer, #reviewer-as-secondary-orchestrator. Adds .claude/rules/reviewer-discipline.md to REQUIRED_HEADER_DOCS in packages/core/principles/09-doc-authority-hierarchy.ts. §1.7: forward-check applied — doc-authority-hierarchy.md:38 header format spec (§3) followed; phase-research-coverage.md:37 §1.7 substance arm complied (this trailer); agents/review-sidecar.md:1 + agents/compliance-verifier.md:1 cited in §See-also as sub-agent precedents; backward-check sweep — REQUIRED_HEADER_DOCS in 09-doc-authority-hierarchy.ts:36 extended; existing rules .claude/rules/phase-research-coverage.md:1 + .claude/rules/no-paid-llm-in-ci.md:1 (prior commit this PR) retain valid headers per principle 09 test pass. Prior-art: context7 queries on reviewer-orchestrator role separation surfaced general agent-role discipline patterns (Cline custom modes, Claude Code agent frontmatter) but no direct production analog for the specific surface-as-decision-needed pattern. Adopted shape from existing project agents/*.md sub-agent precedent.
Codifies git worktree requirement for parallel sub-wave execution previously held only in personal AI memory. Self-contained project rule — global orchestrator skill is optional personal aid. Incident origin 2026-05-12, Wave 8.1/8.1b/8.2 parallel rollout: shared working directory caused branch contamination requiring orchestrator-side cherry-pick surgery. Three anti-patterns: #shared-workdir-parallel, #branch-race-on-checkout, #worktree-add-failure-ignored. Adds .claude/rules/parallel-subwave-isolation.md to REQUIRED_HEADER_DOCS in packages/core/principles/09-doc-authority-hierarchy.ts. §1.7: forward-check applied — doc-authority-hierarchy.md:38 header format spec (§3) followed; phase-research-coverage.md:37 §1.7 substance arm complied (this trailer); reviewer-discipline.md:1 (added prior commit) cited as parallel codification batch sibling; backward-check sweep — REQUIRED_HEADER_DOCS in 09-doc-authority-hierarchy.ts:36 extended; existing rules in .claude/rules/ retain valid headers per principle 09 test pass. Prior-art: context7 queries on parallel agent isolation patterns surfaced git-worktree as standard production practice for concurrent branch work; no project-specific extension required beyond making it mandatory in orchestrator prompts.
…ation note Codifies hook self-test pipeline stub completeness rule previously held only in personal AI memory (Wave 8.3 regression 2026-05-12). Bash implementation in packages/core/audit-self/hook-stub-completeness.test.sh parses .husky/pre-push for hard-fail invocations + verifies each test file using make_test_repo() stubs every dependency. Wired into .husky/pre-push as §3a hard-fail. Recursive self-application: the very rule being introduced applies to its own introduction — this commit adds hook-stub-completeness.test.sh as a hard-fail AND adds its own stub in tests/hooks/prior-art-trailer-hook.test.sh make_test_repo() to satisfy the rule. Rule eats its own dogfood at introduction moment. Mutation arm verified manually before commit: removing the new stub from make_test_repo() causes audit to exit 1 with violation report. Restored. Wave 10 migration note (3-place tracker): when TS-core hook infrastructure lands in Wave 10, port this audit to packages/core/principles/ 11-hook-stub-completeness.test.ts. Bash serves as regression-fixture spec; TS port must produce identical violation output on same fixture. Tracker in (1) top comment of hook-stub-completeness.test.sh, (2) Wave 10 kickoff .claude/orchestrator-prompts/wave-10-hook-architecture/kickoff.md scope list, (3) research patch §10.A. Prior-art: context7 queries on hook self-test stub patterns surfaced no direct production analog (hook stub completeness is project-specific invariant arising from .husky/pre-push hard-fail design). Adopted bash audit-self pattern from existing pre-push.test.sh + audit-ai-docs.test.sh precedents in packages/core/audit-self/.
Principle 10 requires every research patch to carry <!-- scope:<slug> --> on first line. Fix missed during initial commit 1. Prior-art: skipped — fix of missing annotation, no new capability.
7 tasks
This was referenced May 21, 2026
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
Memory-to-docs codification — moves 6 project-wide conventions from personal AI memory (
~/.claude/projects/<repo>/memory/) into repo-committed files. Each entry was either an undocumented convention invisible to fresh AI sessions or a load-bearing policy with no canonical home. Mirrors the project thesis: «AI agents can't silently bypass undocumented conventions — every codified rule fails CI on violation».Changes
.claude/rules/no-paid-llm-in-ci.md: scope, rationale, escape hatch, 3 anti-patterns (commit 3).claude/rules/reviewer-discipline.md: role separation, surface-as-decision-needed, 3 anti-patterns (commit 7).claude/rules/parallel-subwave-isolation.md: git worktree requirement, sequential fallback, 3 anti-patterns (commit 8)packages/core/audit-self/hook-stub-completeness.test.sh: parses pre-push + verifies stubs, wired as §3a hard-fail, Wave 10 TS migration 3-place tracker, recursive self-application (commit 9)Prior-art consult
Prior-art:trailer (orskipped — <≥20 chars rationale>)Test plan
npm test --workspace=@rules-as-tests/core --rungreen (56 tests pass)make self-auditequivalent —bash .husky/pre-pushgreen on pushnpm run --prefix packages/core test:principlesgreen — principle 09 test validates new rules in REQUIRED_HEADER_DOCSbash tests/hooks/prior-art-trailer-hook.test.shgreen — hook stub completeness passes§1.7 Self-discipline check (REQUIRED if PR touches discipline-bearing files)
§1.7 Forward-check applied
PR touches
.claude/rules/× 3 (no-paid-llm-in-ci.md, reviewer-discipline.md, parallel-subwave-isolation.md) andCLAUDE.md— substantive rule introductions. Forward compliance verified:.claude/rules/doc-authority-hierarchy.md:53§3 header format spec — all 3 new rule files carry compliant> **Authoritative for:**headerspackages/core/principles/09-doc-authority-hierarchy.ts:27REQUIRED_HEADER_DOCS declaration — all 3 new rules added; count 53 within sentinel bounds (20–60).claude/rules/phase-research-coverage.md:29§1.7 «Recommendation self-discipline check» — each discipline-introducing commit carries§1.7:trailer with ≥1 file:line citation (verified in commit bodies for commits 3, 7, 8).husky/pre-push:302s17_is_discipline_introducing file-glob + content predicate — commits 3, 7, 8 fire the gate; trailers present and substantive.claude/rules/ai-laziness-traps.md:114T15 «Self-application skipped» — hook-stub-completeness.test.sh (commit 9) recursively applies its own rule at introduction moment§1.7 Backward-check applied
Complete sweep of existing artefacts under the new rules' scope:
.claude/rules/phase-research-coverage.md:1— has valid> **Authoritative for:**header; no authority drift with new rules.claude/rules/doc-authority-hierarchy.md:1— authority header present; new rules cite it correctly.claude/rules/ai-laziness-traps.md:1— authority header present; orthogonal scopepackages/core/principles/09-doc-authority-hierarchy.test.ts:44describe block — test passes with all 3 new rules in REQUIRED_HEADER_DOCS; 56/56 tests greentests/hooks/prior-art-trailer-hook.test.sh:38make_test_repo() — stub for hook-stub-completeness.test.sh added; all 8 sub-tests still pass (verified viabash tests/hooks/prior-art-trailer-hook.test.sh→8 pass / 0 fail).github/workflows/discipline-self-check.yml:97— forward substance arm unmodified; backward arm added at line 115+; sanity job extended to check bothpackages/core/audit-self/pre-push.test.sh:1— existing hook-stub audit passes (hook-stub-completeness.test.sh stub present in make_test_repo)§1.7 Round 3 amendment (2026-05-13): 5 file:line citations corrected after Round 3 reviewer caught inaccurate line numbers in initial submission. See REVIEWER-PR52-VERDICT.md for full verification log. Substance pass: each citation now re-verified against actual file content on this branch via
grepat edit time. The recursive irony of citing wrong lines in a PR codifying «count-claims-unverified» antipattern is itself diagnostic evidence that the gap (autonomous self-audit triggering) needs the additional layer surfaced in .claude/orchestrator-prompts/autonomous-self-audit-research/research-prompt.md.