From 4fac93be78599eb6c1a5cada58be118d6cf4947f Mon Sep 17 00:00:00 2001 From: jared Date: Fri, 17 Jul 2026 14:34:22 -0400 Subject: [PATCH] os-sdlc: standards-and-conventions + debugger nodes; reviewer scope = judgment residue MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New nodes: standards-and-conventions (three-layer opinion/bindings/adoption model, Option B decided; residue rule — lint-enforceable rules stay out of every agent prompt; audience×facet routing; Ruby lint depth reek/mutant) and debugger (stuck-path specialist distinct from reviewer, feeds harness improvement). Both post-tracer-bullet, off the pre-v1 grill queue. Sharpened reviewer scope to judgment residue in pipeline-stages, added the enabling feedback-loop framing to deterministic-gates, and the standards-minimization + lint-copy autoresearch loops to self-improvement-loops. OVERVIEW map/index/sequencing + back-edges. Co-Authored-By: Claude Opus 4.8 --- plugins/os-sdlc/OVERVIEW.md | 25 ++++-- .../reference/agent-design-principles.md | 2 +- plugins/os-sdlc/reference/debugger.md | 57 ++++++++++++ .../os-sdlc/reference/deterministic-gates.md | 11 ++- plugins/os-sdlc/reference/never-ask-twice.md | 2 +- plugins/os-sdlc/reference/pipeline-stages.md | 17 ++-- .../reference/self-improvement-loops.md | 22 ++++- .../reference/standards-and-conventions.md | 88 +++++++++++++++++++ 8 files changed, 207 insertions(+), 17 deletions(-) create mode 100644 plugins/os-sdlc/reference/debugger.md create mode 100644 plugins/os-sdlc/reference/standards-and-conventions.md diff --git a/plugins/os-sdlc/OVERVIEW.md b/plugins/os-sdlc/OVERVIEW.md index 453c275..809c834 100644 --- a/plugins/os-sdlc/OVERVIEW.md +++ b/plugins/os-sdlc/OVERVIEW.md @@ -1,6 +1,6 @@ # os-sdlc — overview & concept map (v0.2) -_Last updated: 2026-07-16. Status: design mapped, no implementation yet._ +_Last updated: 2026-07-17. Status: design mapped, no implementation yet._ _This is the single entry point: an AI pointed here loads only the reference/ nodes its task needs, following the map below._ @@ -42,9 +42,15 @@ graph TD NAT <--> SIL[self-improvement-loops] PO --> SIL SIL --> PF + DG -.post-v1.-> SC[standards-and-conventions] + SC -.residue.-> PS + NAT -.pre-seed.-> SC + DG -.stuck/post-v1.-> DBG[debugger] + DBG --> SIL PS -.deferred.-> HZ[horizon] WP -.deferred.-> HZ NAT -.mobbin.-> HZ + DBG -.adversarial.-> HZ ``` ## Index @@ -60,7 +66,9 @@ graph TD | [never-ask-twice](reference/never-ask-twice.md) | direction | The agency mechanism: two-tier lookup → mint-time scope classification → audit promotion; decision-category autonomy labels | | [self-improvement-loops](reference/self-improvement-loops.md) | direction | Session audits, ADR audits, eval harnesses, skill-lint — each catches a different drift | | [plugin-factory](reference/plugin-factory.md) | direction | Same factory builds plugins from a PRD; the eval harness is the green command | -| [horizon](reference/horizon.md) | horizon | Wake-on-trigger, Herdr controller, router agent, Mobbin — preserved intent, explicitly out of v1 | +| [standards-and-conventions](reference/standards-and-conventions.md) | direction (Option B decided) | Author a standard once; three layers (opinion/bindings/adoption); lint-enforceable rules stay in nobody's prompt, only judgment residue reaches the reviewer | +| [debugger](reference/debugger.md) | direction (deferred) | Stuck-path specialist, distinct from the reviewer; independent reconstruction + diff, feeds harness improvement; not the adversarial reviewer | +| [horizon](reference/horizon.md) | horizon | Wake-on-trigger, Herdr controller, router agent, Mobbin, adversarial reviewer — preserved intent, explicitly out of v1 | ## Working philosophy (design target, not preference) @@ -78,10 +86,15 @@ graph TD ## Build sequencing v1 = the tracer bullet in [pipeline-stages](reference/pipeline-stages.md), -triggered manually, walked by hand once before wiring into skills/hooks/agents. -Everything in [horizon](reference/horizon.md) stays unbuilt until the interactive -factory is trusted. Open items live per-node in each doc's "Open questions" — -this file carries none. +triggered manually, walked by hand once with disposable code and trivial prompts +before wiring into skills/hooks/agents. **Code quality is deliberately a later +phase:** [standards-and-conventions](reference/standards-and-conventions.md) and +[debugger](reference/debugger.md) are post-tracer-bullet, built alongside +[self-improvement-loops](reference/self-improvement-loops.md) — nail the flow +first, dial in quality once the happy path is trusted. Everything in +[horizon](reference/horizon.md) stays unbuilt until the interactive factory is +trusted. Open items live per-node in each doc's "Open questions" — this file +carries none. **Grill queue** (decided 2026-07-16): the critical path is [spec-and-ticket-layer](reference/spec-and-ticket-layer.md) → diff --git a/plugins/os-sdlc/reference/agent-design-principles.md b/plugins/os-sdlc/reference/agent-design-principles.md index de7ddde..b9b069b 100644 --- a/plugins/os-sdlc/reference/agent-design-principles.md +++ b/plugins/os-sdlc/reference/agent-design-principles.md @@ -1,7 +1,7 @@ # agent design principles _Status: settled — as of 2026-07-16_ -_Connects to: [pipeline-stages](pipeline-stages.md), [deterministic-gates](deterministic-gates.md), [overview](../OVERVIEW.md)_ +_Connects to: [pipeline-stages](pipeline-stages.md), [deterministic-gates](deterministic-gates.md), [standards-and-conventions](standards-and-conventions.md), [debugger](debugger.md), [overview](../OVERVIEW.md)_ ## Purpose diff --git a/plugins/os-sdlc/reference/debugger.md b/plugins/os-sdlc/reference/debugger.md new file mode 100644 index 0000000..5ad2ae8 --- /dev/null +++ b/plugins/os-sdlc/reference/debugger.md @@ -0,0 +1,57 @@ +# debugger + +_Status: direction — deferred (post-v1) — as of 2026-07-17_ +_Connects to: [deterministic-gates](deterministic-gates.md), [pipeline-stages](pipeline-stages.md), [self-improvement-loops](self-improvement-loops.md), [agent-design-principles](agent-design-principles.md), [overview](../OVERVIEW.md)_ + +## Purpose + +Names the stuck-path specialist that is deliberately *not* the reviewer, and defines its dual +identity: it solves the ticket the cheaper team couldn't, and it generates a harness-improvement +signal from *why* they got stuck. Load this only when the happy path is trusted and stuck runs +are worth investing in — not before. + +## Design + +- **Distinct from the reviewer, and added later.** The reviewer runs on the happy path where + lint + tests already pass and only judgment remains ([pipeline-stages](pipeline-stages.md)). + The debugger runs on the *stuck* path — triggered when the max-iteration cap in + [deterministic-gates](deterministic-gates.md) escalates, i.e. a cheaper programmer/test-writer + team could not reach green. Different job, different trigger; do not merge them. +- **Expensive by design, rare by frequency.** It only fires on escalation, so it is the one + place opus-tier reasoning is unambiguously worth it — it is solving problems less-capable + models already failed. Cost is amortized across all the runs that *didn't* need it. +- **Independent reconstruction, then diff.** Rather than debugging the stuck team's code + in place, the debugger works the ticket from context on its own — its own tests, its own + implementation — then compares that against what the stuck team produced. The delta is the + diagnosis: it usually reveals *why* the original team stalled (a misread spec, a + test-writer that boxed itself in, a gate whose feedback pointed the wrong way). +- **The diagnosis feeds the harness, not just the ticket.** That "why they got stuck" delta + is an improvement signal for [self-improvement-loops](self-improvement-loops.md) — recurring + stall causes become harness/prompt/gate fixes, so the *next* cheap team clears the same + class of problem without escalating. +- **Lint-thrash is one of its named checks.** A programmer failing the *same* lint rule across + iterations is a strong signal the rule's *explanation* — not the code — is at fault: the + copy is failing to direct the fix. The debugger flags this as a lint-explanation-quality + defect (see [self-improvement-loops](self-improvement-loops.md) for the copy-formula + autoresearch loop it feeds), distinct from a genuinely hard ticket. +- **Not the adversarial reviewer.** Edge-case hardening / adversarial review is a separate, + further-out role ([horizon](horizon.md)) — v1 targets 99% good-enough; the 1% edge cases + wait. The debugger is a *stuck-solver*, not an attacker. + +## Open questions + +- Independent-reconstruction is the tentative mechanism, not settled — it may be cheaper to + have the debugger inspect the stuck team's exhaust first and reconstruct only on a real + miss. Decide against real stuck runs, not up front. +- What the debugger writes down when it succeeds (the improvement-signal format) and how it + routes to [self-improvement-loops](self-improvement-loops.md) — shared audit-report format, + or a bespoke stall-report? +- Threshold for "lint-thrash" (same rule N times) and whether that check lives in the gate + itself (cheap, deterministic) rather than waiting for the debugger to notice. + +## Sources + +- [deterministic-gates](deterministic-gates.md) (max-iteration escalation — the trigger) +- [pipeline-stages](pipeline-stages.md) (reviewer, the happy-path counterpart) +- [self-improvement-loops](self-improvement-loops.md) (harness-improvement + lint-copy loops) +- 2026-07-17 design session (this doc's origin) diff --git a/plugins/os-sdlc/reference/deterministic-gates.md b/plugins/os-sdlc/reference/deterministic-gates.md index 763fd0c..c3d00bb 100644 --- a/plugins/os-sdlc/reference/deterministic-gates.md +++ b/plugins/os-sdlc/reference/deterministic-gates.md @@ -1,7 +1,7 @@ # deterministic gates _Status: settled — as of 2026-07-16_ -_Connects to: [pipeline-stages](pipeline-stages.md), [agent-design-principles](agent-design-principles.md), [plugin-factory](plugin-factory.md), [overview](../OVERVIEW.md)_ +_Connects to: [pipeline-stages](pipeline-stages.md), [agent-design-principles](agent-design-principles.md), [plugin-factory](plugin-factory.md), [standards-and-conventions](standards-and-conventions.md), [debugger](debugger.md), [overview](../OVERVIEW.md)_ ## Purpose @@ -17,8 +17,13 @@ when wiring hook events for os-sdlc. *claims*, at zero additional LLM cost. - On failure, the failing output is injected into the same agent's next turn as context — not routed to a different agent, so the agent that wrote the code gets the direct feedback loop. - A max-iteration counter escalates to the human after N failed attempts, rather than looping - indefinitely. + A max-iteration counter escalates after N failed attempts, rather than looping indefinitely + (v1: to the human; later: to the [debugger](debugger.md)). +- **This feedback loop is what makes the residue rule possible:** because the gate *tells* an + agent which quality rule it broke, only on violation, no agent needs the rulebook in + standing context. The depth of what the gates can enforce (rubocop/reek/flay/mutant for + Ruby, and the symptoms-not-choices ceiling) lives in + [standards-and-conventions](standards-and-conventions.md); this node owns only the mechanism. - **Red-assert and green-assert gates** (defined in [pipeline-stages](pipeline-stages.md)) are the two concrete applications of this rule in the v1 pipeline: red-assert proves the tests actually exercise unbuilt behavior, green-assert diff --git a/plugins/os-sdlc/reference/never-ask-twice.md b/plugins/os-sdlc/reference/never-ask-twice.md index 3c326a9..3d3e975 100644 --- a/plugins/os-sdlc/reference/never-ask-twice.md +++ b/plugins/os-sdlc/reference/never-ask-twice.md @@ -1,7 +1,7 @@ # never ask twice _Status: direction — as of 2026-07-16_ -_Connects to: [self-improvement-loops](self-improvement-loops.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [horizon](horizon.md), [overview](../OVERVIEW.md)_ +_Connects to: [self-improvement-loops](self-improvement-loops.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [standards-and-conventions](standards-and-conventions.md), [horizon](horizon.md), [overview](../OVERVIEW.md)_ ## Purpose diff --git a/plugins/os-sdlc/reference/pipeline-stages.md b/plugins/os-sdlc/reference/pipeline-stages.md index 10e21c6..223b314 100644 --- a/plugins/os-sdlc/reference/pipeline-stages.md +++ b/plugins/os-sdlc/reference/pipeline-stages.md @@ -1,7 +1,7 @@ # pipeline stages _Status: direction — as of 2026-07-16_ -_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [pipeline-observability](pipeline-observability.md), [overview](../OVERVIEW.md)_ +_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [spec-and-ticket-layer](spec-and-ticket-layer.md), [worktree-parallelism](worktree-parallelism.md), [pipeline-observability](pipeline-observability.md), [standards-and-conventions](standards-and-conventions.md), [debugger](debugger.md), [overview](../OVERVIEW.md)_ ## Purpose @@ -23,8 +23,10 @@ Manually triggered by `/implement `. Stages, in order: 4. **Programmer agent** — makes the tests pass. One agent, not a seam-creator/implementor split. 5. **Green-assert gate** (deterministic hook) — suite + lint must pass. Failures are - auto-fed back into the same programmer's next turn; a max-iterations cap escalates to the - human rather than looping forever. + auto-fed back into the same programmer's next turn; a max-iterations cap escalates rather + than looping forever. In v1 escalation goes to the human; once the happy path is trusted, + the stuck path routes to the [debugger](debugger.md) first — a separate agent from the + reviewer below. 6. **Reviewer agent** — a *named agent* (not a skill), so its tool surface is minimal and its context never leaks into the orchestrator's (see [agent-design-principles](agent-design-principles.md)). It reads only a hook-assembled @@ -33,8 +35,13 @@ Manually triggered by `/implement `. Stages, in order: document by a code-actor hook before the agent is invoked; the reviewer runs nothing itself. Two ordered checks: first tests align with the spec/ticket, then code aligns with both tests and spec. Order matters — misaligned tests invalidate a "code passes - tests" result. ADR-0037's `/os-sdlc:review` (standards-conformance + spec-fidelity + - Fowler refactor smells) is satisfied by this same agent; if standalone review of an + tests" result. **Scope is the judgment residue only** — code *standards/conventions* are + already proven mechanically by the gates ([standards-and-conventions](standards-and-conventions.md)), + so the reviewer never re-checks them; it checks spec fidelity, test relevance, and that + the code solves the assigned problem rather than merely gaming the tests. Because mechanical + quality is a settled precondition, this is normally a **single-shot opus** call over that + packet. ADR-0037's `/os-sdlc:review` (spec-fidelity + judgment-residue smells) is + satisfied by this same agent; if standalone review of an arbitrary diff is wanted outside a pipeline run, a thin skill wrapper dispatches the agent with a hand-assembled packet — one reviewer, two entry points. 7. **Cleanup & report** (agent/code mix) — trims scratch artifacts, produces a summary for the diff --git a/plugins/os-sdlc/reference/self-improvement-loops.md b/plugins/os-sdlc/reference/self-improvement-loops.md index eabc262..efb847d 100644 --- a/plugins/os-sdlc/reference/self-improvement-loops.md +++ b/plugins/os-sdlc/reference/self-improvement-loops.md @@ -1,7 +1,7 @@ # self improvement loops _Status: direction — as of 2026-07-16_ -_Connects to: [never-ask-twice](never-ask-twice.md), [plugin-factory](plugin-factory.md), [pipeline-observability](pipeline-observability.md), [overview](../OVERVIEW.md)_ +_Connects to: [never-ask-twice](never-ask-twice.md), [plugin-factory](plugin-factory.md), [pipeline-observability](pipeline-observability.md), [standards-and-conventions](standards-and-conventions.md), [debugger](debugger.md), [overview](../OVERVIEW.md)_ ## Purpose @@ -43,6 +43,26 @@ audit's own cost/latency never blocks a ticket. lints `SKILL.md` files for progressive disclosure on complex tasks and reasonable file sizes, keeping agent context windows lean as the skill corpus grows. +Two agent-tuning applications of loop (c)'s autoresearch pattern, both post-tracer-bullet: + +- **Standards minimization** ([standards-and-conventions](standards-and-conventions.md)) — + the production agents (programmer/test-writer/reviewer) run with *minimal* standards in + prompt; a full-standards **Judge** critiques the output and returns clues about which + standard was missed. Keep/discard on those clues admits a prompt line only when it fixes an + observed failure category — same coverage as front-loading everything, far less standing + context. Discipline: baseline at *zero* standards first; **judge clues feed the tuning loop + only, never a production run** (the runtime feedback channel stays the deterministic gate); + judge **per stage** (so you know whose prompt to tune) with one end-to-end score as a + guardrail against stages locally optimizing against each other. +- **Lint-explanation copy-formula** — the [debugger](debugger.md)'s lint-thrash signal (a + programmer failing the same rule repeatedly) says a gate *message* is failing to direct the + fix. Autoresearch a copy formula (structure + perspective) that maximizes fix-rate per + token of explanation — the linter messages are effectively the agent's prompt now, so their + quality is worth tuning. + +The [debugger](debugger.md) is a fifth improvement input: its "why the stuck team stalled" +diagnosis turns recurring stall causes into harness/prompt/gate fixes. + Together, these four loops are: - the **promotion engine** for [never-ask-twice](never-ask-twice.md) — (b) is the mechanism that actually performs the audit-driven promotion that mechanism depends on; diff --git a/plugins/os-sdlc/reference/standards-and-conventions.md b/plugins/os-sdlc/reference/standards-and-conventions.md new file mode 100644 index 0000000..0a35b93 --- /dev/null +++ b/plugins/os-sdlc/reference/standards-and-conventions.md @@ -0,0 +1,88 @@ +# standards and conventions + +_Status: direction (Option B decided) — as of 2026-07-17_ +_Connects to: [deterministic-gates](deterministic-gates.md), [agent-design-principles](agent-design-principles.md), [never-ask-twice](never-ask-twice.md), [self-improvement-loops](self-improvement-loops.md), [overview](../OVERVIEW.md)_ + +## Purpose + +Defines once, and reuses everywhere, the coding standards and conventions the factory +applies across many languages and frameworks (e.g. Sandi Metz 99-Bottles OOP for all OOP +languages) — so a standard is authored a single time, not redefined per project. Load this +before designing project onboarding, the green command, or any standard-carrying context +packet for a pipeline agent. + +## Design + +- **Three layers, separated on purpose:** + 1. **The opinion** — language-agnostic prose (the Metz rules themselves). Written once. + 2. **Per-language bindings** — executable configs (`.rubocop.yml`, eslint fragment, + `ruff.toml`) each tagged with the standard + version it implements. One opinion, N + bindings: this is where cross-language overlap resolves. + 3. **Per-project adoption** — a project copies the right bindings, wires the green command, + and records a repo ADR ("adopts `sandi-metz-oop` v2 for Ruby") linking the vault opinion. +- **Layout — Option B (DECIDED).** Opinion lives in the vault as a `convention/` note (the + cross-project source of truth, per [never-ask-twice](never-ask-twice.md)); executable + bindings ship in the plugin because they are deployable, git-versioned/diffable artifacts + and the vault is a knowledge graph, not an artifact store. Precedent: + `plugins/cc-architect/references/conventions/cc-os-naming.md` (canonical repo copy; vault + note defers to it). + ``` + ~/Documents/SecondBrain/convention/sandi-metz-oop.md # opinion; links to bindings + plugins/os-sdlc/standards/sandi-metz-oop/ + standard.md # canonical prose (vault note defers here) + ruby/rubocop.yml javascript/eslintrc.json python/ruff.toml + ``` +- **The residue rule: anything lint-enforceable is in nobody's prompt.** An agent is never + told the arity/length/naming limit — the green command's linter tells it, only on + violation, injected into its own next turn (mechanism: [deterministic-gates](deterministic-gates.md)). + Standing context cost of enforceable rules is therefore zero. Only the *judgment residue* a + linter cannot check (abstraction choice, "composition over inheritance", pattern selection) + is ever routed into a prompt — and only into the reviewer's ([pipeline-stages](pipeline-stages.md)). +- **Routing key: standard × language × audience × facet.** Each standard's prose is sectioned + by facet (interface / implementation / test) and audience-tagged, so the context packet is + a mechanical section-filter, not a per-session judgment call: + - **programmer** — gets *nothing* standing; learns quality rules only as gate feedback. + - **test-writer** — is the interface designer in a red-first pipeline, so it gets test + conventions **plus the interface facet** (naming, public message shape, arity-as-interface) + — but not implementation-facing rules (method length, private structure, duplication). + - **reviewer** — gets the judgment-facet residue; it is the designated judgment actor. +- **How far linting reaches (Ruby, the deep case):** `rubocop` (metrics/style/naming, custom + cops for house rules), **`reek`** (semantic smells — feature envy, data clumps, control + coupling; much of "Metz taste" is reek findings), `flay`/`flog` (structural duplication / + complexity), **`mutant`** (mutation testing — deterministically proves the tests *constrain* + behavior, keeping the test-writer honest and mechanically answering the "gaming the + green-assert gate" concern in [pipeline-stages](pipeline-stages.md)). JS (eslint+plugins) / + Python (ruff) are shallower but workable. Ceiling: tools detect **symptoms, not choices** — + they police the boundaries of good code; the reviewer polices the choices within them. +- **Pre-seeding, not just mining.** The Mobbin move from [never-ask-twice](never-ask-twice.md) + generalizes: our own standards are self-sourced pre-seeds — writing `convention/sandi-metz-oop` + up front lets the "OOP approach" decision category start at `afk-ready` instead of being + re-asked per project. This is the concrete cure for "defined Metz a dozen times." +- **Sequencing (hard constraint):** all of this is **post-tracer-bullet**. v1 nails the flow + with disposable code and trivial prompts; standards/gate-tuning land afterward, alongside + [self-improvement-loops](self-improvement-loops.md). Do not add quality gates before the + happy path is trusted. + +## Open questions + +- **Adoption/update ownership.** First-time adoption (copy bindings, wire green command) is + naturally an os-sdlc onboarding skill. Drift-checking (a project on an outdated standard + version) *might* extend os-status — but os-status:fix is scoped to "the cc-os approach," + whereas this layer targets arbitrary client projects in many languages. Ownership unsettled. +- **Gate strictness is a tuning parameter, not an ideology.** A maximal cop wall can thrash a + cheap model (fix one violation → trigger another) and burn the iteration budget. Tune + strictness against iteration counts via autoresearch, same as prompt text — baseline at + *zero* standards first (audit defaults before customizing) and admit each rule only if it + beats that baseline. +- **Auditing existing projects is deferred.** One cheap harvest now: seed the canonical Metz + standard + first Ruby binding from the *best* of the dozen existing definitions. The other + projects reconcile later via the version-check path, one at a time (like ADR rollout). +- Bindings for non-OOP standards (functional, framework-conformance) — schema unproven. + +## Sources + +- SecondBrain vault: `convention/` facet, `matt-pocock-skills-v1-1-changes.md` +- `plugins/cc-architect/references/conventions/cc-os-naming.md` (Option B precedent) +- Ruby toolchain: rubocop, reek, flay, flog, mutant +- ADR-0037; [never-ask-twice](never-ask-twice.md) (vault-as-source-of-truth split) +- 2026-07-17 design session (this doc's origin)