From 6a76efcc98a6b140c2754e146f49d7de72bdde2b Mon Sep 17 00:00:00 2001 From: James Ross Date: Wed, 13 May 2026 08:26:32 -0700 Subject: [PATCH 1/2] docs: codify Code Lawyer standards --- AGENTS.md | 6 +- CODE_STANDARDS.md | 188 +++++++++++++++++++++++ test/unit/release/code-standards.test.ts | 23 +++ 3 files changed, 215 insertions(+), 2 deletions(-) create mode 100644 CODE_STANDARDS.md create mode 100644 test/unit/release/code-standards.test.ts diff --git a/AGENTS.md b/AGENTS.md index 2a41b63..302b2b0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,6 +22,7 @@ Do not audit the repository by recursively walking the filesystem. Follow the au - **`ARCHITECTURE.md`**: Authoritative structural reference (Ports, Adapters, WARP). - **`docs/VISION.md`**: Core tenets and the provenance-aware mission. - **`METHOD.md`**: Repo work doctrine (Backlog lanes, Cycle loop). +- **`CODE_STANDARDS.md`**: Code Lawyer audit standards, Red-Green repair loop, and merge-gate doctrine. ### 3. The Direction - **`docs/BEARING.md`**: Current execution gravity and active tensions. @@ -38,8 +39,9 @@ When starting a new session or recovering from context loss: 1. **Read `docs/BEARING.md`** to find the current execution gravity. 2. **Read `METHOD.md`** to understand the work doctrine. -3. **Check `docs/method/backlog/asap/`** for imminent work. -4. **Check `git log -n 5` and `git status`** to verify the current branch state. +3. **Read `CODE_STANDARDS.md`** before review, release, or PR repair work. +4. **Check `docs/method/backlog/asap/`** for imminent work. +5. **Check `git log -n 5` and `git status`** to verify the current branch state. ## End of Turn Checklist diff --git a/CODE_STANDARDS.md b/CODE_STANDARDS.md new file mode 100644 index 0000000..60839fa --- /dev/null +++ b/CODE_STANDARDS.md @@ -0,0 +1,188 @@ +# CODE_STANDARDS + +These standards define the required review and repair posture for Graft. +They are operational doctrine, not suggestions. When these rules conflict +with convenience, convenience loses. + +## Code Lawyer Mandate + +Code Lawyer is the repository's strict audit posture: + +- Treat correctness, determinism, architecture, typing, documentation, and + style as release-relevant integrity concerns. +- Prefer inspectable evidence over assertion. Anchor findings to files, + line numbers, commands, commits, PR threads, or reproducible tests. +- Do not normalize sludge. Duplication, hidden nondeterminism, vague + ownership, stale docs, loose types, and unbounded processes must either + be fixed or filed as explicit debt. +- Never hide risk behind green reruns. A pass after an unexplained failure + is evidence of nondeterminism until the failure mode is understood or + bounded. + +## Severity Ladder + +Use this priority order when building a review or repair queue: + +| Severity | Meaning | +| :--- | :--- | +| P0 Critical | Data loss, security boundary failure, release corruption, destructive Git risk, or a broken invariant with broad blast radius. | +| P1 High | User-visible bug, deterministic correctness failure, authz/path escape, broken public API, or CI/release gate failure. | +| P2 Medium | Edge-case bug, architectural mismatch, race risk, missing contract coverage, or misleading generated output. | +| P3 Low | Docs drift, incomplete witness, degraded diagnostics, missing targeted regression, or narrow maintainability issue. | +| P4 Style | Formatting, naming, markdown structure, consistency, or local readability issue that does not change behavior. | +| P5 Nit | Tiny polish item that should still be fixed when already touching the area. | + +## Phase 0: Lockdown + +Before any Code Lawyer review or repair loop: + +```bash +export GH_PAGER=cat +git status --porcelain +``` + +- Dirty worktree: halt, report dirty paths, and abort. +- Clean worktree: run `git fetch origin`. +- If `gh` authentication fails, halt immediately with: + +```text +Auth error - run `gh auth login` and retry. +``` + +Do not continue a GitHub-dependent workflow after an auth failure. + +## Phase I: Discovery and Radical Transparency + +1. Fetch unresolved review context. For PR work, use a full GraphQL query + that includes global comments, reviews, inline review threads, + `isResolved`, `isOutdated`, path, line, and comment bodies. +2. Run the branch audit: + + ```bash + git diff origin/main...HEAD + ``` + +3. Audit for logic bugs, races, edge cases, nondeterminism, duplication, + separation-of-concerns violations, style drift, typing holes, stale docs, + and release-gate gaps. +4. If self-discovered issues exist on a PR, immediately post a PR comment + with a clean issue table and include `@codex` for a second opinion. + +Findings must include: + +- filepath +- line or range when available +- infraction type +- severity +- evidence +- recommended mitigation + +## Phase II: Surgical Execution Loop + +Merge PR feedback and self-discovered findings into one prioritized queue, +ordered P0 through P5. Resolve one issue at a time. + +For each issue, print a local log entry: + +```text +=== [N] [P0-P5] =================================== +Source: [PR / Self] +File: path/to/file.ext +Lines: Lxx-Lyy +Issue: [one-line summary] +``` + +Then run a Red-Green-Verify-Document-Commit loop: + +1. RED: create the smallest deterministic regression that fails only for + the issue under repair. Run it and confirm failure. +2. GREEN: make the smallest architecture-preserving fix. +3. VERIFY: rerun the regression and the relevant suite. Both must pass. +4. DOCUMENT: update `CHANGELOG.md` or internal docs when behavior, + schema, API, release truth, or invariant posture changes. +5. COMMIT: make one focused commit per issue: + + ```bash + git add -A + git commit -m "Fix: " + ``` + +6. RESOLVE: if the issue came from a PR thread, mark that exact thread + resolved through GraphQL. + +Regression quality rules: + +- Avoid wall-clock timing, unseeded randomness, ambient network state, and + live-checkout fixture coupling. +- Assert observable behavior, not implementation text. +- Prefer error types, codes, and structured output over fragile message + matching. +- Stdout and stderr are not enough for behavioral proof unless the public + contract is explicitly a CLI rendering contract. + +## Phase III: Closure + +For PR work, post an Activity Summary comment: + +```markdown +| Issue | Severity | File | Commit SHA | Outcome | +| :--- | :--- | :--- | :--- | :--- | +| {Issue Description} | {P0-P5/Docs} | {File} | {Hash} | {Result} | +``` + +Print a console SitRep for every resolved item: + +```text +--[ ITEM N ]----------------------------------------------------------------- +ISSUE: {Description} +SEVERITY: {Severity} +COMMIT: {Hash} +REGRESSION: {Test Name}; {Command} +OUTCOME: {Summary of technical change} +----------------------------------------------------------------------------- +``` + +## Phase IV: Merge Gate + +Before declaring a PR mergeable, verify all gates: + +- CI green via `gh pr checks`. +- At least two approvals. +- Zero Changes Requested reviews. +- No active CodeRabbit cooldown/rate-limit blocker. +- Local tests and linters are 100% clean for the changed surface. +- No unresolved actionable review threads. +- Worktree is clean. + +If ready: + +```text +MERGE GATE: OPEN ✅ +All invariants satisfied. Reply **YES** to execute merge. +``` + +If blocked: + +```text +MERGE GATE: LOCKED 🔒 +Blocking reasons: +• ... +Reply with fixes or "FORCE" only if you accept risk. +``` + +Admin override is allowed only when the operator explicitly accepts that +risk. Even then, use normal merge mechanics; never rebase, amend, or force. + +## Repository Integrity Rules + +- Keep work scoped to the issue being resolved. +- Do not combine unrelated fixes in one commit. +- Do not rewrite history. +- Do not push to `main` without explicit permission. +- Keep generated or build artifacts out of commits unless they are the + documented deliverable. +- Update docs when behavior, workflow, release truth, or invariants change. +- File unresolved bad-code findings in `docs/method/backlog/bad-code/`. +- File non-blocking ideas in `docs/method/backlog/cool-ideas/`. +- Treat `pnpm lint`, `pnpm typecheck`, and the relevant tests as the + minimum proof surface for code changes. diff --git a/test/unit/release/code-standards.test.ts b/test/unit/release/code-standards.test.ts new file mode 100644 index 0000000..b40006c --- /dev/null +++ b/test/unit/release/code-standards.test.ts @@ -0,0 +1,23 @@ +import * as fs from "node:fs"; +import * as path from "node:path"; +import { fileURLToPath } from "node:url"; +import { describe, expect, it } from "vitest"; + +const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../.."); + +function readRepoFile(relativePath: string): string { + return fs.readFileSync(path.join(ROOT, relativePath), "utf8"); +} + +describe("repository code standards", () => { + it("keeps the Code Lawyer standards discoverable from agent orientation", () => { + const standards = readRepoFile("CODE_STANDARDS.md"); + const agents = readRepoFile("AGENTS.md"); + + expect(standards).toContain("# CODE_STANDARDS"); + expect(standards).toContain("Code Lawyer"); + expect(standards).toContain("Phase 0: Lockdown"); + expect(standards).toContain("Merge Gate"); + expect(agents).toContain("CODE_STANDARDS.md"); + }); +}); From df786e196f492a9f60bc86eb5e695042b19a5be4 Mon Sep 17 00:00:00 2001 From: James Ross Date: Wed, 13 May 2026 10:30:02 -0700 Subject: [PATCH 2/2] Fix: align Code Lawyer auth halt text --- CODE_STANDARDS.md | 2 +- test/unit/release/code-standards.test.ts | 1 + 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/CODE_STANDARDS.md b/CODE_STANDARDS.md index 60839fa..d2dad6a 100644 --- a/CODE_STANDARDS.md +++ b/CODE_STANDARDS.md @@ -46,7 +46,7 @@ git status --porcelain - If `gh` authentication fails, halt immediately with: ```text -Auth error - run `gh auth login` and retry. +Auth error — run `gh auth login` and retry. ``` Do not continue a GitHub-dependent workflow after an auth failure. diff --git a/test/unit/release/code-standards.test.ts b/test/unit/release/code-standards.test.ts index b40006c..8c86a32 100644 --- a/test/unit/release/code-standards.test.ts +++ b/test/unit/release/code-standards.test.ts @@ -17,6 +17,7 @@ describe("repository code standards", () => { expect(standards).toContain("# CODE_STANDARDS"); expect(standards).toContain("Code Lawyer"); expect(standards).toContain("Phase 0: Lockdown"); + expect(standards).toContain("Auth error — run `gh auth login` and retry."); expect(standards).toContain("Merge Gate"); expect(agents).toContain("CODE_STANDARDS.md"); });