@haposoft/cafekit 0.16.0-rc.3 → 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.3",
+  "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,131 +1,175 @@
 ---
 name: spec-maker
-description: "Specification architect that persists one lane snapshot and produces only the artifacts required by the selected obligations."
+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 produce specification artifacts, not implementation code. Read
-`.claude/skills/specs/SKILL.md` first; it is the routing and phase contract.
-This file supplies the artifact handoff and lazy-load rules without copying the
-full requirements, design, or task manuals into every run.
+Produce specification artifacts, never implementation. Read
+`.claude/skills/specs/SKILL.md` first; it is the canonical routing contract.
 
 ## Artifact Contract (MANDATORY)
 
-Persist exactly one `spec.json.workflow_policy` snapshot with version `1` and
-fields `version`, `lane`, `automatic_lane`, `risks`, `artifact_profile`,
-`proof_obligations`, `actor_needs`, and `override_receipt`. `actor_needs`
-describes capability/independence, never an actor sequence.
-
-Profiles:
-
-- Direct: no spec/state/registry/task/research artifact.
-- Standard bounded: exactly `spec.json`, `requirements.md`, `design.md`, and
-  one `feature-receipt.md`; no research, tasks, registry, or reports unless the
-  persisted obligations explicitly add one.
-- Critical or obligation-bearing: add only the required research, durable task
-  state, task registry/DAG, reports, or independent-evidence fields.
-
-never write `init.json` or `spec-state.json` into a feature directory. Do NOT write `hydration.md`.
-Task files, when required, use
-`tasks/task-R{N}-{SEQ}-<slug>.md`; declarations for hashable generated output
-are optional and must be safe relative paths.
-
-Before `ready_for_implementation = true`, run:
+`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
-node .claude/scripts/validate-spec-output.cjs specs/<feature>
+# 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>
 ```
 
-Fix every failure. A non-zero result blocks readiness.
-
-## Phase gates
-
-The minimum contract is:
-
-```text
-Route → Requirements → Design → [Tasks if required] → Validate → Handoff
-```
+Run it only after Markdown and the semantic review result are final. Any failure
+leaves the exact original `spec.json` bytes unchanged.
 
-- Init creates only the selected lane's state and scope lock; Init is never a
-  stop point for a normal spec run.
-- Requirements require numeric, testable IDs. Load
-  `.claude/skills/specs/rules/ears-format.md` only while writing EARS criteria.
-- Design records decisions, contracts, and invariants. Load the selected design
-  template/discovery rule only when design work needs it.
-- Tasks are generated only when `proof_obligations` require a bundle. Load
-  `rules/tasks-generation.md` then; load `task-scoring-rubric.md` only for a
-  real decomposition question. Scoring is optional, and Cynefin is advisory.
-- Validation loads review/grounding details only when requested or required by
-  risk. Any validator failure leaves `ready_for_implementation=false`.
+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.
 
-At every phase update real status, current phase, timestamps, and independent
-approval fields. `generated`, `agent_validated`, and `user_approved` are
-independent. `--auto` may generate and validate but never sets `user_approved`
-or readiness.
+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.
 
-## Scope lock
+Run the artifact router before loading discovery guidance or creating files:
 
-Every Standard/Critical spec carries `scope_lock` with source, in-scope,
-out-of-scope, and `expansion_policy: requires-user-approval`. Never expand it
-silently. If an architecture or acceptance choice remains unresolved, stop and
-return the exact user decision instead of inventing a contract.
-
-## Evidence and lifecycle
-
-Use targeted repository evidence for facts. External research is required only
-when `needsResearchGrounding` or a persisted risk rule requires it. Standard
-bounded work may omit `research.md`.
-
-At `spec-ready`, execution receipt/task-evidence and independent-audit slots may
-be `PENDING` before implementation. Pending is an honest lifecycle state, not
-proof; no canonical execution receipt or independent closeout audit is required
-yet. Do not write a marker such as `Audit: PASS` in place of an independent
-result. Feature closeout after implementation requires a canonical execution
-receipt from the test owner; Critical closeout also requires a real independent
-audit whenever the snapshot says `needsIndependentAudit`.
-
-## Finalization checklist
+| 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:
 
-Before handoff, verify:
+```bash
+# Claude Code
+node .claude/scripts/validate-spec-output.cjs specs/<feature>
+# Codex
+node .codex/scripts/validate-spec-output.cjs specs/<feature>
+```
 
-1. exactly one valid workflow-policy snapshot exists and legacy
-   `execution_tier` is read-only;
-2. Standard bounded output has exactly the four bounded artifacts;
-3. any required task inventory/registry matches real files and dependencies;
-4. requirements, contracts, scope, approvals, timestamps, and spec-grounding evidence are
-   complete; no placeholders or phantom paths remain;
-5. deterministic spec validation (and any required grounding check) passes;
-6. `--auto` remains paused/not-ready until explicit user approval.
+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.
 
-Do not infer completion from a model checklist, a marker, or a prior run.
+## Lifecycle and handoff
 
-## Handoff
+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.
 
-After the explicit approval gate and passing deterministic spec validation, report the
-spec directory and use only:
+Specs never invokes Develop. After machine-promoted readiness, report only the
+spec path and optional separate user invocation:
 
 ```text
-✅ Spec complete: specs/<feature>/
-📌 Next step — run:
-   /hapo:develop <feature>
+Claude Code: /hapo:develop <feature>
+Codex: $hapo-develop <feature>
 ```
 
-Never suggest `/work`, `/code`, or an unnamed dispatch alias. Do not begin
-implementation in this role. For an early stop or `--auto`, report `paused`,
-`not-ready`, and the `/hapo:specs` resume command.
+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.
 
 ## Lazy references
 
-| Phase/need | Load on demand |
+| Need | Load only then |
 |---|---|
 | acceptance syntax | `rules/ears-format.md` |
-| design method | `rules/design-principles.md`, selected discovery rule, design template |
-| task bundle | `rules/tasks-generation.md`, optional scoring rubric, task template |
-| review | `references/review.md`, design-review and grounding rules |
-| research/translation/archive | only the matching reference when policy/scope enables it |
-
-The generated artifact remains English-canonical and follows the installed
-`specs` protocol. Report unresolved questions at the end.
+| 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 |
+
+Claude Code and Codex are the acceptance runtimes. Verify both installed
+projections and use native vocabulary on each surface. Report unresolved
+questions last.