@aperant/framework 0.8.1 → 0.8.6

package/drivers/electron/manifest.json

@@ -0,0 +1,37 @@
+{
+	"driverId": "electron",
+	"version": "0.1.0",
+	"targets": ["electron@>=25"],
+	"capabilities": [
+		"click",
+		"type",
+		"key",
+		"navigate",
+		"screenshot",
+		"assert_visible",
+		"assert_text",
+		"wait_for_idle",
+		"execute_js",
+		"dump_state"
+	],
+	"evidence_capabilities": ["screenshot", "dom_dump", "capture_logs"],
+	"frameworkApiRange": "^1.0.0",
+	"priority": 90,
+	"stability": "ga",
+	"trust": {
+		"tier": "first_party_signed",
+		"publisher": {
+			"name": "Aperant",
+			"npm_scope": "@aperant",
+			"github_org": "Mikalsen-AI",
+			"verified": true
+		}
+	},
+	"security": {
+		"sandbox_profile": "workspace_write",
+		"network": "deny",
+		"requires_user_approval": false
+	},
+	"audit": { "log_invocations": true, "log_manifest_hash": true },
+	"transport": { "mcp_server_id": "electron" }
+}

package/package.json

@@ -1,134 +1,139 @@
 {
-	"name": "@aperant/framework",
-	"version": "0.8.1",
-	"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": "Mikalsen AI <hello@mikalsen.ai>",
-	"type": "module",
-	"main": "./dist/index.js",
-	"types": "./dist/index.d.ts",
-	"bin": {
-		"framework": "./bin/apt-tools.mjs",
-		"apt-tools": "./bin/apt-tools.mjs",
-		"apt-proof-video": "./bin/apt-proof-video.mjs"
-	},
-	"exports": {
-		".": {
-			"types": "./dist/index.d.ts",
-			"import": "./dist/index.js"
-		},
-		"./types": {
-			"types": "./dist/types/index.d.ts",
-			"import": "./dist/types/index.js"
-		},
-		"./cost": {
-			"types": "./dist/cost/index.d.ts",
-			"import": "./dist/cost/index.js"
-		},
-		"./mappers": {
-			"types": "./dist/mappers/index.d.ts",
-			"import": "./dist/mappers/index.js"
-		},
-		"./schemas": {
-			"types": "./dist/schemas/index.d.ts",
-			"import": "./dist/schemas/index.js"
-		},
-		"./standalone": {
-			"types": "./dist/standalone/index.d.ts",
-			"import": "./dist/standalone/index.js"
-		},
-		"./coordination/event-schema": {
-			"types": "./src/cli/coordination/event-schema.d.ts",
-			"import": "./src/cli/coordination/event-schema.mjs"
-		},
-		"./roadmap/conductor-view": {
-			"types": "./src/cli/roadmap/conductor-view.d.ts",
-			"import": "./src/cli/roadmap/conductor-view.mjs"
-		},
-		"./design/scan": {
-			"import": "./src/cli/design/scan.mjs"
-		},
-		"./design/extract-repo": {
-			"import": "./src/cli/design/extract-repo.mjs"
-		},
-		"./design/synthesize": {
-			"import": "./src/cli/design/synthesize.mjs"
-		}
-	},
-	"scripts": {
-		"build": "tsc && node scripts/extract-personas-schema.mjs",
-		"dev": "tsc --watch --preserveWatchOutput",
-		"typecheck": "tsc --noEmit",
-		"lint": "biome check . --diagnostic-level=error",
-		"lint:fix": "biome check --write . --diagnostic-level=error",
-		"clean": "rm -rf dist",
-		"test": "vitest run",
-		"c28:cutover": "node scripts/c28-cutover.mjs",
-		"build-plugin": "node scripts/build-plugin.mjs",
-		"publish-plugin": "node scripts/publish-plugin.mjs",
-		"publish:verdaccio": "node scripts/publish-verdaccio.mjs",
-		"release:verdaccio": "pnpm build && pnpm publish:verdaccio",
-		"ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
-	},
-	"files": [
-		"dist/",
-		"bin/",
-		"src/cli/",
-		"src/cost/",
-		"commands/",
-		"skills/",
-		"agents/",
-		"prompts/",
-		"templates/",
-		"context/",
-		"workflows/",
-		"examples/",
-		"LICENSE",
-		"README.md",
-		"CHANGELOG.md",
-		"!**/__tests__/**",
-		"!**/*.test.*",
-		"!**/*.spec.*",
-		"!**/*.test.d.ts.map",
-		"!**/*.test.js.map"
-	],
-	"keywords": [
-		"ai",
-		"framework",
-		"coding-assistant",
-		"claude-code",
-		"codex",
-		"aperant"
-	],
-	"license": "AGPL-3.0-only",
-	"homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
-	"bugs": {
-		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
-	},
-	"repository": {
-		"type": "git",
-		"url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
-		"directory": "packages/framework"
-	},
-	"engines": {
-		"node": ">=18.0.0"
-	},
-	"publishConfig": {
-		"access": "public"
-	},
-	"dependencies": {
-		"@clack/prompts": "^1.2.0",
-		"proper-lockfile": "^4.1.2",
-		"yaml": "^2.8.3",
-		"zod": "^4.3.6"
-	},
-	"optionalDependencies": {
-		"@babel/parser": "^7.29.2",
-		"@babel/traverse": "^7.29.0",
-		"@google/genai": "^1.50.1",
-		"css-tree": "^3.2.1",
-		"playwright": "^1.59.1"
-	},
-	"devDependencies": {
-		"@vitest/coverage-v8": "^4.1.5"
-	}
-}
+  "name": "@aperant/framework",
+  "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": "Mikalsen AI <hello@mikalsen.ai>",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "framework": "./bin/apt-tools.mjs",
+    "apt-tools": "./bin/apt-tools.mjs",
+    "apt-proof-video": "./bin/apt-proof-video.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./types": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/types/index.js"
+    },
+    "./cost": {
+      "types": "./dist/cost/index.d.ts",
+      "import": "./dist/cost/index.js"
+    },
+    "./mappers": {
+      "types": "./dist/mappers/index.d.ts",
+      "import": "./dist/mappers/index.js"
+    },
+    "./schemas": {
+      "types": "./dist/schemas/index.d.ts",
+      "import": "./dist/schemas/index.js"
+    },
+    "./standalone": {
+      "types": "./dist/standalone/index.d.ts",
+      "import": "./dist/standalone/index.js"
+    },
+    "./driver-sdk": {
+      "types": "./dist/driver-sdk/index.d.ts",
+      "import": "./dist/driver-sdk/index.js"
+    },
+    "./coordination/event-schema": {
+      "types": "./src/cli/coordination/event-schema.d.ts",
+      "import": "./src/cli/coordination/event-schema.mjs"
+    },
+    "./roadmap/conductor-view": {
+      "types": "./src/cli/roadmap/conductor-view.d.ts",
+      "import": "./src/cli/roadmap/conductor-view.mjs"
+    },
+    "./design/scan": {
+      "import": "./src/cli/design/scan.mjs"
+    },
+    "./design/extract-repo": {
+      "import": "./src/cli/design/extract-repo.mjs"
+    },
+    "./design/synthesize": {
+      "import": "./src/cli/design/synthesize.mjs"
+    }
+  },
+  "files": [
+    "dist/",
+    "bin/",
+    "src/cli/",
+    "src/cost/",
+    "commands/",
+    "skills/",
+    "agents/",
+    "prompts/",
+    "templates/",
+    "context/",
+    "workflows/",
+    "drivers/",
+    "examples/",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md",
+    "!**/__tests__/**",
+    "!**/*.test.*",
+    "!**/*.spec.*",
+    "!**/*.test.d.ts.map",
+    "!**/*.test.js.map"
+  ],
+  "keywords": [
+    "ai",
+    "framework",
+    "coding-assistant",
+    "claude-code",
+    "codex",
+    "aperant"
+  ],
+  "license": "AGPL-3.0-only",
+  "homepage": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework#readme",
+  "bugs": {
+    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Mikalsen-AI/aperant-cloud-desktop.git",
+    "directory": "packages/framework"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@clack/prompts": "^1.2.0",
+    "proper-lockfile": "^4.1.2",
+    "yaml": "^2.8.3",
+    "zod": "^4.3.6"
+  },
+  "optionalDependencies": {
+    "@babel/parser": "^7.29.2",
+    "@babel/traverse": "^7.29.0",
+    "@google/genai": "^1.50.1",
+    "css-tree": "^3.2.1",
+    "playwright": "^1.59.1"
+  },
+  "devDependencies": {
+    "@vitest/coverage-v8": "^4.1.5"
+  },
+  "scripts": {
+    "build": "tsc && node scripts/extract-personas-schema.mjs",
+    "dev": "tsc --watch --preserveWatchOutput",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome check . --diagnostic-level=error",
+    "lint:fix": "biome check --write . --diagnostic-level=error",
+    "clean": "rm -rf dist",
+    "test": "vitest run",
+    "c28:cutover": "node scripts/c28-cutover.mjs",
+    "build-plugin": "node scripts/build-plugin.mjs",
+    "publish-plugin": "node scripts/publish-plugin.mjs",
+    "publish:verdaccio": "node scripts/publish-verdaccio.mjs",
+    "release:verdaccio": "pnpm build && pnpm publish:verdaccio",
+    "ship:verdaccio": "npm version patch --no-git-tag-version && pnpm build && pnpm publish:verdaccio"
+  }
+}

package/prompts/planner.md

@@ -6,7 +6,7 @@ You are the **first agent** in an autonomous development process. Your job is to
 
 **MANDATORY**: You MUST call the **Write** tool to create `implementation_plan.json`. Describing the plan in your text response does NOT count — the orchestrator validates that the file exists on disk and passes schema validation. If you do not call the Write tool, the phase will fail.
 
-## TRACK BRANCH — Vertical-slice rubric vs legacy flat schema (Pocock adoption ID-05)
+## TRACK BRANCH — Vertical-slice rubric vs legacy flat schema
 
 Subtask schema depends on track:
 

package/prompts/spec_writer.md

@@ -6,7 +6,7 @@ You are the **Spec Writer Agent** in the Auto-Build spec creation pipeline. Your
 
 **MANDATORY**: You MUST call the **Write** tool to create `spec.md`. Describing the spec in your text response does NOT count — the orchestrator validates that the file exists on disk. If you do not call the Write tool, the phase will fail.
 
-## TRACK BRANCH (Pocock adoption ID-05 — Fast Path Guarantee)
+## TRACK BRANCH
 
 Content format depends on the task's track / complexity:
 

package/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/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/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/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.