@haposoft/cafekit 0.16.0-rc.3 → 0.16.0-rc.5

package/src/claude/skills/specs/SKILL.md

@@ -1,216 +1,222 @@
 ---
 name: hapo:specs
-description: "Route a request into the smallest evidence-backed CafeKit specification that its lane requires."
+description: "Author the smallest durable, grounded specification that removes product decisions from implementation."
 user-invocable: true
-when_to_use: "Use when a request needs a durable specification or a lane decision before implementation."
+when_to_use: "Use when a change needs durable requirements or design before implementation."
 category: utilities
 keywords: [specs, requirements, design, tasks]
 argument-hint: "[<feature-description>] [--auto] | --status | --validate <feature> | --archive"
 metadata:
   author: haposoft
-  version: "2.0.0"
+  version: "2.1.0"
 ---
-# Specs — routing and handoff contract
+# Specs — semantic kernel v2.1
 
-This file is the small control plane for specification work. It owns routing,
-phase boundaries, stop conditions, lane obligations, and the implementation
-handoff. Load the detailed rules only when the selected phase needs them; do
-not preload every template, rubric, diagram rule, or discovery manual.
+## Canonical authoring contract
 
-## Core contract
+`spec.json` is machine semantic authority. `requirements.md`, `design.md`,
+conditional `research.md`, and conditional task Markdown are human projections.
+Host state records authority/integrity only; it never supplies product semantics.
+Markdown edits that affect semantics must be synchronized back into `spec.json`
+and pass the same round-trip validation before readiness.
+Promote `semantic_model`, semantic review, and readiness together only through
+the explicit installed machine semantic-sync step, `spec-readiness.cjs`. Authors
+and reviewers never directly write or promote those authority fields; any later
+semantic Markdown edit invalidates the bound round-trip result.
 
-The normal route is:
+```bash
+# Claude Code
+node .claude/scripts/spec-readiness.cjs specs/<feature> --review-result <review.json>
+# Codex
+node .codex/scripts/spec-readiness.cjs specs/<feature> --review-result <review.json>
+```
 
-`Route → Requirements → Design → [task bundle when required] → Validate → Handoff`
+`review.json` has exactly `reviewed_criteria` and `counterexamples`. The command
+projects current Markdown, validates structure, grounding, round-trip, and
+Strict authority, then writes atomically; failure preserves exact original bytes.
+
+Persist `planning_depth`, `assurance_level`, `classified_minimum`, normalized
+`risks`, and contract `version`. Planning and assurance are independent:
+
+| Axis | Values | Decides |
+|---|---|---|
+| `planning_depth` | `None`, `Compact`, `Full` | Durable artifact/detail topology. |
+| `assurance_level` | `Routine`, `Elevated`, `Strict` | Review and verification depth. |
+
+`Direct`, `Standard`, and `Critical` are derived compatibility views. Risk may
+raise assurance without creating artifacts; decomposition may raise planning
+depth without inventing risk. Reclassify before persistence. A persisted
+same-feature baseline is monotonic and never contaminates another feature.
+
+Any non-empty normalized risk raises the automatic assurance floor from Routine
+to Elevated. Strict is opt-in: select it only when the user or project policy
+explicitly requires independent audit, or after the user confirms a concrete,
+scope-specific audit need. A keyword, risk severity, Full depth, or model
+preference never selects Strict by itself.
+
+Canonical lifecycle is exactly `in_progress`, `paused`, `blocked`, `done`.
+Legacy aliases are read compatibility only. `ready_for_implementation` means
+technical authoring readiness; it is not lifecycle completion, implementation
+permission, execution proof, or closeout. `done` belongs to final-state
+authority after execution closeout.
+
+## Artifact router
+
+Decide this table before loading discovery rules or creating files:
+
+| Depth | Durable core | Research route | Task route | Design expansion |
+|---|---|---|---|---|
+| `None` | none | absent | absent | none |
+| `Compact` | `spec.json`, `requirements.md`, `design.md` | only on a research trigger | only on a typed topology trigger | bounded core sections |
+| `Full` | `spec.json`, `requirements.md`, `design.md` | only on a research trigger | only on a typed topology trigger | only sections activated by scoped behavior |
+
+Research triggers are: unresolved material uncertainty that can change
+requirements/design; an external-current fact that must be grounded; or an
+explicit user request. Otherwise `authoring.research=absent`, omit the pointer,
+and create no file or placeholder. Repository scouting may inform requirements
+or design without producing `research.md`.
+
+Task triggers are typed ownership, dependency, transition, proof, or parallel
+boundaries that require separate execution packets. Requirement count, size,
+planning depth, assurance level, risk label, architectural layers, and habit do
+not trigger tasks. `coordination.boundaries` is machine authority.
+
+Full selects potential detail, never automatic discovery ceremony. It does not
+automatically search the web, invoke a researcher, dump discovery results, create
+research, create tasks, or retain unused template sections.
+
+## Artifact profiles
+
+- `None`: create no spec directory, registry, research, task, phase, report, or
+  receipt artifact.
+- `Compact` and `Full`: create the routed core and only optional artifacts whose
+  trigger is present.
+- Research, task, and phase metadata must disappear when their trigger is absent.
+- `feature-receipt.md` and task execution receipts belong to execution closeout,
+  not authoring or readiness.
+
+Forbidden authoring artifacts include `init.json`, `spec-state.json`,
+`hydration.md`, `phase-*.md`, and shorthand task filenames.
+
+## Route
+
+1. Resolve the request and active feature; ambiguity fails closed.
+   Ambiguous active candidates fail closed: multiple active specs require an
+   explicit target. Do not rely on first-directory selection or guess from the
+   first active directory.
+2. Classify both axes and run the artifact router before loading discovery.
+3. Establish `scope_lock` with source, in/out scope, and
+   `expansion_policy=requires-user-approval`.
+4. Author requirements, then design, then conditional research/tasks as their
+   actual dependency requires; do not create empty artifacts to reserve them.
+5. Review the final graph, synchronize machine and Markdown projections, then
+   run deterministic gates.
+6. Pause for unresolved product/scope decisions instead of inventing semantics.
+
+Investigate a `repository_fact` and record grounding. Choose the simplest
+`reversible_assumption` and record its bounded reversal boundary. Ask the user
+for a `user_owned` product, scope, security, data, or irreversible decision.
+Persist only actual items in optional `spec.json.decisions`; omit it when none
+exist. Unresolved `user_owned` entries block readiness.
 
-Each phase must finish before the next begins. A simple request may stop before
-spec creation; a bounded Standard request may finish without tasks. Init is
-never a stop point. Never implement code from this skill.
+Supported flags are `--auto`, `--validate`, `--status`, and `--archive`; bare
+`status`, `archive`, and `resume` are compatibility aliases.
 
-### Hard Output Contract
+## Requirements
 
-- Do NOT create `specs/<feature>/init.json`.
-- Do NOT create `specs/<feature>/hydration.md`.
-- Task filenames are never shorthand such as `tasks/task-R0-1.md`.
+Load `rules/ears-format.md` and `templates/requirements.md`.
 
-The persisted `spec.json.workflow_policy` snapshot is the only new lane-policy
-authority. It is written once, validated strictly, and never reclassified by a
-later prose field. The `execution_tier` value (`Light | Standard | Deep`) is a
-legacy read adapter only: `Light → Direct`, `Standard → Standard`, `Deep →
-Critical`. It never creates policy or controls workflow.
+- Use `Requirement N` and literal `RN.M`; task mappings use numeric `N.M`.
+- State scoped outcomes and non-goals before detailed criteria.
+- Every behavior has measurable acceptance and relevant negative/error cases.
+- Add only feature-specific measurable non-functional constraints.
+- User story, rationale, and scenarios are conditional, not ceremony.
 
-## Lane gate
+## Design and discovery
 
-Classify at the runtime boundary before creating spec state or asking for
-approval:
+Load `rules/design-principles.md` plus the routed light/full discovery rule.
+Load research guidance only when the artifact router selected research.
 
-```bash
-node .claude/scripts/workflow-policy.cjs --classify-lane --task-json '<task JSON>' --json
-```
-
-- **Direct**: clear, isolated, reversible, low-risk work. Do not create a spec,
-  state, registry, task bundle, or research artifact. Run targeted verification
-  and retain proportional evidence.
-- **Standard bounded**: create exactly `spec.json`, `requirements.md`, `design.md`, and one `feature-receipt.md`. Do not require
-  `tasks/`, `task_registry`, `reports/`, or `research.md` for a small scope.
-- **Critical**: destructive/irreversible, auth/payment/privacy/data,
-  migration/schema, public contract, cross-runtime, difficult rollback, or
-  other persisted high-risk obligations. Add only the required durable task
-  state, registry/DAG, research, and independent audit surfaces.
+- Compact keeps boundary, six-column typed anchors, decisions/invariants, and
+  verification. Full adds only triggered contract/flow/data/error/security/
+  migration sections.
+- Define each implementation-significant contract once and reference its stable
+  `D`/`I`/`C` ID.
+- For retention/lifecycle and API contracts, follow `rules/design-principles.md` (clock anchor/source/timezone/precision/comparator/inclusivity/boundary + wrong-clock/boundary counterexample; method/route/auth/headers/schema/response/error/idempotency).
+- Keep exactly one parser-visible `## Verification Definitions` section. Each
+  single-line V definition starts with `Criteria ...; Owner ...;` and traces
+  exact decision refs, method,
+  expected result, negative/failure case, and reachability/grounding.
+- Add `Proof criteria ...; Proof owner ...; Evidence anchor ...;` only for a
+  typed proof boundary; ordinary verification stays in the owner boundary.
+- Delete unused optional sections. Ground repository facts to exact anchors;
+  ground external-current decisions to primary sources.
 
-Risk signals may escalate a lane but never downgrade it. A downgrade without a
-trusted runtime-issued receipt is blocked; boolean approval fields are not
-authorization. `--auto` never writes `user_approved: true`.
+## Tasks and lightweight phases
 
-Task scoring is optional advisory input when a required task bundle needs help
-with decomposition. It cannot choose a lane, make a task bundle mandatory, or
-gate readiness. Cynefin is advisory for discovery/spikes only; it never adds
-ceremony by itself.
+Load `rules/tasks-generation.md` and `templates/task.md` only when at least one
+typed topology trigger exists. Size, risk labels, and tradition alone do not
+create tasks. Keep `Direct`/`Compact` light: do not coerce a task when no typed
+boundary exists, and never invent a task to justify structure.
 
-## Dispatch and flags
+Each task has exactly seven H2 sections: Outcome, Scope, Anchors and Ownership, Changes, Acceptance, Dependencies, and Verification Plan. The only ownership table is `ID | Type | Target | Role | Access | Action`. Planned verification is not execution evidence. Every executable task must own a concrete test file/artifact anchor (write create/modify) or share proof via a typed proof boundary; bare npm test is not ownership.
 
-Supported flags are `--auto`, `--validate`, `--status`, and `--archive`; bare
-`status`, `archive`, and `resume` remain compatibility aliases.
-
-1. `--status` reports state and stops.
-2. `--validate <feature>` jumps to validation and stops on any validator error.
-3. `--archive` runs archival rules and stops.
-4. `--auto` generates lane-required artifacts, validates them, then pauses for
-   explicit user approval; it is always `paused` and `not-ready` at that point.
-5. A description enters the lane-appropriate route. If no description exists,
-   ask only the minimum user-owned question needed to continue.
-
-Before selecting a new Standard/Critical spec, inspect only the relevant active
-state and branch match. Multiple active candidates are an ambiguity stop, not a
-reason to pick the first directory. Direct work does not perform registry
-discovery as ceremony.
-
-## Phase contract
-
-### Route and scope
-
-Use repository evidence for facts. Ask the user only for scope, architecture,
-acceptance, or risk decisions that evidence cannot settle. If the idea is
-unclear or competing designs remain, stop and route to `hapo:brainstorm`.
-Load `references/ask-user-question-gates.md` only when a user-owned decision is
-actually needed. Multimodal/document references load their domain reference
-only when the request contains that input.
-
-### Requirements
-
-Create numeric, testable requirements only for Standard/Critical work. Load
-`rules/ears-format.md` when writing EARS acceptance criteria; it is not part of
-the routing context. Run targeted codebase discovery when behavior, contracts,
-paths, tests, package boundaries, or runtime surfaces are uncertain.
-
-External research is required only when `needsResearchGrounding` or an
-applicable persisted risk obligation says so. Otherwise record the bounded skip
-implicitly through the selected artifact profile and do not create `research.md`.
-
-### Design
-
-Write `design.md` only after requirements are sufficient. Load the design
-template/principles and `rules/phase-decision-matrix.md`. For discovery, load
-`rules/design-discovery-light.md` for bounded work or
-`rules/design-discovery-full.md` for complex, security-sensitive, or externally
-uncertain work; load only the selected mode.
-Use diagrams only for multi-step or cross-boundary
-flows. Auth, transport, persistence, generated artifacts, runtime boundaries,
-and deletion policy require canonical contracts and invariants.
-
-### Task bundle (conditional)
-
-Create tasks only when the persisted lane obligations require durable task
-execution, traceability, or a separate task proof path. When tasks are needed,
-load `rules/tasks-generation.md`. Load `rules/task-scoring-rubric.md` only if
-scoring helps resolve a real split/merge or dependency question. The task
-template and filename/registry rules are lazy inputs, not core ceremony.
-
-Every generated task still needs exact scope, requirement mapping, completion
-criteria, executable evidence, and runtime reachability where applicable.
-Do not add an R0 task, integration task, spike, `(P)` marker, or DAG edge unless
-there is a real dependency or proof boundary. Cynefin may explain a spike
-recommendation but does not mandate one.
-
-### Validation and finalization
-
-Load `references/review.md` and detailed design/task rules only for an explicit
-validation request or when the persisted policy marks validation required.
-Always run the deterministic validator before readiness:
+Typed `coordination.boundaries` entries (`ownership`, `dependency`,
+`transition`, `proof`, `parallel`) are the sole topology authority. Legacy
+priority markers, trigger fields, related-file lists, and prose labels are inert
+read compatibility, never canonical authoring.
 
-```bash
-node .claude/scripts/validate-spec-output.cjs specs/<feature>
-```
+Each `RN.M` has exactly one implementation owner. A proof subject implements
+its criterion; its verifier owns a separate proof criterion/artifact, references
+the same V definition, and never duplicates the subject acceptance claim.
 
-**MUST run deterministic validator.** A non-zero result overrides any LLM checklist result;
-output MUST NOT suggest `/hapo:develop` and must keep
-`ready_for_implementation = false`. For a task-bearing policy, also rebuild the
-real task inventory/registry and run grounding when that validator requires it.
+Phases are optional task-ID groups only for a complex Full task graph. They do
+not create files, repeat prose, or replace typed edges.
 
-## Stop conditions
+## Review and readiness
 
-Stop and report `BLOCKED` or `FAIL` when any of these holds:
+Load `references/review.md`. Review the whole graph and inventory every blocker; presentation may be concise, but finding count is never capped. Each `RN.M` receives a concrete counterexample mapped to real `D`/`I`/`C` and `V` refs. For any retention/lifecycle rule, include a counterexample where the wrong clock (for example creation time instead of terminal/state-transition) would violate the policy.
 
-- lane classification or a required trusted downgrade receipt is unavailable;
-- scope/architecture/acceptance is unresolved and needs the user;
-- an active-spec choice is ambiguous;
-- a required artifact, approval, task mapping, contract, or evidence is missing;
-- a validator, grounding check, or required research obligation fails;
-- a path, dependency, or runtime entrypoint cannot be grounded;
-- execution is blocked by permissions or environment.
+Routine and Elevated have no reviewer ceremony. Strict requires an independent, allowlisted reviewer capability observed by the host hook. The author cannot self-attest Strict. If that host event is unavailable, pause once with the exact capability blocker; do not retry reviewer loops, self-attest, downgrade, or simulate the event. This is an honest-agent guardrail, not host-attested evidence or a security boundary. Two-review target is advisory: after two failed semantic rounds, pause for unresolved product/security/architecture uncertainty or repeated non-convergence; one bounded mechanical correction without weakening gates is allowed; budgets never override correctness.
 
-Never turn a placeholder, empty result, or model claim into independent evidence;
-an `Audit: PASS` marker is not evidence. State the exact missing proof and leave
-the lifecycle unfinished.
+For Strict, the reviewer binds its host-observed event to the read-only candidate
+digest from `node .claude/scripts/validate-spec-output.cjs specs/<feature> --semantic-digest` (Claude Code) or `node .codex/scripts/validate-spec-output.cjs specs/<feature> --semantic-digest` (Codex);
+finalization then verifies that current observation.
 
-## Lifecycle and handoff
+Run final-byte validation and grounding for every durable spec:
 
-`spec-ready` is pre-implementation. Set `ready_for_implementation = true` only
-after lane artifacts, explicit user approval, deterministic spec validation, and
-grounded requirement/task mappings and contracts are complete. Execution-evidence
-and independent-audit slots remain honestly `PENDING` when applicable; neither a
-canonical execution receipt nor an independent closeout audit is required yet.
+```bash
+# Claude Code
+node .claude/scripts/validate-spec-output.cjs specs/<feature>
+# Codex
+node .codex/scripts/validate-spec-output.cjs specs/<feature>
+```
 
-After implementation, feature/task closeout is a separate gate: the test owner
-must provide one canonical execution receipt and every required independent audit.
-Critical work requires a real independent audit when `needsIndependentAudit` is
-persisted. Review consumes proof and never creates or claims it; `Audit: PASS` is
-not evidence.
+Exit 0 proves only implemented structural/grounding checks. It does not prove
+semantic quality, product correctness, execution PASS, or closeout.
 
-The shared verdict adapter keeps the workflow surface to
-`PASS | PASS_WITH_WARNINGS | FAIL | BLOCKED`; adapters must not invent a second
-completion enum. Warnings never erase missing proof; closeout remains unfinished
-until its post-implementation receipt and applicable audit obligations are met.
+The installed atomic finalizer may set `ready_for_implementation = true`
+only after routed artifacts match policy, all projections round-trip, the full
+blocker inventory is resolved, every required authoring state is `validated`,
+semantic review coverage is exact, and every deterministic gate passes. The
+author must not write this authority conclusion directly. This flag is technical
+artifact readiness only.
+Specs never invokes or auto-chains into Develop; only a fresh explicit user
+invocation of Develop starts implementation. Specs-only never creates or
+updates docs; record doc impact as a brief recommendation and leave creation or
+update to the docs workflow. Never fabricate execution proof. On failure, keep lifecycle state unfinished and report the exact blocker.
 
-On successful completion, return paths and evidence, then:
+## Platform acceptance and handoff
 
-**Command integrity:** The implementation handoff command is always
-`/hapo:develop <feature>`. Never suggest `/work`, `/code`, or another alias.
+Semantic acceptance covers Claude Code and Codex. Validate both installed
+instruction projections and use native vocabulary for each runtime.
 
-```text
-✅ Spec complete: specs/<feature>/
-📌 Next step — run:
-   /hapo:develop <feature>
+After readiness, report the optional handoff without invoking it:
 
-💡 Tip: Run /clear or start a new chat session before implementing to reduce planning context carryover.
-```
+- Claude Code: `/hapo:develop <feature>`
+- Codex: `$hapo-develop <feature>`
 
-For `--auto` or an early phase stop, use a paused block instead; keep
-`ready_for_implementation=false` and tell the user to resume with
-`/hapo:specs`.
-
-## Lazy references
-
-| Need | Load only then |
-|---|---|
-| user-owned questions | `references/ask-user-question-gates.md` |
-| EARS syntax | `rules/ears-format.md` |
-| design choices | `rules/design-principles.md`, phase matrix, selected discovery rule |
-| task decomposition | `rules/tasks-generation.md`, optional scoring rubric, task template |
-| validation | `references/review.md`, design review rules, validators |
-| archive/translation/research | the matching reference only when enabled by scope/policy |
-
-`spec.json` remains the source of truth for status, timestamps, approvals,
-`scope_lock`, and the single `workflow_policy` snapshot. Do not emit
-`init.json`, `spec-state.json`, `hydration.md`, shorthand task filenames, or
-unregistered artifacts.
+For an early stop, keep readiness false and explain how to resume. `--auto` may
+set technical readiness after every gate passes, but must stop in Specs. Never
+claim proof, authority, approval, readiness, or closeout from placeholders,
+self-authored receipts, chat state, or stale validation.

package/src/claude/skills/specs/references/ask-user-question-gates.md

@@ -1,6 +1,7 @@
 # AskUserQuestion Gate Matrix
 
-Use this matrix to decide when `hapo:specs` must pause for user input. Ask only when the answer changes scope, architecture, requirements, task shape, validation disposition, or implementation safety.
+Use this matrix to classify authority before pausing for user input. A workflow
+event, uncertainty, or architecture choice does not by itself justify a question.
 
 ## Source Priority
 
@@ -12,25 +13,30 @@ Resolve uncertainty in this order:
 4. Reasonable default from CafeKit rules.
 5. `AskUserQuestion` only when the remaining decision is user-owned.
 
-Do not ask about facts that codebase or official docs can answer.
+Classify first:
+
+- `repository_fact`: investigate and ground it from repository or required
+  current evidence. Do not ask the user to supply a discoverable fact.
+- `reversible_assumption`: choose the simplest engineering option and record its
+  bounded reversal boundary. Do not ask unless the user explicitly requested
+  control of that choice.
+- `user_owned`: HOLD and ASK for a product, scope, security, data, or
+  irreversible decision. Never infer or self-approve it.
+
+Store only actual items in optional `spec.json.decisions`; omit it when absent.
+Every unresolved `user_owned` entry blocks readiness; facts and reversible
+assumptions do not become user questions merely because they are unresolved.
 
 ## Gate Matrix
 
-| Gate | Trigger | Ask? | Question shape | Record in |
-|---|---|---:|---|---|
-| Operation | `/hapo:specs` called without args | Yes | Choose create/status/resume/validate/archive | none |
-| Active spec | In-progress or branch-matched spec exists | Yes | Continue existing vs create new | `spec.json` if changed |
-| Pre-spec clarity | Description lacks concrete output, actor, or acceptance signal | Yes | 1-2 clarifying questions | `spec.json.scope_lock` |
-| Brainstorm routing | 2+ plausible architectures and no approved direction | Yes | Route to brainstorm vs continue minimal spec | final response / `research.md` |
-| Scope inquiry | Non-trivial task after 5D assessment | Yes | Expand / Hold / Reduce | `spec.json.scope_lock` |
-| Evidence gap | Required evidence is unavailable after targeted research | Yes | Continue with explicit risk / run more scout / narrow scope | `research.md` |
-| Architecture tie | Two approaches are materially similar after evidence | Yes | Pick approach with recommended option first | `design.md` |
-| Contract change | Auth, persistence, provider, API, CLI, schema, permissions, or runtime contract changes | Yes if user intent not explicit | Confirm contract and rollback expectations | `design.md` canonical contracts |
-| Scope expansion | A task candidate adds work not in `scope_lock` | Yes | Approve expansion / defer / reject | `spec.json.scope_lock` + affected docs |
-| High-risk spike | Risk = Complex and spike may change deliverables | Yes if cost/scope impact > 4h | Spike now / reduce / defer | `research.md` + task file |
-| Task conflict | Parallel candidate shares files/contracts with another task | No by default | Resolve sequentially unless business deadline requires parallelization | task dependencies |
-| Validation findings | Red-team/validate findings modify approved scope/design/tasks | Yes | Apply accepted / review each / reject all | `reports/red-team-report.md` or validation log |
-| Final contradiction | Whole-spec sweep finds unresolved contradiction | Yes | Choose authoritative source/decision | affected docs + `spec.json` |
+| Class | Example trigger | Action | Record in |
+|---|---|---|---|
+| Repository fact | Existing behavior, path, dependency, API shape, or current constraint | Investigate and ground; if evidence remains unavailable, report the exact grounding blocker without asking the user to guess | design/research anchor |
+| Reversible assumption | Two technically valid internal approaches with bounded rollback | Select the simplest compatible option and record the reversal trigger/boundary | `spec.json.decisions` when material, otherwise design |
+| User-owned decision | Product behavior, scope expansion/reduction, security posture, data handling, or irreversible migration | HOLD and ASK; keep the exact decision unresolved until the user answers | `spec.json.decisions` and affected artifact |
+| Active-target ambiguity | Multiple plausible feature/spec targets | HOLD and ASK because target selection changes scope | `scope_lock` |
+| Validation finding | A factual defect or reversible repair | Ground and repair without approval; ASK only if resolution changes a user-owned decision | affected canonical artifact |
+| Task conflict | Shared files/contracts between parallel candidates | Serialize or merge using the simplest reversible topology | task boundaries |
 
 ## Question Format
 
@@ -50,6 +56,8 @@ Do not ask when:
 - The choice is pure implementation detail with no scope/user impact.
 - The task can safely use an existing codebase convention.
 - The question exists only to avoid making a normal engineering judgment.
+- Evidence is missing for a `repository_fact`; report the grounding blocker
+  instead of asking the user to guess.
 
 ## Recording Rules
 
@@ -58,4 +66,5 @@ After a user answer:
 - Update the artifact that drives implementation, not only a report.
 - Keep exact selected option and custom free text when provided.
 - Add unresolved questions at the end of the affected document.
-- Do not mark `ready_for_implementation = true` while a blocking question remains unresolved.
+- HOLD while any `user_owned` decision is unresolved. Do not mark
+  `ready_for_implementation = true` until the user resolves it.

package/src/claude/skills/specs/references/cross-spec-dependency.md

@@ -50,10 +50,14 @@ When a relationship is detected, update `spec.json` of **BOTH** specs:
 
 ### Step 5: Handle Ambiguity
 
-If the relationship is unclear, ask user via `AskUserQuestion`:
-- **Title:** "Cross-Spec Dependencies"
-- **Question:** "Spec `A` and spec `B` appear related. What's the relationship?"
-- **Options:** "A blocks B" | "B blocks A" | "Mutual dependency" | "Not related"
+Treat dependency direction as a `repository_fact`: inspect owned outputs,
+consumers, typed boundaries, and current lifecycle, then ground the edge. Do not
+ask the user to guess a factual graph relationship. If no direction can be
+grounded, leave the edge absent and report the exact grounding blocker.
+
+If choosing which deliverable proceeds first changes user-owned scope, release
+ordering, data handling, or an irreversible commitment, HOLD and ASK for that
+decision; unresolved `user_owned` ordering blocks readiness.
 
 ## Blocked State
 

package/src/claude/skills/specs/references/research-strategy.md

@@ -86,7 +86,10 @@ Before detailing requirements, list unanswered questions:
   - codebase fit
   - external/current constraints
   - downstream task and test implications
-- If evidence leaves multiple viable choices with no obvious winner, route to `/hapo:brainstorm` or ask the user for a decision.
+- If evidence leaves multiple viable choices, classify authority: choose the
+  simplest reversible engineering option and record its bounded reversal;
+  HOLD/ASK only for a user-owned product, scope, security, data, or irreversible
+  decision. Missing repository facts remain grounding blockers, not questions.
 
 ### 7. Record Findings
 - Write to `research.md` using template `templates/research.md`