os-sdlc: never-ask-twice grilled — ideation-primary lookup-and-mint (ADR-0045), two-state readiness replaces autonomy trio (ADR-0046)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SiGCD6Kur98fgPKMsJ14Xk

docs/adr/0045-never-ask-twice-mechanism-formalized-ideation-primary-lookup-and-mint-over-os-adr-and-os-vault.md

@@ -0,0 +1,27 @@
+---
+id: "0045"
+date: 2026-07-18
+status: Accepted
+supersedes:
+superseded-by:
+affected-paths: [plugins/os-sdlc/reference/never-ask-twice.md, plugins/os-sdlc/, plugins/os-adr/skills/find/, plugins/os-adr/skills/create/, plugins/os-vault/skills/query/, plugins/os-vault/skills/write/, plugins/os-backlog/]
+affected-components: [os-sdlc, os-adr, os-vault, os-backlog]
+---
+
+# 0045 — Never-ask-twice mechanism formalized: ideation-primary lookup-and-mint over os-adr and os-vault
+
+## Context
+
+The factory family (os-sdlc, os-adr, os-vault, os-backlog) needs an operating principle that stops the human being asked the same question on every run. Prior to this ADR the mechanism existed only as design intent in plugins/os-sdlc/reference/never-ask-twice.md, spanning four plugins with no single owner and no recorded decision. A 2026-07-18 grill settled the open questions: where human-input points live, how lookup happens, how records get minted, and how the ADR/vault-convention boundary is drawn.
+
+## Decision
+
+Adopt a cross-plugin, ideation-primary never-ask-twice mechanism owned jointly by os-sdlc, os-adr, os-vault, and os-backlog. (1) Home: human-input points live in the ideation phases (grill / to-spec / to-tickets), not the implementation pipeline; the pipeline keeps one thin valve — a mid-implementation spec gap is a ticket defect that fails back to the spec layer, never an inline ask. Standards reach implementation via lint rules and agent prompts. (2) Lookup: a single batched pre-pass runs at session load (`/os-adr:find` then `/os-vault:query` over relevant facets), and questions are drafted against that corpus; a topic-shift mid-interview triggers a re-lookup for the new topic, not per-question inline lookups. (3) Minting: answers accumulate in a running decisions-so-far list during the interview (crash/resume mitigation); at settle, the skill proposes a scope classification for the whole batch (repo ADR vs. vault convention), the human confirms once, and everything mints together — the session is not complete until the mint pass has run. (4) ADR/convention delineation: conventions are defaults that hold until overridden; ADRs are project-local adoptions of, or deviations from, them. The mint-time scope question plus periodic audit are the entire promotion/demotion machinery; promotion and demotion happen only in audits, never mid-run, with cadence deferred to the self-improvement-loops design. No new storage system and no literal decision-tree engine — the existing ADR corpus and vault conventions ARE the tree; os-sdlc adds only wiring on top of os-adr and os-vault.
+
+## Consequences
+
+Easier: grill/to-spec/to-tickets sessions stop re-asking settled questions; a decision recorded once is findable everywhere it applies; the pipeline stays mechanical since spec gaps route back to ideation instead of prompting inline. Harder: the mechanism guarantees plumbing (findability) but not judgment (applying the right convention in an ambiguous case) — mis-minted conventions are only caught at artifact review or audit demotion, not prevented up front; the pre-pass adds a lookup step to every ideation session load; nothing enforces the mint-pass-before-complete rule except skill discipline, since there is no dedicated storage or engine tracking session completeness.
+
+## Alternatives rejected
+
+A literal decision-tree engine or dedicated new storage system for decisions — rejected: the ADR corpus plus vault conventions already serve as the tree; a new system would duplicate os-adr/os-vault for no added capability. Per-question inline lookups (query os-adr/os-vault live as each question is drafted) — rejected in favor of one batched pre-pass per session plus topic-shift re-lookup: cheaper, and the interview's question set is knowable up front except when the topic genuinely shifts. A dedicated promotion/demotion skill or a new taxonomy for the ADR/convention boundary — rejected: the mint-time scope question and periodic audit are sufficient boundary machinery; the existing ADR-011 six flat facets already organize the domain the grill pre-pass queries.

docs/adr/0046-ticket-readiness-labels-ready-for-agent-ready-for-human-replace-the-hitl-semi-afk-ready-autonomy-trio.md

@@ -0,0 +1,27 @@
+---
+id: "0046"
+date: 2026-07-18
+status: Accepted
+supersedes:
+superseded-by:
+affected-paths: [plugins/os-backlog/skills/route/SKILL.md, plugins/os-backlog/skills/capture/SKILL.md, plugins/os-backlog/skills/list/SKILL.md, plugins/os-sdlc/reference/never-ask-twice.md, docs/adr/0029-os-backlog-card-move-with-cli-enforced-column-ownership-afk-ready-cards-skip-review.md, docs/adr/0042-retire-planka-git-issues-are-the-single-tracker-for-state-and-specs.md]
+affected-components: [os-backlog, os-sdlc]
+---
+
+# 0046 — Ticket readiness labels ready-for-agent/ready-for-human replace the hitl/semi/afk-ready autonomy trio
+
+## Context
+
+ADR-0029 gave the hitl/semi/afk-ready autonomy trio its operational semantics in the Planka era (afk-ready cards skip Review, hitl cards are never moved by the AI), and ADR-0042 (retiring Planka) carried the trio forward 'unchanged' into the git-issues label scheme as part of a broader tracker migration. Neither ADR enumerated or originated the full ten-label taxonomy (priority P0-P3, autonomy hitl/semi/afk-ready, state next/waiting/review) as a designed set — that enumeration exists only in plugins/os-backlog/skills/route/SKILL.md. Revisiting the trio during the 2026-07-18 never-ask-twice grill (parent mechanism: ADR-0045) found the semi/hitl boundary has no operational test: nothing distinguishes when a ticket needs a human check-in mid-flight versus proceeding autonomously, and artifact/PR review already provides proceed-and-flag for free regardless of the label. Matt Pocock's /triage skill offers a two-state readiness vocabulary with a falsifiable test instead.
+
+## Decision
+
+Retire the hitl/semi/afk-ready autonomy trio. Replace it with two-state ticket readiness: ready-for-agent (falsifiable test: 'fully specified — an agent completes it without asking'; an agent that asks a clarifying question or bounces the ticket disproves the label) and ready-for-human. A ticket that is neither is under-decomposed: split it into ordered agent/human parts, agent-first where dependencies allow — never given a third label or left unlabeled in limbo. This is paired with two-state decision-category coverage (a record exists, so proceed and cite it, or it doesn't, so ask) which needs no label or config surface of its own. os-backlog's taxonomy drops from ten labels to nine: priority P0-P3, readiness ready-for-agent/ready-for-human, state next/waiting/review. route/capture/list skill label lists, and existing labeled tickets, need updating (tracked as a follow-up issue, not done in this ADR).
+
+## Consequences
+
+Easier: readiness has an operationally checkable definition instead of a subjective hitl/semi split; production usage itself falsifies mislabeled tickets (an agent asking or bouncing proves the ticket wasn't ready-for-agent), giving a feedback signal the old trio never had; under-decomposed work is forced into explicit splits instead of hiding behind a middling label. Harder: every project that adopted the ten-label taxonomy via /os-backlog:route needs a migration pass (new labels created, old ones retired, open issues relabeled) before its next ticket-working session; route/capture/list SKILL.md all need their label lists updated; ADR-0042's 'autonomy labels carry over unchanged' claim is now stale prose in an otherwise-standing ADR.
+
+## Alternatives rejected
+
+Keep the three-tier hitl/semi/afk-ready trio — rejected: the semi/hitl boundary was never operationally testable, and artifact/PR review already delivers the proceed-and-flag behavior semi was meant to provide, making the middle tier redundant. Add a third readiness label for under-decomposed tickets rather than forcing a split — rejected: a third label re-creates an untestable middle tier by another name; splitting into agent/human parts is mechanical and keeps every ticket in a checkable state. Leave the ten-label taxonomy as-is and treat readiness as an orthogonal new label set — rejected: ready-for-agent/ready-for-human directly replace autonomy rather than adding to it, since the old and new labels encode the same slot (how a ticket should be worked) and running both would be redundant, not additive.

docs/adr/README.md

@@ -51,4 +51,6 @@ One file per decision, `NNNN-kebab-title.md`, created via `/os-adr:create`.
 | 0042 | [Retire Planka: git issues are the single tracker for state and specs](0042-retire-planka-git-issues-are-the-single-tracker-for-state-and-specs.md) | Accepted | 2026-07-16 |
 | 0043 | [Absolute delegation policy: main loop as executive with enumerated exemptions](0043-absolute-delegation-policy-main-loop-as-executive-with-enumerated-exemptions.md) | Accepted | 2026-07-17 |
 | 0044 | [Minimal-prompt discipline: prompt wording is added only in response to observed failures](0044-minimal-prompt-discipline-prompt-wording-is-added-only-in-response-to-observed-failures.md) | Accepted | 2026-07-18 |
+| 0045 | [Never-ask-twice mechanism formalized: ideation-primary lookup-and-mint over os-adr and os-vault](0045-never-ask-twice-mechanism-formalized-ideation-primary-lookup-and-mint-over-os-adr-and-os-vault.md) | Accepted | 2026-07-18 |
+| 0046 | [Ticket readiness labels ready-for-agent/ready-for-human replace the hitl/semi/afk-ready autonomy trio](0046-ticket-readiness-labels-ready-for-agent-ready-for-human-replace-the-hitl-semi-afk-ready-autonomy-trio.md) | Accepted | 2026-07-18 |
 <!-- adr-index:end -->

plugins/os-sdlc/OVERVIEW.md

@@ -38,7 +38,7 @@ graph TD
     PS --> WP[worktree-parallelism]
     DG --> PF[plugin-factory]
     PS --> PO[pipeline-observability]
-    PS -.blocked stage.-> NAT[never-ask-twice]
+    PS -.spec-gap fail-back.-> NAT[never-ask-twice]
     NAT <--> SIL[self-improvement-loops]
     PO --> SIL
     SIL --> PF
@@ -63,7 +63,7 @@ graph TD
 | [agent-design-principles](reference/agent-design-principles.md) | settled | Single job, minimal tool allowlist (programmer: no Bash), settled facts in via prompt, minimum out via return format |
 | [worktree-parallelism](reference/worktree-parallelism.md) | direction | Worktree-per-spec, sequential tickets within a spec, parallel across specs, human merge gate |
 | [pipeline-observability](reference/pipeline-observability.md) | direction | What a run writes down (exhaust), where it lives, predefined lifespans (os-doc-hygiene); copy-tag-audit pattern feeds the loops |
-| [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 |
+| [never-ask-twice](reference/never-ask-twice.md) | settled (grilled 2026-07-18) | The agency mechanism, ideation-primary: pre-pass lookup → batch mint at settle → audit promotion; two-state readiness (`ready-for-agent`/`ready-for-human`) replaces the autonomy trio |
 | [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 |
 | [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 |
@@ -129,10 +129,11 @@ carries none.
 
 **Grill queue** (decided 2026-07-16): the critical path is
 [spec-and-ticket-layer](reference/spec-and-ticket-layer.md) (✅ grilled 2026-07-17) →
-[pipeline-stages](reference/pipeline-stages.md) (✅ grilled 2026-07-18) — next up:
+[pipeline-stages](reference/pipeline-stages.md) (✅ grilled 2026-07-18) →
-[never-ask-twice](reference/never-ask-twice.md) +
+[never-ask-twice](reference/never-ask-twice.md) (✅ grilled 2026-07-18; formalization +
+label-taxonomy ADRs minted) — next up:
 [self-improvement-loops](reference/self-improvement-loops.md) (can run in
-parallel with pipeline build; NAT's formalization ADR is independent), then
+parallel with pipeline build; owes NAT only the audit cadence number), then
 [horizon](reference/horizon.md). The remaining nodes' open questions are
 implementation-time calls, not grill material.
 

plugins/os-sdlc/reference/never-ask-twice.md

@@ -1,76 +1,119 @@
 # never ask twice
 
-_Status: direction — as of 2026-07-16_
+_Status: settled — grilled 2026-07-18_
 _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
 
 The agency mechanism, and the most important node in this reference set. States the
 operating principle that lets the factory earn autonomy over time instead of asking the
-human the same question on every run. Load this before designing any blocked-stage
+human the same question on every run. Load this before designing any human-input point in
-behavior, any human-input point in the pipeline, or ADR-0037's follow-on formalization ADR.
+the ideation phases (grill / to-spec / to-tickets), or any spec-gap handling in the
+pipeline. Formalized 2026-07-18 in its own cross-plugin ADR (see Sources).
 
-## Design
+## Design (settled 2026-07-18)
 
 - **Operating principle: the factory never asks the human the same question twice.** Trust
   is earned in units, and every unit is made durable and reusable. Goal state: the human is
   only presented options when the factory genuinely needs direction — not because a decision
   that was already made once was forgotten.
+- **Home: the ideation phases, not the implementation pipeline.** Questions to the human
+  belong in grill / to-spec / to-tickets; by the time tickets exist, all decisions are made
+  and implementation is nearly mechanical, with standards and conventions baked into lint
+  rules and agent prompts/reference material
+  ([standards-and-conventions](standards-and-conventions.md)). The pipeline keeps one thin
+  safety valve: a spec gap surfacing mid-implementation is a **defect in the ticket** — the
+  run fails back to the spec layer (where the answer gets minted into the ticket/records),
+  never an inline chat ask. "All decisions made by to-tickets" is the target state the
+  system converges toward, not an assumption it depends on.
 - No new storage system and no literal decision-tree engine. The "tree" is the existing ADR
   corpus plus vault conventions; os-sdlc adds only wiring on top of os-adr and os-vault.
   Three thin pieces:
-  1. **Two-tier lookup at block time.** Before any question reaches the human, the blocked
+  1. **Two-tier lookup as a pre-pass.** When a grill / to-spec / to-tickets session loads
-     stage runs a mandatory, mechanical chain: `/os-adr:find` over the repo's ADRs first,
+     its target, it runs one batched lookup pass — `/os-adr:find` over the repo's ADRs,
-     then `/os-vault:query` over `domain/`/`tool/`/`convention/` facets. Only a genuine miss
+     then `/os-vault:query` over the relevant `domain/`/`tool/`/`convention/` facets — and
-     on both tiers produces a human-facing question.
+     drafts questions *against* that corpus: a question already answered by a record never
-  2. **Scope classification at mint time.** When the human unblocks a stage by answering,
+     gets drafted; the record gets cited instead. Topic-shift rule: if the interview moves
-     the factory asks one follow-up: "does this generalize beyond this repo?" No → record a
+     outside the pre-pass scope, re-run the lookup for the new topic before asking.
-     repo-local ADR only. Yes → a vault convention note becomes the source of truth, and the
+  2. **Mint in batch at settle.** Answers accumulate during the interview in a running
-     repo ADR records the local adoption with a link back to it. The ask is not complete
+     decisions-so-far list (the crash/resume mitigation); at the settle step the skill
-     until the record exists — an answered-but-unrecorded question is the failure mode this
+     proposes a scope classification for the whole batch ("these are repo ADRs, this one
-     whole mechanism exists to prevent.
+     generalizes → vault convention — confirm/amend"), the human confirms once, and it
+     mints everything. **The session is not complete until the mint pass has run** — an
+     answered-but-unrecorded question is the failure mode this whole mechanism exists to
+     prevent.
   3. **Promotion by audit, not memory.** A decision minted local that later blocks a second
-     project is a recurrence — visible across blocked-stage logs, not tracked live. A
+     project is a recurrence — visible in session/spec-gap exhaust, not tracked live.
-     periodic audit (see [self-improvement-loops](self-improvement-loops.md)) sees the
+     Periodic audits (owned by [self-improvement-loops](self-improvement-loops.md)) see the
-     recurrence and promotes the answer to a vault convention.
+     recurrence and promote the answer to a vault convention. Promotion and demotion happen
-- **Decision-category autonomy labels**, generalized from individual tickets to decision
+     only in audits, never mid-run; the cadence is self-improvement-loops' decision.
-  *categories* (e.g. dependency choice, schema-migration approach, UI flow pattern):
+- **ADR↔convention delineation:** conventions are defaults that hold until overridden; ADRs
-  - `afk-ready` + a covering record → proceed and cite the record.
+  are project-local adoptions of, or deviations from, them. Worked example: "always use
-  - `semi` → proceed, but flag the decision in the stage report for human review.
+  Devise for Rails auth" is a vault convention note (`convention/rails`, `tool/devise`,
-  - `hitl`, or no coverage at all → stop and ask.
+  `domain/authentication`), not an ADR anywhere; the client project that can't use Devise
-  Promotion and demotion of categories happens only in periodic audits, never mid-run.
+  records a repo ADR deviating from the convention, linking it. The mint-time scope
-- **Cross-project answer, worked example:** a decision minted while building rails app A
+  question and the audit are the *only* boundary machinery — no dedicated promotion skill,
-  should be available when building rails app B. Repo ADRs are deliberately project-local
+  no new taxonomy (the six flat ADR-011 facets are the domain organization the grill
-  (they record local adoption, not universal truth); the vault is the cross-project layer.
+  pre-pass queries).
-  os-sdlc doesn't change this split — it adds the lookup chain, the mint ritual, and the
+- **Two-state readiness, not three-tier autonomy.** The former `hitl`/`semi`/`afk-ready`
-  audit-driven promotion path on top of it.
+  decision-category labels are retired (superseding ADR in Sources): the `semi`/`hitl`
+  boundary had no operational test, and artifact/PR review already delivers
+  proceed-and-flag for free. In their place:
+  - **Coverage is two-state.** A decision category is either covered (a record exists →
+    proceed and cite it in the artifact, where review catches mistakes) or uncovered
+    (ask). Coverage *is* the record's existence — no label field, no config surface.
+  - **Tickets are two-state**, adopting Matt Pocock's triage vocabulary:
+    `ready-for-agent` ("fully specified — an agent can complete it without asking",
+    falsifiable in production: an agent that asks or bounces proves the label wrong) and
+    `ready-for-human`. A ticket that is neither is under-decomposed — split it into
+    ordered agent/human parts, agent parts first where dependencies allow — never labeled
+    into limbo. This replaces the autonomy trio in os-backlog's label taxonomy (migration
+    of existing tickets tracked as a follow-up issue).
 - **Honest limit:** this mechanism guarantees the *plumbing* — a decision recorded once is
   findable everywhere it applies — not the *judgment* that the agent applies the right
   convention in an ambiguous case. Judgment quality is proven only by accumulated audits.
-  Expect the ask-rate to fall as categories graduate from `hitl`/`semi` to `afk-ready`; a
+  Expect the ask-rate to fall as the convention corpus grows and coverage widens; a
-  category that graduates too early gets demoted, with the ADR trail showing exactly which
+  mis-minted convention gets caught at artifact review or demoted by audit, with the ADR
-  decision went wrong and why.
+  trail showing exactly which decision went wrong and why.
 - **Mobbin** (mobbin.com, a design-pattern reference library) as a future pre-seeded
-  convention library for the UI-flow decision category — would let front-end decisions start
+  convention library for UI-flow decisions — pre-seeding makes a category *covered* from
-  at `semi` instead of `hitl` from day one. This is horizon-scoped (see
+  day one. Horizon-scoped (see [horizon](horizon.md)), but validates that the coverage
-  [horizon](horizon.md)) but validates that the category-autonomy frame generalizes to
+  frame generalizes to externally-sourced conventions, not just self-mined ones.
-  externally-sourced conventions, not just self-mined ones.
+- This mechanism spans os-sdlc, os-adr, os-vault, and os-backlog jointly; formalized in its
-- This mechanism spans os-sdlc, os-adr, and os-vault jointly and gets its own ADR when
+  own ADR (see Sources) rather than owned by any single plugin.
-  formalized — it is not owned by any single plugin.
 
-## Open questions
+## Resolved 2026-07-18 (grill)
 
-- Block-report format: what a blocked stage writes when it stops to ask (must carry enough
+1. **Home** — ideation-primary; pipeline keeps only a fail-back-to-spec-layer valve for
-  context for the two-tier lookup to be re-run later without re-asking).
+   ticket defects; never inline asks mid-implementation.
-- Where decision-category labels live (ADR frontmatter? a small config file? vault note
+2. **Lookup mechanics** — one batched pre-pass at session load + topic-shift re-lookup,
-  frontmatter?) and who assigns the initial label for a brand-new category.
+   not per-question inline lookups.
-- Audit cadence for promotion/demotion (tied to [self-improvement-loops](self-improvement-loops.md)'s
+3. **Delineation** — mint-time scope question + audit promotion are the entire
-  ADR-audit loop, but not yet fixed).
+   ADR↔convention boundary; no dedicated promotion machinery.
+4. **Mint mechanics** — batch at settle with a running decisions list; session incomplete
+   until minted.
+5. **Labels** — three-tier autonomy retired for two-state coverage (records) and two-state
+   readiness (tickets, `ready-for-agent`/`ready-for-human`); under-decomposed tickets get
+   split, not a third label. Existing-ticket migration is a tracked os-backlog follow-up.
+6. **Audit cadence** — contract fixed here (audit-only promotion/demotion, never mid-run);
+   the cadence number is deferred to [self-improvement-loops](self-improvement-loops.md).
+7. **Formalization** — two ADRs minted at settle: the cross-plugin never-ask-twice
+   mechanism, and the superseding label-taxonomy change.
+
+No open questions remain in this doc. The former "block-report format" question dissolved
+with the reframe: a mid-implementation gap is a ticket defect routed to the spec layer, and
+its report format belongs to [spec-and-ticket-layer](spec-and-ticket-layer.md) /
+[pipeline-stages](pipeline-stages.md), not here.
 
 ## Sources
 
 - ADR-0037 (`docs/adr/0037-os-sdlc-lives-inside-cc-os-as-a-new-plugin-not-a-separate-cc-sdlc-marketplace.md`)
-- os-adr `find`/`create` skills; os-vault `query`/`write` skills
+- Never-ask-twice formalization ADR + label-taxonomy superseding ADR (minted 2026-07-18 at
+  this grill's settle; see `docs/adr/README.md` index)
+- Matt Pocock's `/triage` skill (two categories, five states incl. `ready-for-agent` /
+  `ready-for-human`) — vocabulary source for two-state readiness
+- os-adr `find`/`create` skills; os-vault `query`/`write` skills; os-backlog ten-label
+  taxonomy (`plugins/os-backlog/skills/route/SKILL.md`)
 - SecondBrain vault: taxonomy/ladder note (referenced by [horizon](horizon.md))
 - mobbin.com (design-pattern library, horizon reference)
-- 2026-07-16 design session (this doc's origin)
+- 2026-07-16 design session (this doc's origin); 2026-07-18 grill (this settle)