@aperant/framework 0.8.1 → 0.8.6

package/dist/driver-sdk/manifest.d.ts

@@ -0,0 +1,93 @@
+/**
+ * manifest.ts — TypeScript shape of a driver manifest.
+ *
+ * Mirrors `packages/framework/src/cli/verify-proof/manifest-schema.json`
+ * (ST03) one-to-one. The JSON Schema is the runtime validator (publish-
+ * time + load-time); this TS type is what third-party driver authors
+ * `import type` to author manifests with intellisense.
+ *
+ * Spec authority: spec.md §ID-03 (trust tiers) + §ID-04 (driver layout).
+ */
+export type TrustTier = 'first_party_signed' | 'community_verified' | 'community_unverified' | 'local_unverified';
+export type Stability = 'experimental' | 'beta' | 'ga';
+export type SandboxProfile = 'read_only' | 'workspace_write' | 'system_write';
+export type NetworkPosture = 'deny' | 'allowlist' | 'allow';
+/** Structured local-command — strings are NEVER accepted (ID-03). */
+export interface LocalCommand {
+    readonly binary: string;
+    readonly args: readonly string[];
+}
+/** Transport — exactly one of the variants. */
+export type Transport = {
+    readonly mcp_server_id: string;
+} | {
+    readonly local_command: LocalCommand;
+} | {
+    readonly http_endpoint: string;
+} | {
+    readonly npm_package: string;
+} | {
+    readonly builtin: true;
+};
+export interface Publisher {
+    readonly name: string;
+    readonly npm_scope?: string;
+    readonly github_org?: string;
+    readonly verified?: boolean;
+}
+export interface Provenance {
+    readonly scheme?: 'sigstore' | 'npm-provenance' | 'gpg' | 'none';
+    readonly identity?: string;
+    readonly signature?: string;
+    readonly certificate?: string;
+}
+export interface Integrity {
+    readonly manifest_sha256?: string;
+    readonly artifact_digest?: string;
+}
+export interface TrustBlock {
+    readonly tier: TrustTier;
+    readonly publisher?: Publisher;
+    readonly provenance?: Provenance;
+    readonly integrity?: Integrity;
+}
+export interface SecurityBlock {
+    readonly sandbox_profile: SandboxProfile;
+    readonly network: NetworkPosture;
+    readonly allowed_executables?: readonly string[];
+    readonly allow_shell?: boolean;
+    readonly requires_user_approval?: boolean;
+}
+export interface AuditBlock {
+    readonly log_invocations: boolean;
+    readonly log_manifest_hash: boolean;
+}
+export interface PreflightCheck {
+    readonly name: string;
+    readonly command?: LocalCommand;
+    readonly required: boolean;
+}
+export interface DriverManifest {
+    readonly driverId: string;
+    readonly version: string;
+    readonly targets: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly evidence_capabilities?: readonly string[];
+    readonly frameworkApiRange: string;
+    readonly requires?: {
+        readonly allOf?: readonly string[];
+        readonly anyOf?: readonly string[];
+    };
+    readonly os?: readonly string[];
+    readonly arch?: readonly string[];
+    readonly container_support?: boolean;
+    readonly conflicts_with?: readonly string[];
+    readonly priority: number;
+    readonly stability: Stability;
+    readonly trust: TrustBlock;
+    readonly security: SecurityBlock;
+    readonly audit?: AuditBlock;
+    readonly preflight?: readonly PreflightCheck[];
+    readonly transport: Transport;
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/driver-sdk/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/driver-sdk/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,MAAM,SAAS,GAClB,oBAAoB,GACpB,oBAAoB,GACpB,sBAAsB,GACtB,kBAAkB,CAAA;AAErB,MAAM,MAAM,SAAS,GAAG,cAAc,GAAG,MAAM,GAAG,IAAI,CAAA;AAEtD,MAAM,MAAM,cAAc,GAAG,WAAW,GAAG,iBAAiB,GAAG,cAAc,CAAA;AAE7E,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,WAAW,GAAG,OAAO,CAAA;AAE3D,qEAAqE;AACrE,MAAM,WAAW,YAAY;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAA;CAChC;AAED,+CAA+C;AAC/C,MAAM,MAAM,SAAS,GAClB;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,aAAa,EAAE,YAAY,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,QAAQ,CAAC,OAAO,EAAE,IAAI,CAAA;CAAE,CAAA;AAE7B,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAA;CAC3B;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,gBAAgB,GAAG,KAAK,GAAG,MAAM,CAAA;IAChE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;CAC7B;AAED,MAAM,WAAW,SAAS;IACzB,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CACjC;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,CAAA;CAC9B;AAED,MAAM,WAAW,aAAa;IAC7B,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAA;IACxC,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAA;IAChC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAChD,QAAQ,CAAC,WAAW,CAAC,EAAE,OAAO,CAAA;IAC9B,QAAQ,CAAC,sBAAsB,CAAC,EAAE,OAAO,CAAA;CACzC;AAED,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;IACjC,QAAQ,CAAC,iBAAiB,EAAE,OAAO,CAAA;CACnC;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,OAAO,CAAC,EAAE,YAAY,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAA;CAC1B;AAED,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAA;IACnC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAA;IACxC,QAAQ,CAAC,qBAAqB,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAClD,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,QAAQ,CAAC,EAAE;QACnB,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;QAClC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;KAClC,CAAA;IACD,QAAQ,CAAC,EAAE,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC/B,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IACjC,QAAQ,CAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;IACpC,QAAQ,CAAC,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;IAC3C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAA;IAC1B,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAA;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,cAAc,EAAE,CAAA;IAC9C,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;CAC7B"}

package/dist/driver-sdk/manifest.js

@@ -0,0 +1,12 @@
+/**
+ * manifest.ts — TypeScript shape of a driver manifest.
+ *
+ * Mirrors `packages/framework/src/cli/verify-proof/manifest-schema.json`
+ * (ST03) one-to-one. The JSON Schema is the runtime validator (publish-
+ * time + load-time); this TS type is what third-party driver authors
+ * `import type` to author manifests with intellisense.
+ *
+ * Spec authority: spec.md §ID-03 (trust tiers) + §ID-04 (driver layout).
+ */
+export {};
+//# sourceMappingURL=manifest.js.map

package/dist/driver-sdk/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/driver-sdk/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/driver-sdk/retry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * retry.ts — exponential backoff helper with abort signal.
+ *
+ * Used by driver implementations that want to retry transient transport
+ * failures (DriverInvocationError) before giving up. Pure, dependency-free.
+ */
+export interface RetryOptions {
+    /** Total maximum attempts including the first. Default 3. */
+    readonly max_attempts?: number;
+    /** Initial delay in ms before the second attempt. Default 100. */
+    readonly base_delay_ms?: number;
+    /** Cap each delay at this many ms. Default 5000. */
+    readonly max_delay_ms?: number;
+    /**
+     * Multiplier applied to delay after each failed attempt. Default 2 →
+     * 100ms, 200ms, 400ms, 800ms, …
+     */
+    readonly multiplier?: number;
+    /** Optional AbortSignal — abort short-circuits the retry loop. */
+    readonly signal?: AbortSignal;
+    /**
+     * Optional predicate. When provided, only retry when shouldRetry(err) is
+     * true; otherwise re-throw immediately. Default: retry every error.
+     */
+    readonly shouldRetry?: (err: unknown) => boolean;
+}
+/**
+ * Run `fn` with exponential backoff. Returns the result of the first
+ * successful call. If every attempt fails (or the signal aborts), throws
+ * the last error.
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/driver-sdk/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/driver-sdk/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAA;CAChD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACvC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,YAAiB,GACrB,OAAO,CAAC,CAAC,CAAC,CAqCZ"}

package/dist/driver-sdk/retry.js

@@ -0,0 +1,50 @@
+/**
+ * retry.ts — exponential backoff helper with abort signal.
+ *
+ * Used by driver implementations that want to retry transient transport
+ * failures (DriverInvocationError) before giving up. Pure, dependency-free.
+ */
+/**
+ * Run `fn` with exponential backoff. Returns the result of the first
+ * successful call. If every attempt fails (or the signal aborts), throws
+ * the last error.
+ */
+export async function retryWithBackoff(fn, opts = {}) {
+    const maxAttempts = Math.max(1, opts.max_attempts ?? 3);
+    const baseDelay = Math.max(0, opts.base_delay_ms ?? 100);
+    const maxDelay = Math.max(0, opts.max_delay_ms ?? 5000);
+    const multiplier = opts.multiplier ?? 2;
+    const signal = opts.signal;
+    const shouldRetry = opts.shouldRetry ?? (() => true);
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (signal?.aborted) {
+            throw signal.reason instanceof Error ? signal.reason : new Error('retryWithBackoff aborted');
+        }
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt >= maxAttempts)
+                break;
+            if (!shouldRetry(err))
+                break;
+            const delay = Math.min(maxDelay, baseDelay * multiplier ** (attempt - 1));
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(resolve, delay);
+                if (signal) {
+                    const onAbort = () => {
+                        clearTimeout(timer);
+                        reject(signal.reason instanceof Error
+                            ? signal.reason
+                            : new Error('retryWithBackoff aborted'));
+                    };
+                    signal.addEventListener('abort', onAbort, { once: true });
+                }
+            });
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+//# sourceMappingURL=retry.js.map

package/dist/driver-sdk/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/driver-sdk/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,EAAoB,EACpB,OAAqB,EAAE;IAEvB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,CAAA;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,IAAI,GAAG,CAAC,CAAA;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,CAAA;IACvD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAA;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC1B,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;IAEpD,IAAI,OAAgB,CAAA;IACpB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACzD,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACrB,MAAM,MAAM,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAA;QAC7F,CAAC;QACD,IAAI,CAAC;YACJ,OAAO,MAAM,EAAE,EAAE,CAAA;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,OAAO,GAAG,GAAG,CAAA;YACb,IAAI,OAAO,IAAI,WAAW;gBAAE,MAAK;YACjC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;gBAAE,MAAK;YAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,GAAG,UAAU,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;YACzE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;gBACxC,IAAI,MAAM,EAAE,CAAC;oBACZ,MAAM,OAAO,GAAG,GAAG,EAAE;wBACpB,YAAY,CAAC,KAAK,CAAC,CAAA;wBACnB,MAAM,CACL,MAAM,CAAC,MAAM,YAAY,KAAK;4BAC7B,CAAC,CAAC,MAAM,CAAC,MAAM;4BACf,CAAC,CAAC,IAAI,KAAK,CAAC,0BAA0B,CAAC,CACxC,CAAA;oBACF,CAAC,CAAA;oBACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;gBAC1D,CAAC;YACF,CAAC,CAAC,CAAA;QACH,CAAC;IACF,CAAC;IACD,MAAM,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;AACtE,CAAC"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.8.1",
+  "version": "0.8.6",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": {
     "name": "Mikalsen AI",
@@ -25,6 +25,7 @@
     "skills/apt",
     "skills/apt-author-skill",
     "skills/apt-bootstrap",
+    "skills/apt-caveman",
     "skills/apt-classify",
     "skills/apt-close-task",
     "skills/apt-create-docs",
@@ -35,6 +36,7 @@
     "skills/apt-docs",
     "skills/apt-execute",
     "skills/apt-fan-out",
+    "skills/apt-handoff",
     "skills/apt-improve",
     "skills/apt-mockup",
     "skills/apt-pause",
@@ -44,6 +46,7 @@
     "skills/apt-prototype",
     "skills/apt-quick",
     "skills/apt-release-notes",
+    "skills/apt-research",
     "skills/apt-resume",
     "skills/apt-review",
     "skills/apt-roadmap",

package/dist/plugin/agents/apt-planner.md

@@ -32,7 +32,8 @@ Before planning, discover project context:
 <environment>
 - **Working directory:** The project root
 - **apt-tools:** Always invoke as `node packages/framework/bin/apt-tools.mjs`
-- **Task directory:** Provided in the spawn prompt as `task_dir`. ALL artifacts (spec.md, implementation_plan.json) are written here, NOT to project root.
+- **Task directory:** Provided in the spawn prompt as `task_dir`. It MUST be an absolute path under the main repo's `.aperant/tasks/{task-id}/`. ALL artifacts (spec.md, implementation_plan.json) are written here, NOT to project root and NOT to a worktree-local `.aperant/tasks/` directory.
+- **Worktree path:** If provided, use it only for code investigation/editing context. Do not derive artifact paths from it.
 - **Config:** `.aperant/config.json` — project preferences
 - **State:** `.aperant/state.json` — execution state
 </environment>
@@ -43,7 +44,7 @@ Before planning, discover project context:
 
 1. Read `CLAUDE.md` and `AGENTS.md` if they exist — extract conventions, stack, constraints
 2. Run `node packages/framework/bin/apt-tools.mjs state .` to understand current project state
-3. Parse the task description and task_dir from the spawn prompt
+3. Parse the task description and task_dir from the spawn prompt. If task_dir is relative, resolve the real main repo path first instead of writing under the current worktree.
 
 ## 2. Assess Complexity
 
@@ -211,7 +212,7 @@ If unable to enumerate (network unavailable, action docs unclear), flag it expli
 
 ## 4. Write Specification
 
-The spec.md content format **branches on track** (Pocock adoption ID-05,
+The spec.md content format **branches on track** (ID-05,
 Fast Path Guarantee). QUICK-routed tasks keep the existing 4-section
 shape; STANDARD/DEEP/COMPLEX tasks get a PRD-shaped artifact that
 survives the task as a second-consumer document.
@@ -239,6 +240,11 @@ survives the task as a second-consumer document.
 
 ### 4.B. STANDARD / DEEP / COMPLEX — PRD-shaped spec.md
 
+**Three orthogonal user-facing sections — keep them distinct.** User
+Stories (motivation prose), User Outcomes (verify-proof input contract),
+and Acceptance Criteria (code-level invariants) serve distinct
+purposes. Do NOT collapse them — STANDARD/DEEP specs carry all three.
+
 ```markdown
 # Spec: {task title}
 
@@ -256,6 +262,22 @@ survives the task as a second-consumer document.
 {One **US-NN (persona).** story per user-value slice. Stories map 1:1
 onto subtasks in implementation_plan.json.}
 
+## User Outcomes
+{Verify-proof input contract. One bolded `**Epic:**` headline + N
+atomic outcomes. Authors write the LITERAL string `**ON**` — IDs are
+POSITIONAL and synthesized by the parser (first row becomes O1, second
+O2, ...). Closed surface set: `electron | web | cli | api | electron+web`.
+Optional cross-refs via `*(requires ON N)*`. Refactor-only specs MAY
+use the empty-with-note escape (verbatim string,
+italic underscores + em dash + period required):}
+
+`_No user-observable changes — pure refactor._`
+
+**Epic:** {one-sentence user-facing capability headline}
+
+- **ON** [surface]: {user does X; system shows/does Y}
+- **ON** [surface]: {user does X; system shows/does Y} *(requires ON 1)*
+
 ## Implementation Decisions
 {Load-bearing principles carried into every subtask. Format:
 "### ID-NN: {title}" + rationale + practical consequence.}
@@ -278,9 +300,19 @@ reference these IDs via the per-subtask `acceptance_criteria` field.}
 ```
 
 **PRD section ordering is load-bearing.** `apt-tools coverage-check
-validate` greps `## Acceptance Criteria`; `apt-tools consistency check`
-greps `## Solution` and `## User Stories`. Renaming or reordering these
-sections breaks downstream tooling and the C15 consistency rules.
+validate` greps `## Acceptance Criteria` AND `## User Outcomes`;
+`apt-tools consistency check` greps `## Solution` and `## User Stories`.
+Renaming or reordering these sections breaks downstream tooling and the
+C15 consistency rules.
+
+**`## User Outcomes` synthesis directive.** Outcomes are
+user-observable (a user does X; the system shows/does Y); Acceptance
+Criteria are code-level invariants (a function returns X; a config key
+exists). Do NOT collapse them — they parse through different gates and
+serve different consumers. STANDARD/DEEP specs carry both sections in
+parallel. IDs are POSITIONAL: the parser counts outcome rows in
+document order and synthesizes `O1`, `O2`, ... — authors MUST write
+the literal `**ON**` token, never `**O1**`/`**O2**`.
 
 **Do NOT interview the user.** The PRD is synthesized from the task
 description + codebase investigation + AGENTS.md, not from a clarifying
@@ -344,7 +376,7 @@ fix it now, not later.
 
 ## 5. Create Implementation Plan
 
-Subtask schema branches on track (Pocock adoption ID-05 — Fast Path Guarantee).
+Subtask schema branches on track.
 
 ### 5.A. QUICK track / SIMPLE complexity — legacy flat subtask schema
 

package/dist/plugin/skills/apt/SKILL.md

@@ -386,18 +386,27 @@ Parse `task_id`, `task_dir`, and (if present) `worktree.worktree_path` / `worktr
 Important nuances:
 - `task_dir` is an **absolute path** under the main repo's `.aperant/tasks/{task-id}/`. All spec/plan/progress artifacts live there and are shared across worktrees.
 - `apt-tools` commands still receive the **project root** as `<project-dir>` — they coordinate state through the main repo's `.aperant/`. The worktree only affects *code editing* cwd.
-- When spawning an agent, set its `cwd` (or prefix its Bash calls with `cd {worktree_path} &&`) to the worktree. Pass `worktree_path` in the agent's context so it knows where it is.
+- When spawning an agent, set its `cwd` (or prefix its Bash calls with `cd {worktree_path} &&`) to the worktree for code reads/edits. Pass `worktree_path` in the agent's context so it knows where code work happens.
+- Planner artifact safety: do **not** spawn `apt-planner` with host-level worktree isolation that gives it a separate copied repo. The planner must write `spec.md` and `implementation_plan.json` to the absolute main-repo `task_dir` from `task create`; `.aperant/tasks/**` is gitignored, so artifacts written under a disposable worktree can be invisible to git and lost when that worktree is cleaned.
 - If no `worktree` block is returned, proceed in the project root as before.
 
 ### Step 3: Spawn Planner Agent
 
 **If `spawn_agent` is true (STANDARD/DEEP):**
 
-Print phase marker BEFORE spawning:
+Print the phase rail BEFORE spawning. Render the panel verbatim — branch glyphs `┌─ │ └─`, status glyphs `✓` (done) / `●` (active) / `○` (pending), one phase per row, inline metrics on completed rows when available:
+
 ```
 [APT] Phase 1/N — Planning (spawning apt-planner agent)
+┌─ Phase rail: {short task name} ───────────────────
+│  Phase 1 Plan       ●  spawning apt-planner
+│  Phase 2 Execute    ○
+│  Phase 3 Verify     ○
+│  Phase 4 Review     ○
+└───────────────────────────────────────────────────
 ```
-(N = total pipeline phases: e.g. plan+execute+verify+review = 4, discuss+plan+… = 5)
+
+(N = total pipeline phases: e.g. plan+execute+verify+review = 4, discuss+plan+… = 5. Keep the `[APT] Phase X/N` header line — it's the backward-compat marker that external grep tooling relies on. The rail panel sits directly below it.)
 
 You **MUST** use the `Task` tool to spawn `apt-planner` — do NOT write
 `spec.md` or `implementation_plan.json` inline using the `Write` tool. The
@@ -414,8 +423,9 @@ Spawn `apt-planner` via Task tool with context:
 ```
 Task: {task_description}
 Task ID: {task_id}
-Task Dir: {task_dir}
+Task Dir: {task_dir}  # absolute path under the main repo, not under worktree_path
 Track: {track}
+Worktree Path: {worktree_path or "none"}
 
 <files_to_read>
 - CLAUDE.md (if exists)
@@ -423,7 +433,7 @@ Track: {track}
 - Any brainstorm notes at .aperant/context/notes/{task_id}-brainstorm.md
 </files_to_read>
 
-Write spec.md and implementation_plan.json to {task_dir}/
+Write spec.md and implementation_plan.json to {task_dir}/. Do not write plan artifacts to `{worktree_path}/.aperant/tasks/...` or any relative `.aperant/tasks/...` path.
 ```
 
 After the agent returns, emit a token running-total line:
@@ -445,9 +455,32 @@ The user's chosen option has a `pipeline` array (e.g. `["plan", "execute", "veri
 **execution_mode = "auto":**
 Auto-chain without waiting. STANDARD and DEEP auto pipelines both follow Plan → execute → verify → review (DEEP additionally leads with discuss).
 
-Each phase transition MUST emit a status marker for visibility:
+Each phase transition MUST emit a status marker AND re-render the phase rail showing the updated state for ALL phases. The rail is the user's primary signal — render it verbatim, do not summarize or skip.
+
 ```
 [APT] Phase {current}/{total} — {name} (spawning {agent})
+┌─ Phase rail: {short task name} ───────────────────
+│  Phase 1 Plan       ✓  {N} subtasks
+│  Phase 2 Execute    ●  spawning apt-executor
+│  Phase 3 Verify     ○
+│  Phase 4 Review     ○
+└───────────────────────────────────────────────────
+```
+
+Metric conventions per phase row (omit metrics on `○` pending rows):
+- **Plan ✓**: `N subtasks`
+- **Execute ✓**: `N commits, K tests` (or `N/M subtasks` mid-execute on `●`)
+- **Verify ✓**: `APPROVED a/b/c/d` (completeness/correctness/quality/coverage)
+- **Review ✓**: `APPROVE a/b/c/d/e/f, K findings fixed` (or `request-changes, K open`)
+- **Ship ✓**: `PR #N` (the SHIPPED collapsed variant — see below)
+
+When ship completes (lifecycle `shipped-pending-merge` + PR URL exists), collapse to the SHIPPED variant:
+
+```
+┌─ {short task name} ────────────────────── ✅ SHIPPED
+│  Plan ✓ Execute ✓ Verify ✓ Review ✓ Ship ✓
+│  PR #{N}: {url}
+└───────────────────────────────────────────────────
 ```
 
 Full auto-chain sequence (STANDARD = 4 phases, DEEP = 5 phases):
@@ -460,6 +493,42 @@ Full auto-chain sequence (STANDARD = 4 phases, DEEP = 5 phases):
 After EACH agent returns, emit the token running-total line (same pattern
 as Step 3: `tokens tally` then print `[APT] Tokens: input+output = total`).
 
+#### Consent-driven --spar-gates auto-inject (FRAMEWORK-RFC-001)
+
+The route envelope carries the consent signal deterministically — do NOT
+re-read `.aperant/config.local.json` from prompt-space. Two envelope fields
+drive the decision, both emitted by `route.mjs` per spec §4.10:
+
+1. **`envelope.spar_inject_gates`** — present only on the flag-override path
+   (explicit `--quick` / `--deep` / `--debug`) when consent is on AND the
+   user did NOT pass an explicit `--spar-gates`. Value is `"plan"` (STANDARD)
+   or `"plan,execute"` (DEEP). When set, append `--spar-gates <value>` to
+   the chained `/apt:run` invocation. **Do NOT recompute** — the deterministic
+   contract lives in code, not prompt-space.
+
+2. **`envelope.spar_consent`** — present on the host-LLM classify path.
+   Shape: `{ enabled: boolean, partner: string|null, user_passed_explicit_gates: boolean }`.
+   After you (the host model) pick a track via Step 0c:
+   - **Track === QUICK or DEBUG: do NOT inject.** QUICK is Fast-Path-exempt
+     (CLAUDE.md Fast Path Guarantee); DEBUG produces no spec/plan to spar
+     against.
+   - **Track === STANDARD** AND `spar_consent.enabled === true` AND
+     `spar_consent.user_passed_explicit_gates === false`: append
+     `--spar-gates plan` to the `/apt:run` invocation.
+   - **Track === DEEP** AND `spar_consent.enabled === true` AND
+     `spar_consent.user_passed_explicit_gates === false`: append
+     `--spar-gates plan,execute` to the `/apt:run` invocation.
+   - `user_passed_explicit_gates === true`: the user already supplied
+     `--spar-gates` — do NOT double-inject. Their flag is already in the
+     dispatched invocation.
+
+If `envelope.spar_consent` is absent (consent never configured) AND
+`envelope.spar_inject_gates` is absent, do NOT inject. The signal is
+**deterministic** — Step 4 reads ONLY the envelope fields above. Do NOT
+re-read `.aperant/config.local.json` from prompt-space; the
+consent-resolution helper is wired into `route.mjs` and the envelope is
+the canonical contract. The structural test grep-locks this invariant.
+
 **execution_mode = "step" or "research":**
 After each stage in the pipeline, show result and ask before proceeding:
 ```

package/dist/plugin/skills/apt-caveman/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: apt:caveman
+description: "Ultra-compressed communication mode — toggle terse 'smart caveman' output to cut token usage ~75% while keeping full technical accuracy"
+apt-skill-version: {{APT_VERSION}}
+stage: ops
+intent: configure
+when_to_use: "The user invokes /apt:caveman, or says 'caveman mode', 'talk like caveman', 'be brief', 'less tokens'. Toggles a persistent terse output mode. Off with 'stop caveman' or 'normal mode'."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_execution_mode: auto
+execution_modes:
+  - auto
+allowed-tools: ""
+argument-hint: "apt:caveman"
+gates: []
+---
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+## Persistence
+
+ACTIVE EVERY RESPONSE once triggered. No revert after many turns. No filler drift. Still active if unsure. Off only when user says "stop caveman" or "normal mode".
+
+## Rules
+
+Drop: articles (a/an/the), filler (just/really/basically/actually/simply), pleasantries (sure/certainly/of course/happy to), hedging. Fragments OK. Short synonyms (big not extensive, fix not "implement a solution for"). Abbreviate common terms (DB/auth/config/req/res/fn/impl). Strip conjunctions. Use arrows for causality (X -> Y). One word when one word enough.
+
+Technical terms stay exact. Code blocks unchanged. Errors quoted exact.
+
+Pattern: `[thing] [action] [reason]. [next step].`
+
+Not: "Sure! I'd be happy to help you with that. The issue you're experiencing is likely caused by..."
+Yes: "Bug in auth middleware. Token expiry check use `<` not `<=`. Fix:"
+
+### Examples
+
+**"Why React component re-render?"**
+
+> Inline obj prop -> new ref -> re-render. `useMemo`.
+
+**"Explain database connection pooling."**
+
+> Pool = reuse DB conn. Skip handshake -> fast under load.
+
+## Auto-Clarity Exception
+
+Drop caveman temporarily for: security warnings, irreversible action confirmations, multi-step sequences where fragment order risks misread, user asks to clarify or repeats question. Resume caveman after clear part done.
+
+Example — destructive op:
+
+> **Warning:** This will permanently delete all rows in the `users` table and cannot be undone.
+>
+> ```sql
+> DROP TABLE users;
+> ```
+>
+> Caveman resume. Verify backup exist first.
+
+## Boundaries
+
+Code, commits, PRs: write normal (full sentences in commit bodies / PR descriptions). Only conversational output is compressed. `stop caveman` / `normal mode` reverts.

package/dist/plugin/skills/apt-debug/SKILL.md

@@ -22,7 +22,7 @@ gates: []
 <objective>
 Debug an issue using the scientific method: observe symptoms, form hypotheses, test them systematically, and reach a conclusion. State persists across context resets via `.aperant/debug/{session-id}/DEBUG.md`.
 
-**Diagnose-discipline posture loader (Pocock adoption AC10).** You MUST
+**Diagnose-discipline posture loader.** You MUST
 load `appendices/diagnose-discipline.md` into reasoning context at
 session start. It carries the 6-phase loop (Reproduce → Minimise →
 Hypothesise → Instrument → Fix → Regression-test) and the **Phase-1
@@ -61,12 +61,44 @@ reproduction, so loading this appendix is non-trivial.
 ## 1. Initialize or Resume Session
 
 Parse `$ARGUMENTS`:
-- **New session:** Generate session ID from timestamp (`debug-YYYYMMDD-HHmm`)
-- **`--resume <session-id>`:** Read existing `.aperant/debug/{session-id}/DEBUG.md` and continue from last state
-- **`--resume` (no id):** Find the most recent session in `.aperant/debug/` and resume it
+- **New session:** resolve a canonical task id (see 1a below), then use it as the `{session-id}` for the debug working directory.
+- **`--resume <session-id>`:** Read existing `.aperant/debug/{session-id}/DEBUG.md` and continue from last state. Skip Section 1a — the session id is already canonical.
+- **`--resume` (no id):** Find the most recent session in `.aperant/debug/` and resume it. Skip Section 1a.
 
 If resuming, read DEBUG.md and skip to the current phase (observe/hypothesize/test/conclude).
 
+### 1a. Resolve canonical task id (idempotent — new sessions only)
+
+DEBUG now produces a canonical state.active_tasks record so `/apt:ship` can find the task via the lite ship profile once the fix is committed. The body owns idempotency because `apt-tools task create` does NOT guard against existing ids (see spec §3 R8).
+
+Two invocation paths converge here:
+
+- **Router path** (`/apt` → `/apt:debug`): the router has already called `task create` and injected `task_id` into your skill context.
+- **Direct path** (`/apt:debug foo`): no `task_id` in context — you create one now.
+
+Sequence:
+
+1. **If `task_id` is present in skill context** (router path):
+   ```bash
+   apt-tools task get . --id {task_id}
+   ```
+   - If exit 0 AND the returned record has `track === "DEBUG"` → reuse, skip the create call. Adopt `task_id` as `{session-id}`.
+   - Else (record missing OR wrong track) → call:
+     ```bash
+     apt-tools task create . --description "$ARGUMENTS" --track DEBUG --id {task_id}
+     ```
+     Adopt the id as `{session-id}`.
+
+2. **If no `task_id` in skill context** (direct path):
+   ```bash
+   apt-tools task create . --description "$ARGUMENTS" --track DEBUG
+   ```
+   Parse the generated `task_id` from the envelope and adopt it as `{session-id}`. The canonical id replaces the legacy `debug-YYYYMMDD-HHmm` form.
+
+The debug working dir at `.aperant/debug/{session-id}/` stays — that working artifact is preserved (per spec §3 R7). The canonical task record at `.aperant/tasks/{task-id}/` is created in parallel by `task create`, and both share the same id.
+
+### 1b. Create debug working directory
+
 ```bash
 mkdir -p .aperant/debug/{session-id}
 mkdir -p .aperant/debug/{session-id}/checkpoints

package/dist/plugin/skills/apt-debug/appendices/diagnose-discipline.md

@@ -1,12 +1,3 @@
-<!--
-Adapted from Matt Pocock's MIT-licensed skill suite:
-https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnose
-Licensed under MIT. Modifications: ported as an apt:debug posture loader
-so the 6-phase loop attaches to the existing 5-phase apt:debug body
-without forking apt:debug's control flow. Aligned with apt:debug's
-DEBUG.md state file and checkpoint conventions.
--->
-
 # Diagnose Discipline — apt:debug posture loader (6-phase loop)
 
 This appendix loads into `apt:debug`'s reasoning context as a posture
@@ -15,7 +6,7 @@ upgrade. The existing apt:debug body has 5 phases (Observe → Hypothesize
 symptom-gathering with reproduction. Open question #1 was verified — the
 gap is real, the appendix is non-trivial.
 
-This appendix carries the 6-phase Pocock discipline. The skill body
+This appendix carries the 6-phase Aperant discipline. The skill body
 loads it and uses Phase 1 (Reproduce) as a **hard prerequisite** before
 advancing from Observe to Hypothesize.
 
@@ -82,7 +73,7 @@ run on demand to trigger the failure.
 
 These are different mental modes. Minimise asks "what's the smallest
 thing that still fails?" — a reductive activity. Hypothesise asks
-"WHY does it fail?" — an explanatory activity. Pocock's discipline
+"WHY does it fail?" — an explanatory activity. the discipline
 separates them because skipping Phase 2 and going straight from "I can
 repro" to "here's why" tends to anchor on the first plausible cause
 and miss alternatives.

package/dist/plugin/skills/apt-discuss/SKILL.md

@@ -47,7 +47,7 @@ These are two postures of the same skill, not two different skills. The
 intent-detection step below decides which one to enter — same file, same
 artifact layout, different section populated.
 
-**Decision-lock posture loader (Pocock adoption ID-02 + ID-04 — AC11).**
+**Decision-lock posture loader (ID-02 + ID-04 — AC11).**
 When entering decision-lock posture, you MUST load
 `appendices/grill-discipline.md` into reasoning context. It carries the
 validated 100-token reframe sentence ("Your job is not to emit a plan;
@@ -60,7 +60,7 @@ source for the autonomy-aware rule; downstream skills (`apt:improve`,
 `apt:triage`) reference it rather than re-stating the policy. Brainstorm
 posture does NOT load this appendix.
 
-**Brainstorm posture zoom-out helper (Pocock adoption AC6 + AC11).**
+**Brainstorm posture zoom-out helper (AC6 + AC11).**
 When in brainstorm posture and the user's turn contains a zoom-out
 trigger phrase ("give me a broader picture", "I'm lost in this area",
 "explain how this fits", "what's the surrounding architecture", "zoom
@@ -565,9 +565,9 @@ Review-Auto is Auto Mode **plus one human checkpoint at the batch end**. It does
 
 Do NOT introduce per-decision staging ("show me D-01, wait, show me D-02, wait...") — that collapses review-auto into spaced interactive mode and defeats the point of joint reasoning up front. Do NOT skip the pause ("autonomy is high, let's just write it") — that collapses review-auto into auto. The one pause at the end is the whole identity of this mode.
 
-## 6.5. Grill Mode (`--grill` flag — Pocock `grill-with-docs` overlay)
+## 6.5. Grill Mode (`--grill` flag — Aperant `grill-with-docs` overlay)
 
-**Activate when:** the user invoked the skill with `--grill`. This is an **overlay**, not a mode — it stacks on top of whichever Section 6 mode is active (Interactive by default; combine with `--auto` etc. as desired). The overlay does two things: (1) it applies Pocock's 4 grill moves during decision resolution; (2) it fires inline writes to CONTEXT.md and ADRs as terms resolve and decisions pass the Nygard 3-gate.
+**Activate when:** the user invoked the skill with `--grill`. This is an **overlay**, not a mode — it stacks on top of whichever Section 6 mode is active (Interactive by default; combine with `--auto` etc. as desired). The overlay does two things: (1) it applies the 4 grill moves during decision resolution; (2) it fires inline writes to CONTEXT.md and ADRs as terms resolve and decisions pass the Nygard 3-gate.
 
 The discipline this overlay loads is already in [`appendices/grill-discipline.md`](./appendices/grill-discipline.md) — re-read the reframe sentence and the autonomy degradation table before each grill turn. **Do NOT duplicate that content here.** What follows is only the moves + writer-call instructions specific to the overlay.