@paths.design/caws-cli 10.2.0 → 11.1.0

package/dist/shell/binding/resolve-binding.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-binding.js","sourceRoot":"","sources":["../../../src/shell/binding/resolve-binding.ts"],"names":[],"mappings":"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"}

package/dist/shell/binding/types.d.ts

@@ -0,0 +1,42 @@
+import type { BindingState, Spec, WorktreeRegistry } from '@paths.design/caws-kernel';
+export interface ResolveBindingInput {
+    /** Repo root (from store/repo-root.ts, --git-common-dir based). */
+    readonly repoRoot: string;
+    /** Current working directory the command was invoked from. */
+    readonly cwd: string;
+    /** Loaded `.caws/worktrees.json`. */
+    readonly registry: WorktreeRegistry;
+    /**
+     * Loaded valid specs. The resolver looks up the spec referenced by the
+     * registry entry's `specId`. If the spec is missing, the binding is
+     * reported as `one_sided`.
+     */
+    readonly specs: readonly Spec[];
+    /**
+     * Optional pluggable git-worktree lookup, for tests. Receives `repoRoot`
+     * and returns a list of `{ name?, path }` entries OR `null` when git
+     * cannot be invoked. Production injects a real git runner.
+     */
+    readonly gitWorktreeList?: (repoRoot: string) => readonly GitWorktreeEntry[];
+}
+export interface GitWorktreeEntry {
+    /** Absolute path of the worktree on disk. */
+    readonly path: string;
+    /** Branch name (may be `(detached)` or `refs/heads/<x>`). */
+    readonly branch?: string;
+}
+export interface ResolvedBinding {
+    /** The kernel's `BindingState`. */
+    readonly binding: BindingState;
+    /**
+     * The resolved worktree name, if any. `undefined` when cwd is in the main
+     * checkout (no worktree).
+     */
+    readonly worktreeName?: string;
+    /**
+     * Where the worktree-name resolution came from. Helps explain `bound`
+     * vs `one_sided` decisions to the user.
+     */
+    readonly source: 'registry_path_match' | 'git_porcelain_match' | 'none';
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/shell/binding/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/shell/binding/types.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,YAAY,EACZ,IAAI,EACJ,gBAAgB,EACjB,MAAM,2BAA2B,CAAC;AAEnC,MAAM,WAAW,mBAAmB;IAClC,mEAAmE;IACnE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,8DAA8D;IAC9D,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,qCAAqC;IACrC,QAAQ,CAAC,QAAQ,EAAE,gBAAgB,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,IAAI,EAAE,CAAC;IAChC;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,SAAS,gBAAgB,EAAE,CAAC;CAC9E;AAED,MAAM,WAAW,gBAAgB;IAC/B,6CAA6C;IAC7C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,6DAA6D;IAC7D,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,eAAe;IAC9B,mCAAmC;IACnC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,qBAAqB,GAAG,qBAAqB,GAAG,MAAM,CAAC;CACzE"}

package/dist/shell/binding/types.js

@@ -0,0 +1,21 @@
+"use strict";
+// Types for cwd → worktree binding resolution.
+//
+// The shell turns a `(repoRoot, cwd, worktreesRegistry, specs)` tuple into
+// one of three terminal states:
+//
+//   - `bound`:      cwd is inside a worktree that is bidirectionally bound
+//                   to a spec (registry.specId === spec.worktree === name).
+//   - `one_sided`:  cwd is inside a worktree whose binding is partial. The
+//                   shell reports this verbatim from the kernel; it is NOT
+//                   authority.
+//   - `unbound`:    cwd is not inside a CAWS-tracked worktree (or is inside
+//                   the main checkout). Hooks treat this as no-authority
+//                   for write-class operations.
+//
+// The shell never derives worktree name from `basename(cwd)`. Authority
+// flows from the registry's recorded `path` field (or a git-worktree
+// porcelain lookup as a deterministic fallback), never from the
+// filesystem layout alone.
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/shell/binding/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/shell/binding/types.ts"],"names":[],"mappings":";AAAA,+CAA+C;AAC/C,EAAE;AACF,2EAA2E;AAC3E,gCAAgC;AAChC,EAAE;AACF,2EAA2E;AAC3E,4EAA4E;AAC5E,2EAA2E;AAC3E,2EAA2E;AAC3E,+BAA+B;AAC/B,4EAA4E;AAC5E,yEAAyE;AACzE,gDAAgD;AAChD,EAAE;AACF,wEAAwE;AACxE,qEAAqE;AACrE,gEAAgE;AAChE,2BAA2B"}

package/dist/shell/commands/claim.d.ts

@@ -0,0 +1,14 @@
+export interface ClaimCommandOptions {
+    readonly takeover?: boolean;
+    readonly cwd?: string;
+    readonly now?: () => Date;
+    readonly env?: NodeJS.ProcessEnv;
+    readonly out?: (line: string) => void;
+    readonly err?: (line: string) => void;
+    /** Heartbeat-stale TTL in ms; display only. Default 24h. */
+    readonly staleTtlMs?: number;
+    /** Show optional `data` block on rendered diagnostics. */
+    readonly showData?: boolean;
+}
+export declare function runClaimCommand(opts?: ClaimCommandOptions): number;
+//# sourceMappingURL=claim.d.ts.map

package/dist/shell/commands/claim.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.d.ts","sourceRoot":"","sources":["../../../src/shell/commands/claim.ts"],"names":[],"mappings":"AAwDA,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,4DAA4D;IAC5D,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,0DAA0D;IAC1D,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,eAAe,CAAC,IAAI,GAAE,mBAAwB,GAAG,MAAM,CA0KtE"}

package/dist/shell/commands/claim.js

@@ -0,0 +1,197 @@
+"use strict";
+// `caws claim [--takeover]` — surface and (optionally) acquire ownership
+// of the current worktree.
+//
+// Pipeline:
+//   1. resolveRepoRoot(cwd)
+//   2. composeStoreSnapshot (worktrees + agents + specs)
+//   3. resolveSession({ allowMint: true })        — write op, mints if needed
+//   4. resolveBinding(cwd, registry, specs)        — identify the worktree
+//   5. kernel.assertOwnership(registry, name, session, { takeover }, now)
+//      → Ok(null)             — same-session, no patch
+//      → Ok(takeover_claim)   — foreign + --takeover; prior_owners audit
+//      → Err                  — foreign without --takeover, OR unowned
+//                              (unowned is a soft block; caller must use
+//                              `caws worktree create`/`bind` to mint)
+//   6. If a patch was returned, applyRegistryPatch (atomic write to
+//      worktrees.json). prior_owners is append-only.
+//   7. ALWAYS refresh agents.json freshness for the current session
+//      via kernel.refreshAgentClaim → applyRegistryPatch.
+//   8. Render the Claim panel.
+//
+// Exit codes:
+//   0 = ownership is established for the current session (same-session
+//       Ok or successful takeover)
+//   1 = foreign owner without --takeover, or unowned worktree, or kernel
+//       refused for any reason
+//   2 = repo-root / session / store composition failure, or cwd is not
+//       inside a tracked worktree
+//
+// Authority discipline (load-bearing):
+//   - worktrees.json[name].owner is the SOLE ownership authority.
+//   - agents.json last-active is freshness/display only.
+//   - Stale heartbeat is NOT abandonment.
+//   - prior_owners is unbounded, append-only on takeover.
+//
+// Event emission is OUT OF SCOPE for 6a. The `claim_taken_over` event
+// type exists in the kernel schema, but emitting it requires deciding
+// the exact payload shape, and that decision belongs with the broader
+// claim/worktree event work in a later slice. Same-session refresh
+// emits nothing.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runClaimCommand = runClaimCommand;
+const caws_kernel_1 = require("@paths.design/caws-kernel");
+const store_1 = require("../../store");
+const resolve_binding_1 = require("../binding/resolve-binding");
+const claim_1 = require("../render/claim");
+const diagnostic_1 = require("../render/diagnostic");
+const resolve_session_1 = require("../session/resolve-session");
+function runClaimCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const nowFn = opts.now ?? (() => new Date());
+    const env = opts.env ?? process.env;
+    const out = opts.out ?? ((s) => process.stdout.write(s + '\n'));
+    const err = opts.err ?? ((s) => process.stderr.write(s + '\n'));
+    const showData = opts.showData === true;
+    const wantsTakeover = opts.takeover === true;
+    // 1. Repo root.
+    const repoRootResult = (0, store_1.resolveRepoRoot)(cwd);
+    if (!repoRootResult.ok) {
+        err('caws claim: failed to resolve repo root.');
+        err((0, diagnostic_1.renderDiagnostics)(repoRootResult.errors, { showData }));
+        return 2;
+    }
+    const { repoRoot, cawsDir } = repoRootResult.value;
+    // 2. Snapshot (we want both worktrees AND agents).
+    let snapshot;
+    try {
+        snapshot = (0, store_1.composeStoreSnapshot)({ repoRoot, cawsDir });
+    }
+    catch (e) {
+        err(`caws claim: store composition failed: ${e.message}`);
+        return 2;
+    }
+    // 3. Session (write op → mint if missing).
+    const sessionResult = (0, resolve_session_1.resolveSession)({
+        cawsDir,
+        worktreeRoot: cwd,
+        env,
+        now: nowFn,
+        allowMint: true,
+    });
+    if (!sessionResult.ok) {
+        err('caws claim: failed to resolve session identity.');
+        err((0, diagnostic_1.renderDiagnostics)(sessionResult.errors, { showData }));
+        return 2;
+    }
+    const session = sessionResult.value.identity;
+    // 4. Binding from cwd.
+    const bound = (0, resolve_binding_1.resolveBinding)({
+        repoRoot,
+        cwd,
+        registry: snapshot.worktrees,
+        specs: snapshot.specs,
+    });
+    if (bound.worktreeName === undefined) {
+        err('caws claim: cwd is not inside a CAWS-tracked worktree. ' +
+            'v11.0.0 does not ship worktree lifecycle commands; create the ' +
+            'worktree externally (git worktree add) and register it via ' +
+            'a future `caws worktree` command (planned for v11.1). To use ' +
+            'lifecycle commands today, pin to caws-cli@^10.2.x.');
+        return 2;
+    }
+    const worktreeName = bound.worktreeName;
+    const record = snapshot.worktrees[worktreeName];
+    if (record === undefined) {
+        // This should not happen if resolveBinding said we are in a tracked
+        // worktree — but be defensive: if the registry lost the entry
+        // between the bound resolution and now, treat as a composition error.
+        err(`caws claim: worktree '${worktreeName}' not in worktrees.json (registry race).`);
+        return 2;
+    }
+    // 5. Kernel ownership decision.
+    const now = nowFn();
+    const ownershipResult = (0, caws_kernel_1.assertOwnership)(snapshot.worktrees, worktreeName, session, { takeover: wantsTakeover }, now);
+    // 6. Apply takeover patch if the kernel emitted one. assertOwnership
+    // never silently mints unowned-→-owned; if the kernel refused, we
+    // surface that as exit 1.
+    if (!ownershipResult.ok) {
+        err('caws claim: ownership refused.');
+        err((0, diagnostic_1.renderDiagnostics)(ownershipResult.errors, { showData }));
+        // Show the current claim panel so the caller can see who holds it.
+        const ownerLine = (0, claim_1.renderClaimPanel)({
+            worktreeName,
+            worktreeRecord: record,
+            ...(record.owner !== undefined && snapshot.agents[record.owner.session_id] !== undefined
+                ? { agentRecord: snapshot.agents[record.owner.session_id] }
+                : {}),
+            currentSession: session,
+            now,
+            ...(opts.staleTtlMs !== undefined ? { staleTtlMs: opts.staleTtlMs } : {}),
+        });
+        err('');
+        err(ownerLine);
+        return 1;
+    }
+    const patch = ownershipResult.value;
+    if (patch !== null) {
+        // Patch must be a takeover_claim (the kernel only emits null or a
+        // takeover_claim from assertOwnership). Apply it.
+        const applyResult = (0, store_1.applyRegistryPatch)(cawsDir, patch);
+        if (!applyResult.ok) {
+            err('caws claim: failed to apply takeover patch.');
+            err((0, diagnostic_1.renderDiagnostics)(applyResult.errors, { showData }));
+            return 2;
+        }
+    }
+    // 7. Refresh agents.json — even when ownership was already ours.
+    //    Visible references to lifecycle verbs refresh agents.json so
+    //    freshness display stays current independent of IDE hooks.
+    //    refreshAgentClaim only fails on a malformed session shape; we
+    //    just validated this session via resolveSession, so Err here
+    //    would be a real bug. Treat it as exit 2.
+    const refreshResult = (0, caws_kernel_1.refreshAgentClaim)(snapshot.agents, session, now, {
+        bound_worktree: worktreeName,
+        ...(record.specId !== undefined ? { bound_spec_id: record.specId } : {}),
+    });
+    if (!refreshResult.ok) {
+        err('caws claim: internal — refreshAgentClaim returned Err with a validated session.');
+        err((0, diagnostic_1.renderDiagnostics)(refreshResult.errors, { showData }));
+        return 2;
+    }
+    const refreshApply = (0, store_1.applyRegistryPatch)(cawsDir, refreshResult.value);
+    if (!refreshApply.ok) {
+        // Apply failure is a hygiene problem (disk I/O on agents.json),
+        // not an authority problem. Ownership is already secured; surface
+        // a warning but continue.
+        err('caws claim: warning — agents.json refresh failed (display only).');
+        err((0, diagnostic_1.renderDiagnostics)(refreshApply.errors, { showData }));
+    }
+    // 8. Render the Claim panel — re-read the worktree record so it shows
+    //    the new owner / prior_owners count after the patch.
+    // We don't re-compose the snapshot because the apply functions already
+    // wrote to disk; reading the in-memory `record` (pre-patch) would lie.
+    // For determinism: reconstruct what the post-patch record looks like
+    // from the patch we just applied.
+    const renderedRecord = patch !== null && patch.kind === 'takeover_claim'
+        ? {
+            ...record,
+            owner: patch.owner,
+            last_heartbeat: patch.when,
+            prior_owners: [...(record.prior_owners ?? []), patch.prior_owner],
+        }
+        : record;
+    const newRel = (0, claim_1.classifyOwnership)(renderedRecord, session);
+    out((0, claim_1.renderClaimPanel)({
+        worktreeName,
+        worktreeRecord: renderedRecord,
+        currentSession: session,
+        now,
+        ...(opts.staleTtlMs !== undefined ? { staleTtlMs: opts.staleTtlMs } : {}),
+    }));
+    // Same-session OR successful takeover both count as "claim established".
+    // The only Ok-but-not-yours case is impossible here: assertOwnership
+    // never returns Ok with a foreign owner intact.
+    return newRel === 'you' ? 0 : 1;
+}
+//# sourceMappingURL=claim.js.map

package/dist/shell/commands/claim.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"claim.js","sourceRoot":"","sources":["../../../src/shell/commands/claim.ts"],"names":[],"mappings":"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"}

package/dist/shell/commands/doctor.d.ts

@@ -0,0 +1,13 @@
+export interface DoctorCommandOptions {
+    readonly cwd?: string;
+    readonly now?: Date;
+    readonly out?: (line: string) => void;
+    readonly err?: (line: string) => void;
+    /**
+     * Show the optional `data` block for each diagnostic/finding. Default
+     * false to keep output tight.
+     */
+    readonly showData?: boolean;
+}
+export declare function runDoctorCommand(opts?: DoctorCommandOptions): number;
+//# sourceMappingURL=doctor.d.ts.map

package/dist/shell/commands/doctor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../../src/shell/commands/doctor.ts"],"names":[],"mappings":"AAyCA,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,wBAAgB,gBAAgB,CAAC,IAAI,GAAE,oBAAyB,GAAG,MAAM,CAsExE"}

package/dist/shell/commands/doctor.js

@@ -0,0 +1,97 @@
+"use strict";
+// `caws doctor` — composition command.
+//
+// Pipeline (no business logic in this file):
+//
+//   1. resolveRepoRoot(cwd)         (store)
+//   2. composeDoctorSnapshot(...)   (store)
+//   3. inspectProjectState(input)   (kernel)
+//   4. render store-load diagnostics  (renderer)
+//   5. render doctor findings         (renderer)
+//   6. choose exit code               (this file)
+//
+// The command does NOT read .caws/ files directly, does NOT walk specs,
+// does NOT invent repair rules, and does NOT re-validate state.
+//
+// Exit codes:
+//   0 = no error-severity findings AND no error-severity store-load
+//       diagnostics
+//   1 = any error-severity finding OR any error-severity store-load
+//       diagnostic. (Store-load errors count even when they were filtered
+//       out before reaching the kernel, because an invalid spec file is a
+//       project-health problem regardless.)
+//   2 = repo-root resolution failed, or other hard composition failure.
+//
+// Testable without Commander: caller passes cwd / out / err / now and
+// receives a number. `registerShellCommands(program)` (Slice 5c.9) is the
+// only place that wires this to Commander.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctorCommand = runDoctorCommand;
+const caws_kernel_1 = require("@paths.design/caws-kernel");
+const store_1 = require("../../store");
+const index_1 = require("../index");
+function runDoctorCommand(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const now = opts.now ?? new Date();
+    const out = opts.out ?? ((s) => process.stdout.write(s + '\n'));
+    const err = opts.err ?? ((s) => process.stderr.write(s + '\n'));
+    const showData = opts.showData === true;
+    // 1. Repo root
+    const repoRootResult = (0, store_1.resolveRepoRoot)(cwd);
+    if (!repoRootResult.ok) {
+        err('caws doctor: failed to resolve repo root.');
+        err((0, index_1.renderDiagnostics)(repoRootResult.errors, { showData }));
+        return 2;
+    }
+    const { repoRoot, cawsDir } = repoRootResult.value;
+    // 2 + 3. Compose snapshot, run kernel diagnoser
+    let composition;
+    try {
+        composition = (0, store_1.composeDoctorSnapshot)({ repoRoot, cawsDir, now });
+    }
+    catch (e) {
+        err(`caws doctor: store composition failed: ${e.message}`);
+        return 2;
+    }
+    const { snapshot, doctorInput } = composition;
+    let report;
+    try {
+        report = (0, caws_kernel_1.inspectProjectState)(doctorInput);
+    }
+    catch (e) {
+        err(`caws doctor: kernel inspect failed: ${e.message}`);
+        return 2;
+    }
+    // 4. Render store-load diagnostics — kept SEPARATE from doctor findings.
+    const loadDiagnostics = [
+        ...snapshot.specDiagnostics,
+        ...snapshot.policyErrors,
+        ...snapshot.policyWarnings,
+        ...snapshot.eventWarnings,
+    ];
+    out('Store load diagnostics:');
+    if (loadDiagnostics.length === 0) {
+        out('  (none)');
+    }
+    else {
+        out((0, index_1.renderDiagnostics)(loadDiagnostics, { showData }));
+    }
+    // 5. Render doctor findings — separate section.
+    out('');
+    out('Doctor findings:');
+    if (report.findings.length === 0) {
+        out('  (none)');
+    }
+    else {
+        out((0, index_1.renderFindings)(report.findings, { showData }));
+    }
+    // 6. Exit code
+    const loadCounts = (0, index_1.countSeverities)(loadDiagnostics);
+    const findingCounts = (0, index_1.countFindingSeverities)(report.findings);
+    const hasErrors = findingCounts.errors > 0 || loadCounts.errors > 0;
+    out('');
+    out(`Summary: findings ${findingCounts.errors}E/${findingCounts.warnings}W/${findingCounts.infos}I; ` +
+        `load ${loadCounts.errors}E/${loadCounts.warnings}W/${loadCounts.infos}I`);
+    return hasErrors ? 1 : 0;
+}
+//# sourceMappingURL=doctor.js.map

package/dist/shell/commands/doctor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"doctor.js","sourceRoot":"","sources":["../../../src/shell/commands/doctor.ts"],"names":[],"mappings":"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"}

package/dist/shell/commands/evidence.d.ts

@@ -0,0 +1,28 @@
+import { type ActorKind } from '@paths.design/caws-kernel';
+export type EvidenceKind = 'test' | 'gate' | 'ac';
+export interface EvidenceRecordOptions {
+    /** Which evidence event to record. */
+    readonly kind: EvidenceKind;
+    /** Required: the spec id this evidence is about. */
+    readonly specId: string;
+    /** Required: the event payload — must match the kernel's event-type schema. */
+    readonly data: Record<string, unknown>;
+    /** Actor kind. Defaults to 'agent'. */
+    readonly actorKind?: ActorKind;
+    /** Optional actor id override. Defaults to session.identity.session_id. */
+    readonly actorId?: string;
+    /** Optional ISO-8601 ts. Defaults to now. */
+    readonly ts?: string;
+    /** Working directory. Defaults to process.cwd(). */
+    readonly cwd?: string;
+    /** Injected clock for tests. */
+    readonly now?: () => Date;
+    /** Injected env for tests. */
+    readonly env?: NodeJS.ProcessEnv;
+    readonly out?: (line: string) => void;
+    readonly err?: (line: string) => void;
+    /** Show optional `data` blocks on rendered errors. */
+    readonly showData?: boolean;
+}
+export declare function runEvidenceRecordCommand(opts: EvidenceRecordOptions): number;
+//# sourceMappingURL=evidence.d.ts.map

package/dist/shell/commands/evidence.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"evidence.d.ts","sourceRoot":"","sources":["../../../src/shell/commands/evidence.ts"],"names":[],"mappings":"AAyBA,OAAO,EAEL,KAAK,SAAS,EAGf,MAAM,2BAA2B,CAAC;AAQnC,MAAM,MAAM,YAAY,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;AAQlD,MAAM,WAAW,qBAAqB;IACpC,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,oDAAoD;IACpD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,+EAA+E;IAC/E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACvC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAC;IAC/B,2EAA2E;IAC3E,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,6CAA6C;IAC7C,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,oDAAoD;IACpD,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,gCAAgC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,IAAI,CAAC;IAC1B,8BAA8B;IAC9B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAC;IACjC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IACtC,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;CAC7B;AAeD,wBAAgB,wBAAwB,CAAC,IAAI,EAAE,qBAAqB,GAAG,MAAM,CAqG5E"}

package/dist/shell/commands/evidence.js

@@ -0,0 +1,166 @@
+"use strict";
+// `caws evidence record` — append one typed evidence event.
+//
+// Pipeline:
+//   1. resolveRepoRoot(cwd)
+//   2. resolveSession({ allowMint: true })       — this is a write op
+//   3. buildActor({ session, kind })
+//   4. construct EventBody from caller inputs   — body-only; no seq/prev/hash
+//   5. appendEvent(cawsDir, body)                 — store enforces lock,
+//                                                   chain via kernel
+//                                                   prepareAppend
+//   6. print seq + event_hash AFTER success
+//
+// Exit codes:
+//   0 = append succeeded
+//   1 = validation rejected the body OR appendEvent returned Err
+//   2 = repo-root / session resolution / composition failure
+//
+// CRITICAL: the API surface accepts EventBody-shaped inputs only. It does
+// not accept `seq`, `prev_hash`, or `event_hash`. The CLI layer parsing
+// (commander) MUST NOT add those fields. If a caller does pass them via
+// the data object, kernel `validateEventBody` rejects them (additionalProperties:
+// false on the per-event-type payload schemas).
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runEvidenceRecordCommand = runEvidenceRecordCommand;
+const path = __importStar(require("node:path"));
+const store_1 = require("../../store");
+const actor_1 = require("../session/actor");
+const resolve_session_1 = require("../session/resolve-session");
+const diagnostic_1 = require("../render/diagnostic");
+const rules_1 = require("../rules");
+const KIND_TO_EVENT_TYPE = {
+    test: 'test_recorded',
+    gate: 'gate_evaluated',
+    ac: 'ac_recorded',
+};
+function rejectPreChainedFields(data) {
+    for (const banned of ['seq', 'prev_hash', 'event_hash']) {
+        if (Object.prototype.hasOwnProperty.call(data, banned)) {
+            return banned;
+        }
+    }
+    return null;
+}
+function isEvidenceKind(value) {
+    return value === 'test' || value === 'gate' || value === 'ac';
+}
+function runEvidenceRecordCommand(opts) {
+    const cwd = opts.cwd ?? process.cwd();
+    const now = opts.now ?? (() => new Date());
+    const env = opts.env ?? process.env;
+    const out = opts.out ?? ((s) => process.stdout.write(s + '\n'));
+    const err = opts.err ?? ((s) => process.stderr.write(s + '\n'));
+    const showData = opts.showData === true;
+    // Validate the evidence kind up front (defensive — Commander should
+    // reject unknown values at the parser, but tests / programmatic callers
+    // may bypass that).
+    if (!isEvidenceKind(opts.kind)) {
+        err(`caws evidence record: invalid --type. Got ${JSON.stringify(opts.kind)}; expected test|gate|ac.`);
+        err(`(rule: ${rules_1.SHELL_RULES.COMMAND_INVALID_EVIDENCE_TYPE})`);
+        return 1;
+    }
+    // Reject pre-chained fields in the payload BEFORE doing any I/O.
+    const banned = rejectPreChainedFields(opts.data);
+    if (banned !== null) {
+        err(`caws evidence record: payload must NOT include \`${banned}\`. Pre-chained events are not accepted by this command.`);
+        err(`(rule: ${rules_1.SHELL_RULES.COMMAND_PRE_CHAINED_EVENT_REFUSED})`);
+        return 1;
+    }
+    // Require non-empty spec_id (also enforced by kernel REQUIRES_SPEC_ID
+    // fence, but we surface the shell-level error early).
+    if (typeof opts.specId !== 'string' || opts.specId.length === 0) {
+        err('caws evidence record: --spec is required.');
+        err(`(rule: ${rules_1.SHELL_RULES.COMMAND_MISSING_SPEC_ID})`);
+        return 1;
+    }
+    // 1. Repo root.
+    const repoRootResult = (0, store_1.resolveRepoRoot)(cwd);
+    if (!repoRootResult.ok) {
+        err('caws evidence record: failed to resolve repo root.');
+        err((0, diagnostic_1.renderDiagnostics)(repoRootResult.errors, { showData }));
+        return 2;
+    }
+    const { repoRoot, cawsDir } = repoRootResult.value;
+    // 2. Session (write op → allowMint).
+    const sessionResult = (0, resolve_session_1.resolveSession)({
+        cawsDir,
+        worktreeRoot: cwd,
+        env,
+        now,
+        allowMint: true,
+    });
+    if (!sessionResult.ok) {
+        err('caws evidence record: failed to resolve session identity.');
+        err((0, diagnostic_1.renderDiagnostics)(sessionResult.errors, { showData }));
+        return 2;
+    }
+    // 3. Actor envelope.
+    const actor = (0, actor_1.buildActor)({
+        session: sessionResult.value,
+        kind: opts.actorKind ?? 'agent',
+        ...(opts.actorId !== undefined ? { id: opts.actorId } : {}),
+    });
+    // 4. Body.
+    const eventType = KIND_TO_EVENT_TYPE[opts.kind];
+    const ts = opts.ts ?? now().toISOString();
+    // `EventBody.data` is typed as `EventPayload` (a union of per-event
+    // payload shapes). The kernel will validate against the right schema
+    // at append time; we hand off the caller's already-parsed object.
+    const body = {
+        event: eventType,
+        ts,
+        actor,
+        spec_id: opts.specId,
+        data: opts.data,
+    };
+    // 5. Append. `appendEvent` calls `prepareAppend` which calls
+    // `validateEventBody` against the per-type schema.
+    const appendResult = (0, store_1.appendEvent)(cawsDir, body);
+    if (!appendResult.ok) {
+        err('caws evidence record: append rejected.');
+        err((0, diagnostic_1.renderDiagnostics)(appendResult.errors, { showData }));
+        return 1;
+    }
+    // 6. Print outcome AFTER success. Includes seq + event_hash so the
+    // caller (agent or human) gets a stable handle for the new event.
+    const ev = appendResult.value;
+    out(`recorded ${ev.event} seq=${ev.seq} hash=${ev.event_hash} spec=${ev.spec_id ?? '(none)'}`);
+    // Print the relative events file path for ergonomics.
+    out(`  written to ${path.relative(repoRoot, path.join(cawsDir, 'events.jsonl'))}`);
+    return 0;
+}
+//# sourceMappingURL=evidence.js.map