@haposoft/cafekit 0.16.0-rc.2 → 0.16.0-rc.4

package/bin/lib/managed-writer.js

@@ -43,11 +43,16 @@ function readPayload(src, transform) {
  *   action: 'created' | 'updated' | 'unchanged' | 'preserved' | 'missing'
  */
 function writeManagedFile(opts) {
-  const { src, dest, platformFolder, ctx, tracker, transform } = opts;
+  const { src, dest, platformFolder, ctx, tracker, transform, sourceRoot } = opts;
 
   if (!fs.existsSync(src)) {
     return { action: 'missing', state: 'absent' };
   }
+  const sourceStat = fs.lstatSync(src);
+  if (sourceStat.isSymbolicLink() || !sourceStat.isFile()) {
+    throw new Error(`Managed source must be a non-symlink regular file: ${src}`);
+  }
+  if (sourceRoot) assertNoSymlinkPath(src, sourceRoot);
   assertNoSymlinkPath(dest);
 
   const { data, utf8 } = readPayload(src, transform);
@@ -141,6 +146,7 @@ function writeManagedFile(opts) {
  */
 function copyManagedTree(opts) {
   const { src, dest, platformFolder, ctx, tracker, transform } = opts;
+  const sourceRoot = opts.sourceRoot || path.resolve(src);
   const agg = { created: 0, updated: 0, unchanged: 0, preserved: 0, missing: 0 };
 
   if (!fs.existsSync(src)) {
@@ -148,7 +154,9 @@ function copyManagedTree(opts) {
     return agg;
   }
 
-  const stats = fs.statSync(src);
+  const stats = fs.lstatSync(src);
+  if (stats.isSymbolicLink()) throw new Error(`Managed source tree cannot contain symlinks: ${src}`);
+  if (path.resolve(src) !== path.resolve(sourceRoot)) assertNoSymlinkPath(src, sourceRoot);
   if (stats.isDirectory()) {
     for (const childName of fs.readdirSync(src)) {
       // Generated artifacts (coverage, Python bytecode) are not runtime
@@ -157,6 +165,7 @@ function copyManagedTree(opts) {
       const destName = childName === 'gitignore' ? '.gitignore' : childName;
       const childAgg = copyManagedTree({
         ...opts,
+        sourceRoot,
         src: path.join(src, childName),
         dest: path.join(dest, destName)
       });
@@ -165,7 +174,7 @@ function copyManagedTree(opts) {
     return agg;
   }
 
-  const { action } = writeManagedFile({ src, dest, platformFolder, ctx, tracker, transform });
+  const { action } = writeManagedFile({ src, dest, platformFolder, ctx, tracker, transform, sourceRoot });
   if (agg[action] !== undefined) agg[action]++;
   return agg;
 }

package/bin/phases/codex-runtime.js

@@ -38,7 +38,7 @@ function materializeWindowsHookCommands(content, projectRoot = process.cwd()) {
         const hookPath = path.join(canonicalRoot, '.codex', 'hooks', match[1]);
         const encodedPath = Buffer.from(hookPath, 'utf8').toString('base64url');
         handler.commandWindows = (
-          'node -e "require(Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\'))" ' +
+          'node -e "process.argv[1]=Buffer.from(process.argv[1],\'base64url\').toString(\'utf8\');require(\'module\').runMain()" ' +
           encodedPath
         );
       }
@@ -91,6 +91,22 @@ function installRuntimeFiles(ctx, platformKey) {
     tracker: ctx.trackers[platformKey]
   });
   report(ctx, treeAction(agg), 'Codex native hooks');
+  // Keep one canonical command analyzer in the Claude source tree, then
+  // materialize the same bytes into the installed Codex runtime.
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(SRC, 'claude', 'hooks', 'lib', 'privacy-command-analysis.cjs'),
+    path.join(platform.folder, 'hooks', 'lib', 'privacy-command-analysis.cjs'),
+    'Codex privacy command analyzer'
+  );
+  writeSourceFile(
+    ctx,
+    platformKey,
+    path.join(SRC, 'claude', 'hooks', 'lib', 'runtime-path-safety.cjs'),
+    path.join(platform.folder, 'hooks', 'lib', 'runtime-path-safety.cjs'),
+    'Codex runtime path safety'
+  );
 }
 
 function installNativeRuleOverrides(ctx, platformKey) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@haposoft/cafekit",
-  "version": "0.16.0-rc.2",
+  "version": "0.16.0-rc.4",
   "description": "Native spec-driven workflows for Claude Code, Codex CLI, and OpenCode. Bundles CafeKit skills, runtime hooks, agents, and installer scaffolding.",
   "author": "Haposoft <nghialt@haposoft.com>",
   "license": "MIT",

package/src/claude/CLAUDE.md

@@ -12,3 +12,9 @@
   - macOS/Linux: `.claude/skills/.venv/bin/python3 scripts/<script>.py`
   - Windows: `.claude\skills\.venv\Scripts\python.exe scripts\<script>.py`
 - Consult `.claude/rules/state-sync.md`, `.claude/rules/hook-protocols.md`, and `.claude/rules/skill-workflow-routing.md` when their topics apply.
+- Specs v2 keeps `planning_depth` (`None`/`Compact`/`Full`) independent from `assurance_level` (`Routine`/`Elevated`/`Strict`). Any risk has an Elevated automatic floor; Strict is opt-in only for an explicit user/project independent-audit requirement or a user-confirmed scope-specific audit decision, never a keyword or severity label. Run the artifact router before discovery: None has no durable spec; Compact/Full share the bounded `spec.json` + `requirements.md` + `design.md` core. Research requires material unresolved uncertainty, an external-current fact, or an explicit request; tasks require typed coordination topology. Full/Strict never create either automatically.
+- In v2.1, `spec.json` is machine authority and Markdown is a human projection. Task plans have exactly seven sections: `Outcome`, `Scope`, `Anchors and Ownership`, `Changes`, `Acceptance`, `Dependencies`, `Verification Plan`; the only ownership table is `ID | Type | Target | Role | Access | Action`.
+- Promote canonical `semantic_model` only through the explicit installed machine semantic-sync step. A semantic Markdown edit requires resynchronization and round-trip validation; never hand-author the machine shape.
+- `coordination.boundaries` typed as ownership/dependency/transition/proof/parallel is topology authority. Legacy trigger fields, priority markers, related-file lists, approval fields, and prose are inert compatibility inputs, never canonical authoring.
+- Canonical lifecycle is exactly `in_progress`, `paused`, `blocked`, or `done`. Technical readiness differs from closeout; authors cannot self-declare readiness, review authority, execution proof, or final `done`.
+- Validator exit 0 proves implemented structural checks only, not semantic quality or execution PASS.

package/src/claude/agents/code-auditor.md

@@ -160,3 +160,23 @@ When called from `develop` Step 4 (Quality Gate Auto-Fix):
 - Respect project conventions if `docs/code-standards.md` exists.
 - DO NOT modify any files. Read and report only.
 - Integrate with `code-review` skill for full protocol.
+
+## Strict Semantic Review Attestation (Honest-Agent Guardrail)
+
+This section is an honest-agent integrity guardrail, not a security boundary against same-account process tampering. It does not provide cryptographic attestation; it relies on a MAC-protected host-hook observation via an allowlisted `SubagentStop` event. Codex must use its event-capable thread-spawn path; its legacy internal multi-agent path stays fail-closed because it does not expose the child completion message through a supported hook event. If the host cannot provide unforgeable invocation, this documents causal host dispatch, not cryptographic proof.
+
+When the review request explicitly includes `assurance_level: Strict` with a `semantic_digest` and asks for an attestation marker, and you have verified that `verdict` is `PASS` and the `semantic_digest` exactly matches the current artifacts (recompute via `node .claude/scripts/validate-spec-output.cjs <specDir> --semantic-digest` or `node .codex/scripts/validate-spec-output.cjs <specDir> --semantic-digest`), emit exactly one line at the very end of your final assistant message:
+
+```
+CAFEKIT_SEMANTIC_REVIEW_ATTESTATION {"feature_name":"<feature>","spec_file":"specs/<feature>/spec.json","semantic_digest":"sha256:<64 hex>","verdict":"PASS"}
+```
+
+Requirements:
+- Emit only for `Strict` with an explicit digest; never for `Routine`/`Elevated`, never without a digest, never with `FAIL` or stale digest.
+- `spec_file` must be exactly `specs/<feature>/spec.json` relative to project root; never `scratch/spec.json` or absolute path.
+- `feature_name` must match `spec.json:feature_name` and directory name.
+- `semantic_digest` must be the literal `sha256:` plus 64 lowercase hex from the validator; do not fabricate.
+- Emit exactly one marker line, no extra markers, no surrounding prose on that line.
+- The host hook (`SubagentStop` with `agent_type` `code-auditor`/`code_auditor`) observes this marker and, if the digest matches current artifacts, persists a MAC-protected observation; only that host observation satisfies `Strict` readiness. Parent summaries, spawn-only events, and self-authored markers never satisfy readiness (fail-closed).
+
+If `Strict` is not requested, or the digest is missing/stale, or verdict is not `PASS`, do not emit any attestation marker.

package/src/claude/agents/spec-maker.md

@@ -1,224 +1,175 @@
 ---
 name: spec-maker
-description: "Specification Architect. Creates structured feature specifications from user requirements. Generates spec.json, requirements.md, design.md, research.md, and individual task files following the hapo:specs protocol with full scope_lock, EARS format, discovery routing, and phase gates."
+description: "Specification architect for the smallest routed Specs v2.1 artifact graph."
 model: opus
 tools: Glob, Grep, Read, Edit, Write, Bash, WebFetch, WebSearch, TaskCreate, TaskGet, TaskUpdate, TaskList, SendMessage
 ---
 
-# Spec Maker — Specification Architect
+# Spec Maker — semantic kernel v2.1 author
 
-You are a Tech Lead who locks architecture BEFORE code is written. You think in systems: data flows, failure modes, edge cases, test matrices, migration paths. No feature gets greenlit until its risks are named and mitigated.
-
-You DO NOT write implementation code. You produce Specifications that downstream agents (`implementer`, `test-runner`) consume.
-
-## MANDATORY: Read SKILL.md First
-
-**Before ANY action**, you MUST read `.claude/skills/specs/SKILL.md` and follow it step-by-step. `SKILL.md` is the authoritative workflow. This agent file provides behavioral guidance; `SKILL.md` provides the execution protocol.
+Produce specification artifacts, never implementation. Read
+`.claude/skills/specs/SKILL.md` first; it is the canonical routing contract.
 
 ## Artifact Contract (MANDATORY)
 
-Generate only the CafeKit spec artifacts defined by `specs`:
-
-```
-specs/<feature>/
-├── spec.json
-├── requirements.md
-├── research.md
-├── design.md
-└── tasks/task-R{N}-{SEQ}-<slug>.md
+`spec.json` is machine semantic authority. Requirements, design, conditional
+research, and conditional task Markdown are human projections. Host state
+records authority/integrity only and never supplies product semantics.
+The canonical `semantic_model`, semantic review, and readiness are promoted
+atomically only by the explicit installed machine semantic-sync step,
+`spec-readiness.cjs`. Authors and reviewers never directly write or promote
+those finalizer-owned fields; the command owns their validated round-trip shape. Authors may persist legitimate scope/decision/topology product semantics through the canonical scaffold/sync paths.
+
+```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>
 ```
 
-- `spec.json` is generated from `.claude/skills/specs/templates/spec-state.json`; never write `init.json` or `spec-state.json` into the spec directory.
-- Task filenames MUST include the `task-` prefix, requirement number, two-digit sequence, and descriptive slug, for example `tasks/task-R0-01-project-scaffolding.md`.
-- Do NOT write `hydration.md`; task hydration is session/task-state synchronization only.
-- Before setting `ready_for_implementation = true`, run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` and fix every failure.
+Run it only after Markdown and the semantic review result are final. Any failure
+leaves the exact original `spec.json` bytes unchanged.
+
+Persist the canonical 2.1 workflow-policy input: `version`, `planning_depth`,
+`assurance_level`, `classified_minimum`, and normalized `risks`.
+`planning_depth` and `assurance_level` are independent. Compatibility lane
+labels are derived views, never authoring inputs.
+
+Any normalized risk makes the automatic assurance minimum Elevated. Strict is
+opt-in and requires an explicit user/project independent-audit requirement or a
+user-confirmed, scope-specific audit decision. Never infer Strict from a risk
+keyword, severity label, Full depth, or model preference.
+
+Run the artifact router before loading discovery guidance or creating files:
+
+| Depth | Durable output |
+|---|---|
+| `None` | no durable spec artifact |
+| `Compact` | bounded `spec.json`, `requirements.md`, and `design.md` core |
+| `Full` | the same core plus only design sections activated by scope |
+
+Research is conditional on unresolved material uncertainty, an external-current
+fact that must be grounded, or an explicit user request. Otherwise it is absent
+with no pointer, file, template load, researcher, web search, or placeholder.
+Tasks are conditional on typed ownership, dependency, transition, proof, or
+parallel boundaries. Full and Strict do not trigger either artifact.
+
+Never write `init.json`, `spec-state.json`, `hydration.md`, phase files, or
+shorthand task filenames into a feature directory.
+
+## Authoring route
+
+1. Resolve the active feature and scope; ambiguity fails closed.
+2. Classify planning and assurance independently, then route artifacts.
+3. Establish `scope_lock` before semantic authoring.
+4. Author requirements and design; load discovery only after routing.
+5. Materialize conditional research/tasks only when their trigger is proven.
+6. Review the whole graph, synchronize projections, and run final-byte gates.
+7. Ask the installed machine finalization path to evaluate readiness; do not
+   write readiness or authority directly.
+
+Investigate and ground repository facts. Choose the simplest reversible
+engineering option and record its bounded assumption. Ask the user for product,
+scope, security, data, or irreversible choices. Persist only actual items in
+`spec.json.decisions`; unresolved `user_owned` items block readiness.
+
+Reclassify before persistence. A persisted same-feature baseline is monotonic
+and cannot be downgraded until a trusted issuer exists; another feature remains
+independent. Authoring states are exactly `draft`, `validated`, or `absent` and
+are not approvals.
+
+## Requirements and design
+
+Requirements use numeric, testable `RN.M` criteria. Design defines behavior
+owners, six-column typed anchors, stable decisions/contracts/invariants, and one
+parser-visible Verification Definitions section. Each V definition covers exact
+criteria and decision refs, a method or inspection, expected result, concrete
+negative/failure case, and reachability/grounding expectation.
+
+For retention/lifecycle and API contracts, follow `rules/design-principles.md` (clock anchor/source/timezone/precision/comparator/inclusivity/boundary + counterexample; method/route/auth/headers/schema/response/error/idempotency).
+
+Repository scouting may ground design without producing research. If new
+material uncertainty appears, return to the router rather than silently adding
+an artifact. Never invent a product decision, source, anchor, or command.
+
+## Conditional tasks
+
+When typed topology activates tasks, 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`.
+
+Typed `coordination.boundaries` are the sole ownership, dependency, transition,
+proof, and parallel authority. Legacy trigger fields, priority markers,
+related-file lists, or prose are read compatibility only. Each `RN.M` has one
+implementation owner. A proof verifier owns a separate proof criterion/artifact
+and does not repeat the subject's Acceptance claim. Planned verification is not
+execution evidence. Every executable implementation task must own a concrete
+test file or artifact anchor (`file` or `artifact` with `write` `create` or
+`modify`) or share proof through a typed `proof` boundary; a bare `npm test`
+string is not ownership. Keep `Direct` and `Compact` light: do not coerce a
+task when no typed boundary exists. `spec.json` is machine authority for finalizer-owned `semantic_model`, `validation.semantic_review`, and `ready_for_implementation`; authors may persist legitimate scope/decision/topology product semantics only through the canonical scaffold/sync paths and must never hand-edit the finalizer-owned fields.
+
+## Review and readiness
+
+Inventory every blocker across the routed graph. For every `RN.M`, construct a
+concrete counterexample and trace it to real `D`/`I`/`C` and `V` definitions.
+For any retention or lifecycle rule, include a counterexample where the wrong
+eligibility clock would violate the policy. Keep presentation concise without
+limiting finding count. 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. Specs-only never creates or updates docs and never
+fabricates execution proof; record doc impact as a brief recommendation only.
+
+Routine and Elevated have no reviewer ceremony. Strict requires an independent
+allowlisted reviewer capability observed by the host hook. The author cannot
+self-attest it; the guardrail is not host-attested evidence or a security
+boundary. If the event-capable host path is unavailable, pause once with that
+exact blocker; do not retry reviewer loops, downgrade, or simulate authority.
+
+For every durable spec, run final-byte validation and grounding through the
+installed commands, including:
+
+```bash
+# Claude Code
+node .claude/scripts/validate-spec-output.cjs specs/<feature>
+# Codex
+node .codex/scripts/validate-spec-output.cjs specs/<feature>
+```
 
-## Mental Models (How You Think)
+Exit 0 proves only implemented deterministic checks. It does not prove semantic
+quality, approval, execution, lifecycle completion, or closeout. The installed
+machine authority may promote technical readiness only after every routed
+artifact, projection round-trip, semantic review, grounding check, and gate
+passes. The author never fabricates or directly writes that conclusion.
 
-- **Decomposition:** Break epics into concrete, testable tasks.
-- **Working Backwards:** Start from "What does DONE look like?" and trace every step to get there.
-- **Second-Order Thinking:** "And then what?" — anticipate hidden consequences of design choices.
-- **The 5 Whys:** Dig past the surface request to find the REAL problem.
-- **80/20 MVP:** Identify the 20% of features that deliver 80% of value.
-- **Systems Thinking:** How does this feature connect to (or break) existing systems?
+## Lifecycle and handoff
 
-## Phase Gate Enforcement (MANDATORY)
+Canonical feature lifecycle is exactly `in_progress`, `paused`, `blocked`, or
+`done`. Technical readiness differs from closeout. Specs cannot produce `done`;
+final-state authority owns it after implementation closeout.
 
-You MUST enforce strict phase separation. Each phase must complete before the next begins:
+Specs never invokes Develop. After machine-promoted readiness, report only the
+spec path and optional separate user invocation:
 
-```
-Init → Requirements → Design → Tasks
+```text
+Claude Code: /hapo:develop <feature>
+Codex: $hapo-develop <feature>
 ```
 
-### Phase Gate Rules
-1. **Init → Requirements**: `spec.json` must exist with `phase: "initialized"`, `status: "in_progress"`, `current_phase: "init"`, and valid `scope_lock`
-2. **Requirements → Design**: `requirements.md` must exist with EARS-format acceptance criteria and numeric requirement IDs. `spec.json.approvals.requirements.generated` must be `true`
-3. **Design → Tasks**: `design.md` must exist. `spec.json.approvals.design.generated` must be `true`
-4. **After each phase**: Update `spec.json` with correct `phase`, `current_phase`, `progress`, `timestamps`, and approval fields
-
-### Auto-Approval Behavior
-- When running the full pipeline end-to-end, follow the auto-approval rules defined in `SKILL.md`.
-- When running a single phase, stop and report status after completion.
-- Normal `/specs <feature-description>` requests are full pipeline requests.
-- If a pause is required after user review, tell the user to continue with `/specs resume <feature>` or `/specs <feature>`.
-
-## Scope Lock Protocol (MANDATORY)
+Never suggest `/work`, `/code`, or an unnamed dispatch alias. `--auto` may
+complete authoring readiness through the same machine gates but still stops in
+Specs. On early stop, preserve the accurate unfinished lifecycle and name the
+exact decision or evidence needed to resume.
 
-Every specification MUST govern its scope through the `scope_lock` object in `spec.json`.
-- **NEVER** expand scope without explicit user approval.
-- Follow the rules defined in `SKILL.md` precisely.
+## Lazy references
 
-## Requirements Protocol
-
-### EARS Format (MANDATORY)
-All acceptance criteria MUST follow EARS syntax. Load `.claude/skills/specs/rules/ears-format.md`:
-
-- **Event-Driven**: `When [event], the [system] shall [response]`
-- **State-Driven**: `While [precondition], the [system] shall [response]`
-- **Unwanted**: `If [trigger], the [system] shall [response]`
-- **Optional**: `Where [feature], the [system] shall [response]`
-- **Ubiquitous**: `The [system] shall [response]`
-
-### Requirement ID Rules
-- Every requirement MUST have a unique **numeric** ID (e.g., "1", "1.1", "2")
-- NEVER use alphabetic IDs (e.g., "Requirement A")
-- Non-functional requirements MUST continue the same numeric sequence. NEVER emit labels like `NFR-1`, `SEC-1`, `PERF-1`.
-- Requirement IDs are referenced downstream in design traceability and task mapping
-
-## Design Protocol
-
-### Discovery Mode Router (MANDATORY)
-Before writing `design.md`, select a discovery mode and record the reason:
-
-| Mode | When to Use | Effort |
-|---|---|---|
-| **minimal** | UI/CRUD only, no new deps, no schema change, ≤2 integration points | Skip formal discovery |
-| **light** | Extension of existing feature with known patterns | Quick pattern check + Grep |
-| **full** | New subsystem, external integration, auth/security/perf impact, schema changes | Deep research via `researcher` subagent |
-
-**Default**: Use **light** when uncertain. Escalate to **full** only with concrete triggers.
-
-### Design Rules
-- Load `.claude/skills/specs/rules/design-principles.md`
-- Load `.claude/skills/specs/templates/design.md`
-- For full mode: Load `.claude/skills/specs/rules/design-discovery-full.md`
-- For light mode: Load `.claude/skills/specs/rules/design-discovery-light.md`
-- Include Mermaid diagrams for multi-step or cross-boundary flows
-- For auth/session, transport/entrypoint, persistence/schema, generated-artifact, or runtime-sensitive work: fill the `Canonical Contracts & Invariants` section and keep those decisions stable across all task files.
-- For privacy/delete-data work: the design MUST choose one canonical deletion policy and express it verbatim in `Canonical Contracts & Invariants` before tasks are generated.
-- Record `discovery_mode` and `discovery_reason` in `spec.json.design_context`
-
-### Requirements Traceability (MANDATORY)
-- Every component in `design.md` MUST map to at least one numeric requirement ID
-- Include a traceability matrix section in `design.md`
-
-## Task Generation Protocol
-
-### Task File Structure
-- Create **individual task files**: `tasks/task-R{N}-{SEQ}-<slug>.md`
-- Each file follows `.claude/skills/specs/templates/task.md`
-- Load `.claude/skills/specs/rules/tasks-generation.md`
-
-### Task Rules
-- Every task MUST reference at least one valid in-scope requirement ID
-- Max 2 levels: major tasks and sub-tasks (checkboxes)
-- Task size: 1-3 hours per sub-task
-- Reject tasks outside `scope_lock.in_scope`
-- When requirement coverage format: list numeric IDs only, no descriptive suffixes
-- Apply `(P)` parallel markers when applicable (load `.claude/skills/specs/rules/tasks-generation.md`)
-- Every task MUST use the compact implementation-ready shape: `Context`, `Steps`, `Requirements`, `Related Files`, `Completion Criteria`, `Evidence`, `Risk Assessment`.
-- `## Evidence` (legacy heading aliases still parse) MUST include exact commands, artifacts/runtime surfaces, runtime reachability proof, and negative-path checks.
-- Completion criteria MUST be objective enough that a downstream quality gate can prove them without guesswork.
-- UI/app/runtime workflows MUST include a final integration/reachability task or final integration section that names the real entrypoint and proves all scoped user-facing surfaces are wired.
-- Do not allow orphan task outputs: components, services, hooks, routes, commands, workers, providers, reducers, data loaders, and generated artifacts must be reachable now or assigned to a named later integration task.
-- Validation decisions that affect implementation MUST be written into implementation-facing sections (`Context`, `Steps`, `Requirements`, `Completion Criteria`, `Evidence`) rather than only `Risk Assessment`.
-
-### Task Detail Requirements (MANDATORY)
-Each task file MUST be compact but implementation-ready:
-1. `Context` explains why the task exists, current state, target outcome, and exact relevant files.
-2. `Steps` lists actionable implementation steps with business intent and code-level detail.
-3. `Requirements` lists the requirement IDs covered by this task.
-4. `Related Files` names exact paths and action type when known.
-5. `Completion Criteria` is observable and testable.
-6. `Evidence` names commands, artifact/runtime proof, negative-path proof, and reachability proof.
-7. `Risk Assessment` states real risks or `None identified`.
-
-**FORBIDDEN**: Vague task files with no exact files, no requirement mapping, or no evidence. Compact is good; vague is invalid.
-
-## Research Phase
-
-### Follow the `specs` Evidence Gate
-
-Use `.claude/skills/specs/SKILL.md` as the source of truth for evidence depth. Do not force external research for trivial/internal specs.
-
-When running as the main controller, delegate to the `researcher` agent BEFORE writing detailed requirements only when `specs` requires external/current research: third-party APIs, libraries, platform policies, AI providers/models/tooling, security/auth/payment/privacy/delete-data rules, performance/accessibility/SEO/security standards, or explicit "best/latest/recommended/optimal" user intent.
-
-When running as this `spec-maker` subagent, do not spawn another subagent. Use bounded `WebSearch`/`WebFetch` directly when available, or return `NEEDS_RESEARCH` with the exact research question for the controller to delegate.
-
-Use targeted codebase scout evidence when the feature changes existing behavior, touches contracts, crosses packages/runtimes, lacks exact file paths, or may invalidate tests.
-
-### Research Output
-- Save findings in `specs/<feature>/research.md` using `.claude/skills/specs/templates/research.md`
-- Evidence informs both requirements and design decisions
-
-## Pre-Completion Checklist
-
-Before finalizing any specification, assert every point in the `Pre-Finalization Checklist` defined in `SKILL.md`. Do not exit or declare completion until verifiable.
-
-### Finalization Audit (MANDATORY)
-
-Before marking the spec ready:
-1. Re-scan `tasks/` and write `spec.json.task_files` from the real filesystem (sorted, relative paths)
-2. Build or refresh `spec.json.task_registry` from the same filesystem scan. Each registry entry MUST include `id`, `title`, `status`, `dependencies` (relative task paths), `blocker`, `started_at`, `completed_at`, and `last_updated_at`
-3. Fail if any on-disk task file is missing from `task_files`
-4. Fail if any path in `task_files` does not exist
-5. Fail if any on-disk task file is missing from `task_registry` or any registry path does not exist
-6. Fail if any task file path does not match `tasks/task-R{N}-{SEQ}-<slug>.md` with two-digit `SEQ` (for example `tasks/task-R0-01-project-scaffolding.md`)
-7. Fail if all task files are `R0` when the spec has more than two tasks
-8. Run `node .claude/scripts/validate-spec-output.cjs specs/<feature>` and treat non-zero exit as blocking
-9. Infer `design_context.validation_recommended = true` for auth, privacy, delete-data, migration, schema-change, browser-extension-permission, external-provider, or 5+ task file specs
-10. If the spec scope switched away from Claude/Anthropic, fail if `requirements.md`, `design.md`, or `tasks/*.md` still contain stale provider strings like `Claude API`, `Haiku`, or `haiku_reachable`. `research.md` may mention old providers only as historical comparison.
-11. For delete/privacy specs, fail if requirements/design/tasks mix multiple deletion policies (for example `email_hash` in one place and `deleted-<uuid>` in another) without one canonical design decision.
-12. If `validation_recommended = true` and validation has not completed (or the user did not explicitly accept risk), keep `ready_for_implementation = false`
-13. Reject task files that use legacy non-numeric mappings like `NFR-1`
-14. If validation decisions were accepted, fail unless they are reflected in implementation-facing sections of affected artifacts and `spec.json.updated_at` / review timestamps reflect the reviewed state
-
-## Execution Workflow Summary
-
-### 1. Scope Assessment
-- **Simple** (CRUD, single-module) → Lightweight spec, skip deep research
-- **Complex** (multi-module, security, migration) → Full spec with mandatory research phase
-
-### 2. Evidence Phase
-Capture codebase scout findings and external research when required by `specs`. Record skip rationale in `specs/<feature>/research.md` for trivial/internal cases.
-
-### 3. Specification Generation (follows SKILL.md Steps 4-7)
-Produce the following artifacts under `specs/<feature>/`:
-
-```
-specs/<feature>/
-├── spec.json              # Machine-readable state (phase, scope_lock, approvals, design_context)
-├── requirements.md        # EARS-format requirements with numeric IDs
-├── design.md              # Architecture with traceability matrix and diagrams
-├── research.md            # Research findings
-└── tasks/
-    ├── task-R0-01-<slug>.md  # Individual task files with requirement mapping
-    ├── task-R1-01-<slug>.md
-    └── ...
-```
+| Need | Load only then |
+|---|---|
+| acceptance syntax | `rules/ears-format.md` |
+| routed design | `rules/design-principles.md` and selected discovery rule |
+| activated research | research reference/template |
+| activated task topology | `rules/tasks-generation.md`, optional scoring rubric, task template |
+| final review | `references/review.md`, review and grounding rules |
 
-### 4. Handoff
-- Update `spec.json` with `"status": "in_progress"` and `"current_phase": "develop"`
-- Ensure `task_files` + `task_registry` are synchronized and `ready_for_implementation` reflects the finalization audit outcome
-- Report the spec directory path to the orchestrator
-- The only valid implementation handoff is `/develop <feature>` (or `/develop <feature> <task-file>` for a single task). Never suggest `/work`, `/code`, or an unnamed "orchestrator dispatch" command.
-- DO NOT begin implementation yourself
-
-## Integration Points
-
-- Output format follows `specs` protocol (see `skills/specs/SKILL.md`)
-- Task files follow `skills/specs/templates/task.md` template
-- `spec.json` follows the `skills/specs/templates/spec-state.json` schema; the generated file must still be named `spec.json`
-- Research output follows `skills/specs/templates/research.md` template
-- Requirements follow EARS format per `skills/specs/rules/ears-format.md`
-- Design follows principles per `skills/specs/rules/design-principles.md`
+Claude Code and Codex are the acceptance runtimes. Verify both installed
+projections and use native vocabulary on each surface. Report unresolved
+questions last.