Nquiry Development Lifecycle Methodology
Created: 2026-04-28
Authors: Joe + CD (collaborative); CC implements the gates this doc describes
Status: Draft pending Joe ratification (NQU-698)
Sister doc: docs/claude_desktop/prompt-lifecycle-methodology.md — same shape, applied to prompts
Linear: NQU-698 (this doc), NQU-285 (cross-model review), NQU-359 (F+F gate, retroactive), NQU-652 (branch protection, done)
This doc is the spine of the code lifecycle. Every other process document is a section, an appendix, or gets cut. If a process exists in conversation but not here, it does not exist.
Table of Contents
- §0. Premise & operating truths
- §1. Principles (anti-entropy commitments)
- §2. Lifecycle stages
- §3. Recurring rhythms
- §4. The multi-model review layer
- §5. Anti-entropy mechanisms
- §6. Joe-as-weak-link mitigations
- §7. Tooling inventory
- §8. RACI
- §9. Operating definitions
- §10. Disposition of existing fragments
- §11. Acceptance criteria
- Appendix A. Pre-prod cutover gate (one-time checklist)
- Appendix B. Tooling pilot status
§0. Premise & operating truths
Last verified: 2026-04-28 Max age: 90 days (review every quarter, or immediately on any change to team composition or F+F/cutover state)
Team shape. One human (Joe), two internal agents (CC = Claude Code CLI, CD = Claude Desktop / Cowork), at least one external review participant (initially built-in CC review skills; ramping into a non-Anthropic LLM via CC codex skill — see §4). Roles described in .claude/rules/cross-repo.md and docs/reference/developer-context.md; not duplicated here.
Joe's role. Intent owner, risk approver, milestone gatekeeper. Not a code reviewer. Joe does not provide line-level code oversight. Any procedure in this doc that depends on "Joe will catch it" is a defect — see §6. Joe approves intent and risk; agents and tools provide review depth.
Production state (April 2026). F+F flipped 2026-04-20 (NQU-359). Real users are on the system. Every merge to main deploys (see docs/admin/ops/deployment-flow.md). Branch protection on main went live 2026-04-26 (NQU-652). The lifecycle described here is the steady-state lifecycle, not an aspirational one.
Doc constraints. Readable in <10 minutes. Operational substance only — no aspiration without a forcing function attached. Cross-references over duplication. The doc reviews itself (§5).
§1. Principles (anti-entropy commitments)
Last verified: 2026-04-28 Max age: 180 days (principles change rarely; review semi-annually or on event trigger)
The principles below are commitments, each enforced by a mechanism elsewhere in this doc. Principle without mechanism is aspiration.
- Doc-as-source-of-truth. This doc is the spine. New process docs go in here as sections or appendices, or they get rejected at creation (§5).
- Forcing functions over discipline. Every gate is enforced by a tool, a schedule, or a required artifact — never by "remember to do this." If a step has no forcing function, it doesn't exist.
- Multi-model by design. At least one review pass per cycle by a non-Anthropic model. Not aspirational. Operationalized in §4.
- Continuous recertification. Every section has
Last verified+Max age. Sections past max age are blockers on the dashboard until refreshed. - Visible state. Who is reviewing what, when — in Linear or this doc. Not in conversation. Conversation is not durable.
- Joe-as-weak-link explicit. Stated as a design constraint, not a flaw. The methodology is built so review depth survives Joe's absence (§6).
- Continuous-checkin-as-gate is real. This team's shape (1 human + 2 agents) makes per-PR continuous gates the substantive review layer for routine work, not a degraded form of review. Bi-weekly broader passes catch what continuous gates miss.
§2. Lifecycle stages
Last verified: 2026-04-28 Max age: 60 days (revisit on any process incident or on quarterly recertification)
Eleven stages. Each row: entry → activities → exit → owner → required artifact. Activities and forcing functions only — no narrative.
| # | Stage | Entry | Activities | Exit | Owner | Required artifact |
|---|---|---|---|---|---|---|
| 1 | Intake & scoping | Idea, bug, request | Joe or CD opens a Linear ticket on the Nquiry team; assigns to delegate (CC or CD) | Linear ticket exists with title, problem statement, acceptance criteria | Joe / CD | Linear issue (NQU-xxx) |
| 2 | Specification | Linear ticket exists | CD writes spec; posts as Linear comment (existing pattern) | Spec comment posted; CC has enough to plan from | CD | Linear comment with spec |
| 3 | Planning | Spec exists | CC enters plan mode; outputs plan; Joe approves intent + risk (not code) | Plan approved by Joe in writing on the Linear ticket or PR draft | CC drafts, Joe approves | Plan + Joe's intent approval comment |
| 4 | Implementation | Plan approved | CC creates feature branch per .claude/rules/git-workflow.md; commits; opens PR | PR open with description per template; branch follows <owner>/<ticket>-<desc> | CC | Feature branch + PR |
| 5 | Self-review (CC) | PR open / push | The Anthropic-published code-review skill (installed 2026-04-28; namespace code-review:code-review) runs against the diff. Default invocation: GitHub Action on every push to a PR branch. Manual invocation by CC via the Agent tool is a fallback when CI is down. On Sensitive paths (§9), the security-review skill also runs. Findings are posted as a PR comment by the action, not pasted by hand | (a) PR comment from the code-review skill exists and is current with HEAD of the PR branch; (b) every comment finding is either resolved in code or has a written disposition reply on the PR | CI runs the skill; CC triages findings | PR comment authored by the code-review skill |
| 6 | Continuous gate (CI) | PR open / push to main | GitHub Actions: lint, type-check, build, Semgrep (p/typescript, p/security-audit, p/secrets, p/eslint-plugin-security), tests w/ coverage, e2e on main. See docs/admin/ops/deployment-flow.md | All required checks green; cannot bypass (branch protection) | GitHub Actions | CI run (linked from PR) |
| 7 | Per-merge gate | CI green | Branch protection: 1 approving review + required status checks. PR description follows template per .claude/rules/git-workflow.md. One PR per Linear ticket | PR meets template + protection rules | GitHub branch protection | Approving review + green checks |
| 8 | Substantive review | Triggered by file paths (§9) on PR; recurring on schedule (§3) | (a) Per-PR multi-model review on Sensitive paths; (b) bi-weekly internal cross-model differential; (c) bi-weekly external-LLM differential. See §4 | Per-PR: external LLM findings acknowledged in PR comment thread (acknowledged ≠ necessarily fixed). Recurring: review log entry posted to docs/reviews/YYYY-MM-DD-cross-model-review.md | CD coordinates; CC + external LLM execute | Review log entry; PR comment with findings + dispositions |
| 9 | Deployment | Merge to main | Auto-pipeline: change-detection skip → ECR build → ECS task def update → service update → wait stable → smoke test /api/health. Full mechanics: docs/admin/ops/deployment-flow.md | Smoke test green; ECS service stable on new SHA | GitHub Actions | Deploy run + smoke test result |
| 10 | Post-deploy verification | Deploy succeeded | Sentry / Bedrock / quality-check observability checked for new error patterns; agent sweep of audit_log for failed actions in the new SHA's first hour; error-budget check | No new error class introduced; or, if introduced, follow-up ticket opened | CC (sweep) + CD (review of sweep output) | Post-deploy sweep comment on the deploying PR |
| 11 | Milestone gates | Named milestone (F+F, prod cutover, GA) | One-time checklist: pre-cutover audit (Appendix A); convergent internal + external review on touched surfaces; Joe sign-off on intent + residual risk | Checklist complete + Joe sign-off in writing on the milestone ticket | Joe (gate) + CD (orchestration) + CC + external LLM | Completed milestone checklist + sign-off comment |
Notes.
- Stages 4-7 happen on every PR. Stages 5 and 8(a) are where review depth lives — Joe never enters this loop on code substance.
- The F+F flip (2026-04-20) preceded this doc, so stage 11 was run informally for that milestone. A retroactive
docs/decisions/note documenting the actual gate that did fire (CD/CC continuous check-in) is tracked as a separate small ticket; it is not a do-over.
§3. Recurring rhythms
Last verified: 2026-05-14 (recertification-cadence row updated to reflect Joe's 2026-05-06 ratification — quarterly steady-state, not monthly-through-cutover) Max age: 90 days
Every recurring rhythm below has a corresponding Linear recurring ticket — auto-renews on close. Empty review log = visible blocker on the dashboard (§5).
| Cadence | Activity | Owner | Forcing function | Linear |
|---|---|---|---|---|
| Per-merge | CI: lint, type-check, build, Semgrep, test+coverage, e2e | GitHub Actions | Branch protection — cannot merge with red checks | (mechanical) |
| Per-PR | Anthropic code-review skill runs against the diff via GitHub Action; security-review skill also runs on Sensitive paths | GitHub Action (CI) — CC triages findings | Required status check on main branch protection: PR cannot merge until the code-review action has succeeded against the latest commit and findings are resolved or dispositioned. Cannot be bypassed | (mechanical) — workflow at .github/workflows/code-review.yml (CI integration is a follow-up CC ticket; see Appendix B) |
| Per-PR (Sensitive) | External-LLM review on touched Sensitive paths (§9) | CC drives, external LLM runs | Required PR comment from external reviewer before merge; findings acknowledged | NQU-285 (parent), per-PR pilot tracked in Appendix B |
| Weekly (rotating) | Substantive focus: Auth (W1), Errors (W2), Tests (W3), Compliance (W4) — substance carried from docs/admin/security/review-schedule.md | CC | Recurring Linear ticket; each focus produces a review-log entry | NQU-506, NQU-500 (rotating focus tickets) |
| Bi-weekly | Internal cross-model differential review (Claude family) — see template in docs/reviews/2026-03-15-cross-model-review.md | CD | Recurring Linear ticket; review log entry required at docs/reviews/YYYY-MM-DD-cross-model-review.md | NQU-285 |
| Bi-weekly (offset 1 week) | External-LLM broader-scope differential review — pilot order in §4 | CD packages, external LLM runs, CC triages | Recurring Linear ticket; review log entry; offset by 1 week so external coverage is continuous | NQU-285 (sub-issue per cycle) |
| Quarterly | Deep dive: Semgrep clean run, npm audit, IAM policy review, infra/Terraform review, Cognito password policy | Joe + CC | Calendar event + ticket; output is a quarterly memo committed to docs/reviews/ | (recurring quarterly) |
| Quarterly | Methodology recertification (this doc reviews itself) | CD first pass; Joe + CD review together | CD report posted to NQU-698; deltas land in docs/decisions/; event triggers fire off-cycle | NQU-670 (recurring CD report) |
| Per milestone (one-time) | Pre-cutover audit (Appendix A) | Joe + CD + external LLM | Checklist must be complete before milestone declared | One-time ticket per milestone |
Implicit absorption. The substance of docs/admin/security/review-schedule.md (weekly rotating focus areas + quarterly deep dive) is now hosted in this table. The old file gets a redirect note in a follow-up ticket — it is not the source of truth as of the date this doc lands.
Enforcement model — per-PR code-review skill
Goal: the code-review skill is a required gate, not a suggestion. "Used" must be verifiable from the PR alone, not from CC's intent. Three layers, each a forcing function:
- CI runs the skill, not the agent. A GitHub Action workflow (
.github/workflows/code-review.yml) checks out the PR branch, invokes Anthropic'scode-reviewskill on the diff (andsecurity-reviewon Sensitive paths per §9), and posts findings as a PR comment authored by the action's bot identity. The skill never depends on a human or agent remembering to run it. - Branch protection requires the status check. The
code-reviewjob is added to the required status checks onmain(alongsidelint-and-build,test,security-scanper.claude/rules/git-workflow.md). The check passes only when (a) the action completed successfully against the latest commit on the PR branch (strict mode), and (b) every action-posted finding has either been resolved in a follow-up commit or has a disposition reply on the PR thread (the disposition check is a small CI script — see follow-up below). - No bypass paths. Branch protection is enforced at the API level (NQU-652), so neither
git push origin mainnor "merge without review" bypasses the gate. If the workflow itself is broken, the unbroken path is to fix the workflow — not to merge around it. Workflow disablement counts as an incident under §5 event triggers and fires off-cycle methodology recertification.
Acknowledged ≠ necessarily fixed. The skill can be wrong. CC may push back on a finding by replying with a written rationale; the disposition is the response, not silence. Silence on a finding fails the disposition check, which fails the status check, which blocks the merge.
Manual invocation is a fallback, not the default. CC may invoke the skill directly via the Agent tool when working locally; that is useful pre-push to shorten the loop, but the required invocation is the CI run on the PR. A locally-clean review does not satisfy the gate.
CI integration is a follow-up CC ticket (out of scope for this doc body): .github/workflows/code-review.yml, a small scripts/check-review-dispositions.ts (parses PR comments by the code-review bot, fails CI if any finding lacks a resolution commit or disposition reply), and a branch-protection update to add the code-review and security-review jobs to the required status checks list. Until that ticket lands, the per-PR enforcement layer is a known gap — CC self-runs the skill via the Agent tool and posts the output as a PR comment manually, and CD verifies presence on every PR review during the gap window. The gap closes when the workflow is merged.
§4. The multi-model review layer
Last verified: 2026-05-14 (Codex named as the committed non-Anthropic choice per Joe's 2026-05-06 ratification) Max age: 60 days (re-verify on any tooling change or cross-model outcome that affects the pilot order)
External-LLM review is a first-class part of the lifecycle, not aspirational. Two reasons: (a) Joe cannot provide code-level review depth, so vendor diversity in agentic review is the substitute for an independent human reviewer; (b) the April 2026 model-quality regression (read-to-edit ratio dropped 70%, fixed in v2.1.116) demonstrated that single-vendor review is monoculture — a regression invisible to the affected family was visible to other models.
Non-Anthropic choice — Codex. Ratified 2026-05-06 (NQU-698). The methodology commits to Codex as the non-Anthropic review participant rather than running a parallel evaluation of Codex / Gemini Pro / GPT-5. Codex is the simplest dependency, the one this team has the most context on, and the one closest to what's already wired into CC. If a future signal pushes us to swap, that change is an ADR, not an open-ended re-evaluation.
Two-layer design
Per-PR (continuous, scoped). External LLM reviews each PR that touches a Sensitive surface (§9: auth, billing, retention, PHI, security boundary, infrastructure/Terraform). Posted as a PR comment by the reviewer. Forcing function: PR cannot merge while the external-review comment is missing on a Sensitive PR; findings must be acknowledged before merge. Acknowledged ≠ necessarily fixed — CC may push back if the reviewer is wrong, but the rationale must be in the PR thread.
Bi-weekly (periodic, broader). Differential review with cross-PR scope: pattern detection across recent merges, fresh-eyes pass on anything the per-PR scoped review didn't trigger on, follow-up on prior findings. Output is a dated review log at docs/reviews/YYYY-MM-DD-cross-model-review.md matching the format of the 2026-03-15 review (previous-review status table + consensus findings + single-agent findings + priority remediation table). The bi-weekly external review may use a different model from the per-PR layer, for true vendor diversity.
Convergence rule (Sensitive paths)
For PRs touching Sensitive paths that go beyond mechanical fixes (new auth flow, new billing path, retention policy change, PHI handling change, infrastructure change with blast radius beyond the PR's stated scope): internal review (CC self-review) and external review must converge before merge. No single-reviewer override. If they diverge, CD adjudicates by writing a delta note on the PR; if CD cannot adjudicate, the PR blocks until Joe weighs in on the disagreement (Joe arbitrates the disagreement, not the code).
Tool selection — pilot order
Methodology is tool-agnostic. Pilot order pre-commits to using available toolsets before paying for a service:
- Built-in CC
reviewandsecurity-reviewskills. Already installed, free, Anthropic-side. Pilot on the next 5–10 PRs. Establishes the baseline of what same-vendor agentic self-review catches. Does not satisfy the multi-model principle — same family — but establishes the floor. - CC codex skill. Separate plugin layer. Pilot to introduce a non-Anthropic model into the review loop without paid integration. This is the multi-model-by-design lever; if it produces useful, distinct findings on a representative PR sample, it is the answer.
- Paid service (CodeRabbit / Greptile / Bito). Only if 1+2 do not deliver. Evaluation criteria when triggered: privacy posture (where does the diff go), per-PR cost, operability (latency on PR creation, signal-to-noise on findings).
Current state of the pilot lives in Appendix B. External-LLM tool selection beyond naming the principle is out of scope for this doc; tracked as a separate ticket once §4 is ratified.
§5. Anti-entropy mechanisms
Last verified: 2026-05-14 (recertification-cadence subsection rewritten to reflect Joe's 2026-05-06 ratification — quarterly steady-state, not monthly-through-cutover) Max age: 90 days (review at the quarterly recertification, or immediately on any forgotten gate / stalled review)
Every commitment in §1 maps to a mechanism here. Mechanism without an owner and a forcing function is aspiration.
| Mechanism | What it does | Forcing function | Owner |
|---|---|---|---|
| Recurring Linear tickets | Each rhythm in §3 has a recurring ticket that auto-renews on close | Linear scheduler; missed cycles surface as overdue tickets on the Joe-Review dashboard | Linear (mechanical) |
| Doc staleness sweeper | Weekly CD pass flags any process doc past Last verified + Max age | Recurring CD ticket; sweep output is committed to docs/working/ and converted to deltas | CD (sweeper tool tracked as a separate CC ticket — out of scope for this doc) |
| Empty-review-log blocker | If the bi-weekly cross-model review hasn't produced a docs/reviews/YYYY-MM-DD-cross-model-review.md entry by its due date, the recurring ticket flips to overdue and surfaces on the dashboard | Linear ticket overdue state | CD |
| Quarterly methodology revalidation | This doc reviews itself; deltas land in docs/decisions/ (one ADR per substantive change); rejected deltas are recorded too | Recurring CD ticket (NQU-670); Joe + CD review session (~30 min) | CD first pass, Joe ratifies |
| No-new-standalone-process-docs rule | New process docs must land as a section or appendix here, or be rejected at creation; CC's 2026-04-28 docs/admin/ops/git-workflow.md draft is the canonical example of "rejected, will be cut" | Pre-merge: CD reviewer rejects unaffiliated process docs; PR must either fold them in or close them | CD (review) |
| Joe-bypass check | Any procedure phrased as "Joe will catch it" is rejected at draft time | Drafted and reviewed by CD; CD must call this out on review | CD |
| Event triggers | Process incidents (recurrence of 14-commits-to-main, missed gate, model-regression-exposed gap, F+F-style undocumented milestone) trigger off-cycle methodology recertification immediately, regardless of cadence | Incident report comment on NQU-698 with the trigger; recertification report due within 7 days | CD detects + reports; Joe ratifies |
Recertification cadence
Quarterly. Steady-state from the start — not stepped from monthly through cutover. Ratified 2026-05-06 (NQU-698). The reasoning: F+F is already live, so the steepest shape-change phase is behind us; monthly recertification would be process churn for a three-person team. Event triggers (table above) fire off-cycle when assumptions shift fastest — incidents, milestone cutovers, forgotten gates — so the quarterly cadence is supplemented, not relied on, in moments when the actual work surface is moving.
CD first-pass deliverable each quarter (~30 min)
- Lifecycle doc vs. last-quarter actual practice — did changes flow through the stages described? Where did practice diverge?
Last verifiedaudit on every section; flag any past max age.- Audit whether each recurring rhythm in §3 actually ran on schedule.
- Flag any new process docs that landed without a section/appendix in this spine doc.
- Flag any "Joe will catch it" patterns that crept in.
- Recertification report: "doc still matches reality" or "drift in §X, proposed delta: …"
Joe + CD review the report together (~30 min). Deltas are ratified or revised; ratified deltas land in docs/decisions/ as one-line ADRs.
§6. Joe-as-weak-link mitigations
Last verified: 2026-04-28 Max age: 180 days (this is a design constraint; revisit only if team composition changes)
Joe cannot provide line-level code review. This is a design constraint, not a flaw. The methodology is built so review depth survives Joe's absence and does not depend on Joe's availability.
What Joe does.
- Approves intent (does this work make sense?) and risk (am I OK with the residual exposure if it ships?). Written sign-off lives on the Linear ticket or PR description.
- Gatekeeps milestones (§2 stage 11; Appendix A).
- Ratifies methodology recertification (§5).
- Arbitrates disagreement between internal and external review on Sensitive paths when CD cannot (§4).
What Joe does not do.
- Read code line-by-line in PRs.
- Catch bugs by inspection.
- Provide review-of-record on substantive code changes.
Where review depth comes from instead.
- CI — lint, type-check, build, Semgrep, tests w/ coverage, e2e on
main(forcing function: branch protection). - CC self-review —
reviewskill on every PR;security-reviewon Sensitive PRs (forcing function: PR description block). - Internal cross-model differential (bi-weekly; forcing function: empty-log blocker).
- External LLM review — per-PR scoped on Sensitive paths + bi-weekly broader (forcing functions: per-PR review comment required for merge; recurring ticket).
Joe-unavailable handling. Routine work (no Sensitive-path triggers) proceeds via CD → CC handoff with delayed Joe sign-off on intent (Joe ratifies after the fact). Sensitive-path work proceeds through CI + CC self-review + multi-model review and merges if and only if all gates pass; Joe ratifies risk after the fact. Milestone-gated work blocks until Joe approves intent — milestones are the only category where Joe's availability is a hard dependency, and that's by design.
Joe's highest-leverage act. The quarterly recertification session. ~30 min/quarter of Joe time produces ~the entire anti-entropy budget for the methodology.
§7. Tooling inventory
Last verified: 2026-04-28 Max age: 60 days (tooling shifts faster than other surfaces; check at each quarterly recertification, and event-trigger off-cycle when any layer transitions)
| Tool | Role | Status | Cross-reference |
|---|---|---|---|
| Branch protection (GitHub) | Workflow gate on main | Live since 2026-04-26 (NQU-652) | .claude/rules/git-workflow.md |
| GitHub Actions CI | Lint, type-check, build, Semgrep (p/typescript, p/security-audit, p/secrets, p/eslint-plugin-security), tests w/ coverage, e2e on main | Live | docs/admin/ops/deployment-flow.md §CI/CD Pipeline |
| Plan mode (CC) | Pre-execution review of approach | In use | (CC built-in) |
| Agent tool (CC) | CC self-review via subagent during PR | In use | (CC built-in) |
code-review skill (Anthropic-published) | Per-PR agentic code review on the diff. The required per-PR review gate (§3 enforcement model) | Installed 2026-04-28 — namespace code-review:code-review, allow-listed in .claude/settings.local.json. CI integration (the gate) is a follow-up CC ticket | Pilot status in Appendix B |
security-review skill (CC) | Agentic security review — required on Sensitive PRs alongside code-review | Available; runs in the same CI job as code-review once the workflow lands | Appendix B |
/ultrareview (Anthropic) | High-stakes paths; rate-limited | Available; reserved for §9 Sensitive paths beyond what security-review covers | (Anthropic-side) |
| Internal cross-model differential | Bi-weekly Claude-family differential | In use; template in docs/reviews/2026-03-15-cross-model-review.md | NQU-285 |
| External LLM review (multi-model) | Per-PR scoped + bi-weekly broader; pilot order in §4 | Pilot order committed; first paid candidate not yet selected | Appendix B |
| Sentry / Bedrock / quality-check observability | Post-deploy verification (§2 stage 10) | Live | (mechanical) |
| ConKurrence | Prompt validation; separate lifecycle | Out of scope here — see sister doc | docs/claude_desktop/prompt-lifecycle-methodology.md |
§8. RACI
Last verified: 2026-04-28 Max age: 90 days (revisit on team composition change or external-reviewer change)
R = Responsible (does the work). A = Accountable (sign-off authority). C = Consulted. I = Informed.
| Activity | Joe | CD | CC | External LLM |
|---|---|---|---|---|
| Intent / scope | A | C | I | — |
| Spec | C | R | I | — |
| Plan | A | C | R | — |
| Implementation | I | I | R | — |
| Self-review (per-PR) | I | I | R | — |
| CI gates | I | I | I | — |
| Per-PR external review (Sensitive) | I | C | R (driver) | R (reviewer) |
| Bi-weekly internal cross-model | C | R | C | — |
| Bi-weekly external-LLM differential | C | R | C | R |
| Substantive review convergence (Sensitive) | A (arbitrates ties) | R (adjudicates) | C | C |
| Deploy | I (auto on merge) | I | I | — |
| Post-deploy verification | I | C | R | — |
| Milestone gate | A | R | C | C |
| Methodology recertification | A | R | C | — |
Joe is A on intent, milestones, and methodology — never on code substance. That's the design.
§9. Operating definitions
Last verified: 2026-05-14 (added explicit three-category mapping to honor Joe's 2026-05-06 ratification — categories survive as derived facts, not as human-applied labels) Max age: 90 days (these are load-bearing; review at each quarterly recertification)
- Substantive review. Multi-agent + external-LLM differential analysis. Not Joe code-read. Output is review-log entries and PR-comment findings with explicit dispositions.
- Joe approval. Written sign-off on intent and risk in Linear or on the PR description. Does not imply Joe read the code.
- Production. State of
mainat HEAD. Every merge is a deploy. There is one environment. - Milestone. A discrete, named state change: F+F (done 2026-04-20), prod cutover (target ~2026-09-01), GA (TBD). Each milestone gets a one-time pre-cutover checklist (Appendix A).
- Sensitive path (file-path-triggered, no labels). A PR is treated as touching a Sensitive surface if it modifies any of:
- Auth:
app/api/auth/**,lib/auth/**, Cognito config ininfrastructure/terraform/**, route wrappers (createProtectedRoute,createPublicRoute) - Billing:
app/api/billing/**,lib/billing/**, Stripe webhook handlers, plan/pricing tables and migrations - Retention:
app/api/admin/cron/retention/**,lib/retention/**, retention-related migrations - PHI surfaces: evidence storage paths (
app/api/storage/**,lib/storage/**), audit-log surfaces (lib/audit/**), GDPR export/delete flows - Security boundary:
.github/workflows/*.yml, Semgrep config, route wrapper code, anything in.claude/rules/security.mdand.claude/rules/api-design.md - Infrastructure:
infrastructure/terraform/**,Dockerfile, ECS task definition, IAM policies, secrets references
- Auth:
- Continuous gates. CI + branch protection + CC self-review + per-PR external review when triggered. Every PR runs continuous gates.
- File-path-triggered rules (replace tier labels):
- All PRs: continuous gates always.
- PRs touching a Sensitive path: continuous gates and require a recent (<2 weeks) multi-model pass on the touched surface. If no recent pass exists, the PR triggers a per-PR external review and waits.
- Milestones: one-time checklist (Appendix A), outside the per-change flow.
- No "Routine / Sensitive / Milestone-gated" labels. No T0–T3. Rules fire automatically off file paths so there is nothing for a human to mis-classify.
- The three change categories (the Routine / Sensitive / Milestone-gated taxonomy Joe ratified 2026-05-06) survive as derived facts, not as labels:
- Routine = a PR touching no Sensitive paths. Continuous gates only. No human applies this label; it's true when the file-path triggers don't fire.
- Sensitive = a PR touching at least one Sensitive path. Continuous gates + recent multi-model pass.
- Milestone-gated = work scoped to a named milestone (F+F, prod cutover, GA, single-tenant licensed first-customer). One-time checklist (Appendix A).
- The taxonomy is what Joe ratified; deriving it from file paths and milestone events (rather than asking humans to label PRs) is the implementation. Substance: identical. Mis-classification surface: zero.
§10. Disposition of existing fragments
Last verified: 2026-04-28 Max age: 90 days (revisit when any disposition is acted on; the table is closed when all dispositions are executed)
| Doc | Disposition | Action ticket |
|---|---|---|
docs/admin/ops/git-workflow.md (CC's 2026-04-28 draft, T0–T3 tier system) | CUT. Operational rules already in .claude/rules/git-workflow.md. Tier system replaced by file-path-triggered rules (§9). | Separate small CC ticket — cuts file once this spine lands |
docs/admin/ops/deployment-flow.md | CROSS-REFERENCED. Deep mechanics of stage 9. Stays standalone. | None |
docs/admin/security/review-schedule.md | ABSORBED into §3 (weekly rotating focus areas) and §5 (quarterly deep dive). Old file gets a redirect note pointing here. | Separate small CD ticket |
docs/reference/developer-context.md | CROSS-REFERENCED in §0 and §6. Stays standalone. | None |
docs/claude_desktop/prompt-lifecycle-methodology.md | CROSS-REFERENCED as sister doc. This doc is its code analog; the prompt doc continues to govern prompt work. | None |
docs/reviews/2026-03-15-cross-model-review.md and successors | CANONICAL TEMPLATE for §4 bi-weekly review log entries. New entries follow the same structure (previous-review status table + consensus + single-agent + priority remediation). | None |
| F+F (2026-04-20) — undocumented at the time | RETROACTIVE NOTE in docs/decisions/ recording the actual gate that fired (CD/CC continuous check-in). One-time post-fact note, not a do-over. | Separate small CD ticket — out of scope for this doc |
§11. Acceptance criteria
Last verified: 2026-04-28 Max age: until ratified by Joe (this section closes once Joe signs off)
Status of each criterion as of this draft:
- Readable in <10 minutes — verified by length and density on draft completion.
- Every section has
Last verifieddate + max-age — every section above carries both. - Every recurring rhythm has a corresponding Linear recurring ticket — table in §3 has the
Linearcolumn populated; mechanical-only rhythms marked as such. - External LLM (multi-model) review is operationalized with a named ticket process — §4 defines the two-layer design; pilot order committed; per-PR comment + bi-weekly review log are the named artifacts.
- All existing fragmented process docs are listed in §10 with their disposition.
- Pre-prod cutover gate template exists as an appendix — see Appendix A.
- F+F-retroactive gate documented in
docs/decisions/as a one-time post-fact note — out of scope for this body draft; tracked as a separate small CD ticket per the brief. - [~] Pilot Anthropic
code-review/security-review, then CC codex skill, before paid services — pilot order is committed in §4; Appendix B tracks status. Layer 1 skill installed 2026-04-28; CI integration is the next forcing-function step (follow-up CC ticket). Pilot execution proceeds in parallel with this doc landing. - Joe reads it once, says "yes, this is what we do" or marks specific deltas — pending Joe review.
Appendix A. Pre-prod cutover gate (one-time checklist)
Last verified: 2026-04-28 Max age: 60 days through prod cutover (target ~2026-09-01); refreshed at each milestone use
Use this checklist for any milestone where the system's customer-facing posture changes (F+F, prod cutover, GA, single-tenant licensed deployment first-customer). Each milestone gets a one-time copy of this list as a Linear sub-issue under the milestone ticket.
Pre-conditions (must be true before checklist starts).
- Milestone scope is named and written in the milestone Linear issue. No "we'll see what's ready."
- All in-scope PRs are merged or explicitly cut.
Substantive review convergence.
- All Sensitive-path PRs in scope have a recent (<2 weeks) multi-model pass — internal cross-model and external LLM converged.
- Bi-weekly external-LLM differential review log entry exists for the cycle covering the milestone-window PRs.
- All HIGH-severity findings from the latest cross-model review are either fixed or documented as residual risk in the milestone ticket.
CI/CD and infra posture.
-
mainis green on the SHA being cut over. - Branch protection settings on
mainreviewed (current state matches.claude/rules/git-workflow.md). - Deployment flow (
docs/admin/ops/deployment-flow.md) reviewed end-to-end; no recent CI/CD changes that haven't been verified in a real deploy. - Smoke test (
/api/health) and post-deploy observability (Sentry, Bedrock latency, quality-check error rate) checked clean on the cut-over SHA.
Security and compliance.
- Latest quarterly deep-dive items closed or accepted: Semgrep clean (or accepted findings documented),
npm audit(or accepted), IAM review, Cognito password policy, S3 encryption + lifecycle. - Audit-log coverage check:
SELECT DISTINCT action FROM audit_logmatches expected actions for in-scope flows. - GDPR export/delete flows tested on a test account if any change touched them in the milestone window.
Joe sign-off (this is the only place Joe's availability is a hard dependency).
- Joe approves intent — the milestone scope is what we want to ship.
- Joe approves residual risk — written acceptance of every HIGH-severity finding being kept open.
- Joe records the milestone declaration on the milestone Linear ticket, in writing.
Post-milestone.
- Add a
docs/decisions/YYYY-MM-DD-<milestone>.mdADR recording: scope, gates that fired, residual risks, Joe sign-off ref. - Trigger an off-cycle methodology recertification (§5 event triggers) — every milestone shifts assumptions.
Appendix B. Tooling pilot status
Last verified: 2026-04-28 Max age: 30 days (pilot is in-flight; status changes frequently)
Pilot order is committed in §4. This appendix tracks live status. Updated at each quarterly recertification, or whenever a layer transitions (an off-cycle event trigger).
| # | Layer | Vendor | Cost | Pilot status | Sample size | Decision date |
|---|---|---|---|---|---|---|
| 1 | Anthropic code-review skill | Anthropic | Free | Skill installed 2026-04-28 (allow-listed via Skill(code-review:code-review)). Manual-invocation phase: CC runs it via the Agent tool on every PR and posts output as a PR comment by hand. CI-integration phase begins when .github/workflows/code-review.yml + scripts/check-review-dispositions.ts + branch-protection update land (follow-up CC ticket). Pilot acceptance criterion: ≥10 PRs across ≥3 Sensitive surfaces with the skill having produced at least one finding that prior layers (CI Semgrep, type-check, tests) missed | 0 / 10 | TBD |
| 1b | Anthropic security-review skill | Anthropic | Free | Runs in the same CI job as layer 1 once the workflow lands. Required on Sensitive paths (§9) | 0 / 10 | TBD |
| 2 | CC codex skill (non-Anthropic external review) | OpenAI (Codex) | Free / per-token | Not started — pilot begins after layer 1 produces a baseline of what same-vendor review catches. This is the multi-model-by-design lever (§4); layer 1 alone does not satisfy the multi-model principle (same family) | 0 / 10 | TBD |
| 3 | Paid service (CodeRabbit / Greptile / Bito) | TBD | Per-PR or per-seat | Not evaluated — only triggered if layers 1 + 2 fail to deliver useful, distinct findings | — | — |
Pilot exit criterion (each layer). A layer is "in" once it has produced useful findings on a representative PR sample (≥10 PRs covering at least 3 Sensitive surfaces). "Useful" = at least one finding the prior layers missed, or repeated useful-confirmation that prior layers' findings are real. A layer that produces only noise on the sample is dropped and the next layer starts.
Privacy posture. Any external-LLM review tool that ingests source code must be evaluated for: where the diff goes, retention policy, training data inclusion, and whether the tool is acceptable for Sensitive paths under the .claude/rules/security.md constraints. This evaluation is a precondition for any paid-service decision and is tracked separately when triggered.