@aperant/framework 0.6.2

package/docs/api.md

@@ -0,0 +1,425 @@
+# Aperant Framework -- API Reference
+
+This document covers the TypeScript types exported by `@aperant/framework`. Plugin authors use these types to build framework adapters that work with the Aperant app.
+
+## Installation
+
+```bash
+npm install @aperant/framework
+```
+
+Import types for plugin development:
+
+```typescript
+import type {
+  FrameworkManifest,
+  StageManifest,
+  ArtifactDeclaration,
+} from "@aperant/framework/types";
+
+import type {
+  AperantContextView,
+  AperantPlanView,
+  AperantProgressView,
+  AperantVerificationView,
+} from "@aperant/framework/types";
+
+import type {
+  ProviderCapabilities,
+  PromptAdaptationHints,
+} from "@aperant/framework/types";
+```
+
+---
+
+## 1. FrameworkManifest
+
+The manifest declares what your framework produces at each lifecycle stage. It is the entry point for plugin registration.
+
+**Source:** `src/types/manifest.ts`
+
+### `FrameworkManifest`
+
+| Field     | Type              | Required | Description                                                      |
+| --------- | ----------------- | -------- | ---------------------------------------------------------------- |
+| `id`      | `string`          | Yes      | Unique framework identifier (e.g., `"aperant"`, `"bmad"`)       |
+| `name`    | `string`          | Yes      | Human-readable name (e.g., `"Aperant Framework"`)                |
+| `version` | `string`          | Yes      | Semver version string                                            |
+| `stages`  | `StageManifest[]` | Yes      | What each lifecycle stage produces                               |
+| `runtime` | `string`          | No       | Path to deterministic CLI tool (e.g., `"./bin/my-tools.mjs"`)   |
+
+### `StageManifest`
+
+| Field       | Type                    | Required | Description                                                   |
+| ----------- | ----------------------- | -------- | ------------------------------------------------------------- |
+| `stage`     | `"context" \| "plan" \| "execute" \| "verify"` | Yes | Which lifecycle stage this declaration covers |
+| `artifacts` | `ArtifactDeclaration[]` | Yes      | Artifacts this stage produces                                 |
+| `mapper`    | `string`                | Yes      | Path to JS module with mapper class export                    |
+
+### `ArtifactDeclaration`
+
+| Field        | Type     | Required | Description                                                            |
+| ------------ | -------- | -------- | ---------------------------------------------------------------------- |
+| `nativeName` | `string` | Yes      | Filename as your framework produces it (e.g., `"CONTEXT.md"`, `"PRD.md"`) |
+| `role`       | `"context" \| "plan" \| "task-list" \| "progress" \| "verification" \| "summary"` | Yes | Semantic role of the artifact |
+| `format`     | `"markdown" \| "json" \| "yaml"` | Yes | File format                                              |
+
+### Complete manifest example
+
+```typescript
+import type { FrameworkManifest } from "@aperant/framework/types";
+
+const manifest: FrameworkManifest = {
+  id: "my-framework",
+  name: "My Framework",
+  version: "1.0.0",
+  stages: [
+    {
+      stage: "context",
+      artifacts: [
+        { nativeName: "context.md", role: "context", format: "markdown" }
+      ],
+      mapper: "./mappers/context-mapper.js"
+    },
+    {
+      stage: "plan",
+      artifacts: [
+        { nativeName: "plan.md", role: "plan", format: "markdown" },
+        { nativeName: "tasks.json", role: "task-list", format: "json" }
+      ],
+      mapper: "./mappers/plan-mapper.js"
+    },
+    {
+      stage: "execute",
+      artifacts: [
+        { nativeName: "progress.json", role: "progress", format: "json" }
+      ],
+      mapper: "./mappers/progress-mapper.js"
+    },
+    {
+      stage: "verify",
+      artifacts: [
+        { nativeName: "verification.json", role: "verification", format: "json" }
+      ],
+      mapper: "./mappers/verify-mapper.js"
+    }
+  ],
+  runtime: "./bin/my-tools.mjs"
+};
+```
+
+---
+
+## 2. UI Shapes
+
+The Aperant app renders framework output through 4 normalized UI shapes. Your mapper translates your native artifacts into these shapes.
+
+**Source:** `src/types/ui-shapes.ts`
+
+### `AperantContextView`
+
+Rendered as a **decisions table** in the Aperant UI.
+
+| Field           | Type                       | Description                                       |
+| --------------- | -------------------------- | ------------------------------------------------- |
+| `frameworkId`   | `string`                   | Framework that produced this context               |
+| `title`         | `string`                   | Project or task name                               |
+| `scope`         | `string`                   | Scope description                                  |
+| `decisions`     | `ContextDecision[]`        | Locked decisions                                   |
+| `deferredItems` | `string[]`                 | Items explicitly deferred to later                 |
+| `openQuestions` | `string[]`                 | Unresolved items                                   |
+| `metadata`      | `Record<string, unknown>`  | Framework-specific data (UI shows under "View raw") |
+
+**`ContextDecision`:**
+
+| Field       | Type     | Required | Description           |
+| ----------- | -------- | -------- | --------------------- |
+| `id`        | `string` | Yes      | e.g., `"D-01"`       |
+| `summary`   | `string` | Yes      | What was decided      |
+| `rationale` | `string` | No       | Why it was decided    |
+
+### `AperantPlanView`
+
+Rendered as a **Kanban board** in the Aperant UI.
+
+| Field         | Type                       | Description                          |
+| ------------- | -------------------------- | ------------------------------------ |
+| `frameworkId` | `string`                   | Framework that produced this plan    |
+| `title`       | `string`                   | Plan title                           |
+| `totalTasks`  | `number`                   | Total number of tasks                |
+| `waves`       | `PlanWave[]`               | Tasks grouped by wave for parallel execution |
+| `metadata`    | `Record<string, unknown>`  | Framework-specific data              |
+
+**`PlanWave`:**
+
+| Field        | Type         | Description                |
+| ------------ | ------------ | -------------------------- |
+| `waveNumber` | `number`     | Wave sequence number       |
+| `tasks`      | `PlanTask[]` | Tasks in this wave         |
+
+**`PlanTask`:**
+
+| Field         | Type       | Required | Description                                                   |
+| ------------- | ---------- | -------- | ------------------------------------------------------------- |
+| `id`          | `string`   | Yes      | Task identifier                                                |
+| `name`        | `string`   | Yes      | Task name                                                      |
+| `status`      | `"pending" \| "in-progress" \| "completed" \| "failed" \| "skipped"` | Yes | Current status |
+| `files`       | `string[]` | Yes      | Files this task modifies                                       |
+| `dependsOn`   | `string[]` | Yes      | Task IDs this depends on                                       |
+| `description` | `string`   | No       | Brief description of what the task does                        |
+
+### `AperantProgressView`
+
+Rendered as a **progress bar with activity feed** in the Aperant UI.
+
+| Field            | Type                          | Description                            |
+| ---------------- | ----------------------------- | -------------------------------------- |
+| `frameworkId`    | `string`                      | Framework that produced this progress  |
+| `progressPercent`| `number`                      | Overall progress 0--100                |
+| `totalTasks`     | `number`                      | Total task count                       |
+| `completedTasks` | `number`                      | Completed task count                   |
+| `failedTasks`    | `number`                      | Failed task count                      |
+| `currentTask`    | `ProgressCurrentTask \| null` | Currently executing task               |
+| `recentActivity` | `ProgressActivity[]`          | Recent activity (newest first)         |
+| `metadata`       | `Record<string, unknown>`     | Framework-specific data                |
+
+**`ProgressCurrentTask`:**
+
+| Field           | Type     | Required | Description                              |
+| --------------- | -------- | -------- | ---------------------------------------- |
+| `id`            | `string` | Yes      | Task identifier                           |
+| `name`          | `string` | Yes      | Task name                                 |
+| `startedAt`     | `string` | Yes      | ISO 8601 timestamp                        |
+| `statusMessage` | `string` | No       | What the agent is currently doing         |
+
+**`ProgressActivity`:**
+
+| Field        | Type     | Required | Description                                                                              |
+| ------------ | -------- | -------- | ---------------------------------------------------------------------------------------- |
+| `timestamp`  | `string` | Yes      | ISO 8601 timestamp                                                                        |
+| `type`       | `"task-started" \| "task-completed" \| "task-failed" \| "commit" \| "retry" \| "phase-transition"` | Yes | Activity type |
+| `message`    | `string` | Yes      | Human-readable description                                                                |
+| `commitHash` | `string` | No       | Git commit hash (when `type === "commit"`)                                                |
+
+### `AperantVerificationView`
+
+Rendered as a **verification dashboard** in the Aperant UI.
+
+| Field          | Type                       | Description                              |
+| -------------- | -------------------------- | ---------------------------------------- |
+| `frameworkId`  | `string`                   | Framework that produced this verification |
+| `status`       | `"passed" \| "failed" \| "partial" \| "not-run"` | Overall verification status |
+| `score`        | `number \| null`           | Overall score 0--100 (null if not scored) |
+| `dimensions`   | `VerificationDimension[]`  | Individual scored dimensions              |
+| `gaps`         | `VerificationGap[]`        | Gaps found during verification            |
+| `antiPatterns` | `string[]`                 | Anti-patterns detected                    |
+| `metadata`     | `Record<string, unknown>`  | Framework-specific data                   |
+
+**`VerificationDimension`:**
+
+| Field       | Type     | Required | Description                                      |
+| ----------- | -------- | -------- | ------------------------------------------------ |
+| `name`      | `string` | Yes      | e.g., `"correctness"`, `"completeness"`, `"code-quality"`, `"test-coverage"` |
+| `score`     | `number` | Yes      | Score 0--100                                     |
+| `threshold` | `number` | Yes      | Minimum acceptable score                         |
+| `passed`    | `boolean`| Yes      | Whether score meets threshold                    |
+| `details`   | `string` | No       | Additional context                               |
+
+**`VerificationGap`:**
+
+| Field       | Type       | Required | Description                            |
+| ----------- | ---------- | -------- | -------------------------------------- |
+| `truth`     | `string`   | Yes      | What should be true but is not         |
+| `reason`    | `string`   | Yes      | Why it failed                          |
+| `severity`  | `"blocker" \| "major" \| "minor"` | Yes | Severity level          |
+| `artifacts` | `string[]` | Yes      | Files involved                         |
+
+---
+
+## 3. ProviderCapabilities
+
+Enables skills to adapt prompting strategy per LLM provider without provider-specific code branches.
+
+**Source:** `src/types/provider-capabilities.ts`
+
+### `ProviderCapabilities`
+
+| Field                        | Type                  | Required | Description                                            |
+| ---------------------------- | --------------------- | -------- | ------------------------------------------------------ |
+| `providerId`                 | `string`              | Yes      | Provider identifier (e.g., `"anthropic"`, `"openai"`)  |
+| `modelId`                    | `string`              | Yes      | Model identifier (e.g., `"claude-opus-4-6"`, `"gpt-4o"`) |
+| `supportsThinking`           | `boolean`             | Yes      | Extended thinking / chain-of-thought support            |
+| `supportsStructuredOutput`   | `boolean`             | Yes      | JSON mode / structured output support                   |
+| `toolCallingStyle`           | `"parallel" \| "sequential" \| "none"` | Yes | How the model handles tool calling     |
+| `maxContextTokens`           | `number`              | Yes      | Maximum context window size in tokens                   |
+| `maxOutputTokens`            | `number`              | Yes      | Maximum output tokens per response                      |
+| `supportsVision`             | `boolean`             | Yes      | Image/vision input support                              |
+| `supportsStreaming`          | `boolean`             | Yes      | Streaming support                                       |
+| `costPerMillionInputTokens`  | `number`              | No       | Cost per million input tokens (USD)                     |
+| `costPerMillionOutputTokens` | `number`              | No       | Cost per million output tokens (USD)                    |
+| `promptHints`                | `PromptAdaptationHints` | Yes    | Provider-specific prompt adaptation hints               |
+
+### `PromptAdaptationHints`
+
+| Field                          | Type                          | Description                                              |
+| ------------------------------ | ----------------------------- | -------------------------------------------------------- |
+| `preferredStructuredFormat`    | `"json" \| "xml" \| "yaml"`  | Preferred structured data format (`"xml"` for Claude, `"json"` for GPT) |
+| `useSystemPrompt`             | `boolean`                     | Whether to use system prompt                              |
+| `needsExplicitReasoning`      | `boolean`                     | Whether to include "think step by step" (unnecessary for thinking models) |
+| `recommendedMaxPromptTokens`  | `number`                      | Max recommended prompt length before quality degrades     |
+
+### Example: Claude Opus
+
+```typescript
+import type { ProviderCapabilities } from "@aperant/framework/types";
+
+const claude: ProviderCapabilities = {
+  providerId: "anthropic",
+  modelId: "claude-opus-4-6",
+  supportsThinking: true,
+  supportsStructuredOutput: true,
+  toolCallingStyle: "parallel",
+  maxContextTokens: 200000,
+  maxOutputTokens: 32000,
+  supportsVision: true,
+  supportsStreaming: true,
+  costPerMillionInputTokens: 15,
+  costPerMillionOutputTokens: 75,
+  promptHints: {
+    preferredStructuredFormat: "xml",
+    useSystemPrompt: true,
+    needsExplicitReasoning: false,
+    recommendedMaxPromptTokens: 150000,
+  }
+};
+```
+
+### Example: GPT-4o
+
+```typescript
+const gpt4o: ProviderCapabilities = {
+  providerId: "openai",
+  modelId: "gpt-4o",
+  supportsThinking: false,
+  supportsStructuredOutput: true,
+  toolCallingStyle: "parallel",
+  maxContextTokens: 128000,
+  maxOutputTokens: 16384,
+  supportsVision: true,
+  supportsStreaming: true,
+  costPerMillionInputTokens: 2.5,
+  costPerMillionOutputTokens: 10,
+  promptHints: {
+    preferredStructuredFormat: "json",
+    useSystemPrompt: true,
+    needsExplicitReasoning: true,
+    recommendedMaxPromptTokens: 100000,
+  }
+};
+```
+
+---
+
+## 4. Writing a Mapper
+
+A mapper translates your framework's native artifacts into the 4 Aperant UI shapes. Each mapper is a class with 4 methods.
+
+### How it works
+
+1. When Aperant loads a framework, it reads the manifest to find mapper paths for each stage.
+2. For each stage, Aperant collects the native artifact files and passes them as a `Map<filename, fileContent>` to the corresponding mapper method.
+3. The mapper parses the native format and returns the normalized UI shape.
+4. Aperant renders the UI shape in its standard components (decisions table, Kanban board, progress bar, verification dashboard).
+
+### Mapper skeleton
+
+```typescript
+import type {
+  AperantContextView,
+  AperantPlanView,
+  AperantProgressView,
+  AperantVerificationView,
+} from "@aperant/framework/types";
+
+export class MyFrameworkMapper {
+  toContextView(artifacts: Map<string, string>): AperantContextView {
+    const contextFile = artifacts.get("my-context.md");
+    // Parse your native format...
+    return {
+      frameworkId: "my-framework",
+      title: "Project Name",
+      scope: "Scope description",
+      decisions: [],
+      deferredItems: [],
+      openQuestions: [],
+      metadata: {},
+    };
+  }
+
+  toPlanView(artifacts: Map<string, string>): AperantPlanView {
+    const planFile = artifacts.get("my-plan.json");
+    // Parse your native format...
+    return {
+      frameworkId: "my-framework",
+      title: "Implementation Plan",
+      totalTasks: 0,
+      waves: [],
+      metadata: {},
+    };
+  }
+
+  toProgressView(artifacts: Map<string, string>): AperantProgressView {
+    const progressFile = artifacts.get("my-progress.json");
+    // Parse your native format...
+    return {
+      frameworkId: "my-framework",
+      progressPercent: 0,
+      totalTasks: 0,
+      completedTasks: 0,
+      failedTasks: 0,
+      currentTask: null,
+      recentActivity: [],
+      metadata: {},
+    };
+  }
+
+  toVerificationView(artifacts: Map<string, string>): AperantVerificationView {
+    const qaFile = artifacts.get("my-qa.json");
+    // Parse your native format...
+    return {
+      frameworkId: "my-framework",
+      status: "not-run",
+      score: null,
+      dimensions: [],
+      gaps: [],
+      antiPatterns: [],
+      metadata: {},
+    };
+  }
+}
+```
+
+### Reference implementation
+
+See `src/mappers/aperant-mapper.ts` for the complete Aperant Framework mapper. It demonstrates:
+
+- Parsing multiple native artifacts per stage
+- Graceful handling of missing or malformed files
+- Mapping native status values to normalized enums
+- Populating the `metadata` field with raw data for power users
+
+### Registering your mapper
+
+In your manifest, point each stage's `mapper` field to the file containing your mapper class:
+
+```typescript
+{
+  stage: "plan",
+  artifacts: [
+    { nativeName: "my-plan.json", role: "plan", format: "json" }
+  ],
+  mapper: "./mappers/my-plan-mapper.js"  // Compiled JS path
+}
+```
+
+The mapper file must export the class as a named or default export. Aperant instantiates it and calls the appropriate method based on the stage.

package/docs/artifact-lifecycle.md

@@ -0,0 +1,130 @@
+# Artifact lifecycle
+
+Authoritative reference for how the framework classifies `.aperant/` state, keeps producer commits self-contained, and runs the post-merge closer. Delivered by C56 (absorbing C59) in framework 0.5.0.
+
+## The problem C56 solved
+
+Before 0.5.0, `/apt:ship` exited the moment `gh pr create` returned. Merge happened on GitHub hours/days later with no agent present to run the closer side. Four classes of artifact leaked:
+
+- **Roadmap state drift** — phases flipped to `in-progress` during plan/execute never auto-flipped to `completed` on merge. Users had to remember to run `apt-tools roadmap set-phase-status` by hand.
+- **Orphaned workflow files** — `.aperant/workflows/pr-{N}.json` persisted after `workflow destroy` marked state internally.
+- **Stale per-PR config** — `config.pr_review.authorship_overrides['pr-{N}']` entries lingered forever.
+- **Task artifact dir accumulation** — `.aperant/tasks/{id}/` never got GC'd.
+
+Root cause: the framework had **producers** (plan / execute / review / ship / pr-review — write artifacts while an agent is present) but no **closers** that run post-merge. C56 introduced the missing closer and wired the state machine, classification contract, and per-subtask drift audit that prevent leaks from accumulating in the first place.
+
+## Classification contract
+
+The single source of truth is `packages/framework/src/cli/artifacts/classification.mjs`. Every `.aperant/` subpath is either **committable** (belongs in git; changes must land in the task's PR) or **ephemeral** (gitignored; per-agent / per-task / per-round state).
+
+| Path | Classification | Rationale |
+|------|---------------|-----------|
+| `.aperant/roadmap/**/milestones.json` | committable | Shared team roadmap state; rolled into `ROADMAP.md` render |
+| `.aperant/roadmap/**/phases/*.json` | committable | Per-phase canonical record |
+| `.aperant/roadmap/**/ROADMAP.md` | committable | Human-readable rendered view |
+| `.aperant/context/notes/**` | committable | Locked discuss-phase decisions |
+| `.aperant/decisions/**` | committable | Decision ledger entries |
+| `.aperant/features/**` | committable | Feature registry (shared inventory) |
+| `.aperant/project.json` | committable | PROJECT.md-backed product context |
+| `.aperant/config.json` | committable | Team-level framework preferences |
+| `.aperant/state.json` | ephemeral | Per-agent active task map |
+| `.aperant/events/**` | ephemeral | Append-only event log |
+| `.aperant/team-status/**` | ephemeral | Per-agent liveness (TTL-expired) |
+| `.aperant/workflows/**` | ephemeral | Per-review workflow gate state |
+| `.aperant/tasks/**` | ephemeral | Per-task artifacts (spec/plan/progress/QA/review) |
+| `.aperant/pr-reviews/**` | ephemeral | Local pr-review coordination (state, snapshots, rounds, scratch). See "PR-review artifacts are local-only" below. |
+| `.aperant/proof/**` | ephemeral | Verification evidence (screenshots, videos) |
+| `.aperant/logs/**` | ephemeral | Runtime logs |
+
+Any path not in the table falls into the **unknown** bucket and triggers a hard-stop in the audit and drift-check flows. This is the planner-gap signal: if your subtask touched a new `.aperant/` subpath, extend the table and ship the extension alongside the feature.
+
+## PR-review artifacts are local-only
+
+`/apt:pr-review` writes everything under `.aperant/pr-reviews/` — `pr-{N}/pr-state.json`, `pr-{N}/rounds/{R}/pr-state-snapshot.json`, `pr-{N}-{HASH}/findings/`, etc. **All of it is ephemeral.** Three responsibilities are separated explicitly:
+
+| Layer | Owns | Lives where |
+|------|------|------|
+| GitHub PR API | PR-level audit trail (comments, commits, reviews, merge state) | github.com |
+| Local framework state (`.aperant/`) | Coordination — *is `/apt:pr-review` running, what round, who has the lock* | `.aperant/pr-reviews/**` (gitignored) |
+| Aperant the app | Cross-machine AI performance telemetry, team insights, dashboards | Separate product |
+
+The framework historically classified `pr-state.json` and `pr-state-snapshot.json` as committable — a re-evaluation in 2026-04 reversed that for three reasons:
+
+1. **PID leak.** `pr-state.json` stores `lock.owner: "agent-{pid}-{ts}"` — same security reasoning that classifies `state.json` ephemeral.
+2. **Empirical never-honored.** Across the framework's own dev history we found 9 prior merged PRs whose state files accumulated locally and never made it into git. The `git add -f` self-staging without an automatic commit step was a designed-in leak.
+3. **Snapshot fields are reconstructible.** `head_sha_by_round` ↔ `gh pr view --json commits,timelineItems`. `comment_timeline` ↔ `gh api .../comments`. `superseded_findings` ↔ `findings[N] − findings[N+1]`. Optional fields were empty in 9/9 snapshots inspected. The snapshot is a denormalized cache of GitHub data — caches don't belong in git.
+
+**For richer cross-machine traceability** (which AI flagged what across rounds, drift over time, model A vs model B), use Aperant the app. That's where AI-performance telemetry belongs — not in every consumer's git repo.
+
+### Auto-prune on merge
+
+`apt-tools pr-review close-round` calls `gh pr view`; on `MERGED` or `CLOSED` it now `rm -rf .aperant/pr-reviews/pr-{N}/` in addition to the existing workflow + config-override cleanup. This is **disk hygiene** — once the files are EPHEMERAL the gitignore prevents the leak; the prune is so `git status` stops showing accumulated cruft from prior reviews.
+
+## The `shipped-pending-merge` lifecycle waypoint
+
+Tasks flow `planning → executing → verifying → reviewing → shipped-pending-merge → completed`. Before 0.5.0, `/apt:ship` jumped straight from `reviewing` to `completed` — producing landed-work claims about unlanded code.
+
+- **Entry:** `/apt:ship` step 8 calls `task update --lifecycle-phase shipped-pending-merge` after `gh pr create` succeeds and the `pr_url` is recorded on the task record.
+- **Exit:** `/apt:close-task` polls `gh pr view` for the PR's merge state. On `MERGED`, it flips the task to `completed` and triggers the full closer sequence: phase flip, narrator spawn (if phase-linked), worktree GC, per-PR config strip, task archive per retention policy.
+- **Stuck states:** tasks can stay in `shipped-pending-merge` indefinitely without consequence. Running `/apt:close-task --all` batch-resolves every task whose PR has merged since last invocation.
+- **`OPEN` / `CLOSED` (not merged):** skipped by `close-task`; the task stays in the waypoint. `CLOSED (not merged)` tasks should be closed manually via `task close --verdict rejected` — automated rejection flip is out of scope for C56.
+
+## Self-staging contract
+
+State-mutating `apt-tools` CLI commands automatically `git add -f` their committable file writes so the caller's next commit picks them up. No more "I ran `roadmap set-phase-status` and forgot to stage the change" drift class.
+
+Wired commands (as of 0.5.0):
+
+- `roadmap add-milestone` / `add-phase` / `set-phase-status` / `delete-phase` / `delete-milestone` / `render`
+
+Not wired (intentional — state writes are ephemeral):
+
+- `task create` / `update` / `close` / `move` — writes go to `state.json` (ephemeral).
+- `workflow create` / `advance` / `destroy` — writes go to `workflows/**` (ephemeral).
+- `event append`, `lock acquire` / `release` — writes to events/ or state.json.
+- `pr-review init-pr` / `detect-authorship` / `record-comment` / `close-round` — writes go to `pr-reviews/**` (ephemeral; see below).
+
+The self-staging helper is best-effort: if the caller's cwd isn't a git working tree (e.g. inside a sandbox), the write happens but staging is a silent no-op. Callers shouldn't assume staging succeeded without verifying with `git status`.
+
+## Per-subtask drift check
+
+`/apt:execute` §3e-drift runs `apt-tools audit pending-artifacts . --stage` after every atomic subtask commit.
+
+- `clean` → next subtask.
+- `committable[]` non-empty after `--stage` → the auditor already staged them; amend into the subtask commit (`git commit --amend --no-edit`) or emit a follow-on `chore(aperant): capture {subtask.id} artifact drift` commit.
+- `unknown[]` non-empty → HARD STOP. Route to `{task_dir}/execution-decisions.md` as decision class `classification-gap`. Either extend `classification.mjs` inline (if the subtask is a framework change) or open a follow-up task.
+
+`/apt:ship` §0.5 runs the same audit once more as a final safety net before `gh pr create`.
+
+## Authorship override migration window
+
+A3 moved pr-review authorship overrides from global `.aperant/config.json` to per-PR `.aperant/pr-reviews/pr-{N}/pr-state.json`. Precedence at read:
+
+1. **`pr-state.json.authorship_override`** (canonical, post-0.5.0 writes go here).
+2. **`config.pr_review.authorship_overrides['pr-{N}']`** (legacy, deprecated). `init-pr` auto-promotes legacy entries to `pr-state.json` on first call and logs a deprecation warning. Will be removed in 0.6.
+3. **`config.pr_review.authorship_override`** (global default, unchanged).
+4. **`null`** — no override; run detection.
+
+Backwards compatibility is preserved for one release. Downstream agents reading authorship state should call `resolveAuthorshipOverride()` (exported from `pr-review.mjs`), never read the config key directly.
+
+## Retention model
+
+- **Task artifact dirs** — `apt-tools task prune --older-than <duration>` (accepts `30d`, `6w`, `1y`). Default off; user-opt-in retention. Refuses to prune tasks still in `active_tasks[*]`.
+- **Workflow files** — `apt-tools workflow destroy --archive` moves `.aperant/workflows/{id}.json` into `.aperant/workflows/archive/{id}.json`. Archive itself has no retention policy today (out of scope for C56).
+- **pr-reviews rounds** — no retention, intentionally. Per-round findings + fixer transcripts are reference material for authorship / rejection disputes.
+
+## Extension checklist
+
+When you add a new `.aperant/` subpath:
+
+1. Pick committable or ephemeral. Default to ephemeral unless the state is **shared across agents** and **part of the task's PR**.
+2. Add an entry to the classification table in `packages/framework/src/cli/artifacts/classification.mjs`.
+3. Add a row to the table above in this document.
+4. If writing from a CLI command that already self-stages, your writes are automatically handled. If writing from a new command, either self-stage explicitly via `selfStageCommittableWrites(root, paths)` or mark the path ephemeral.
+5. Run `apt-tools audit pending-artifacts .` and confirm your new path no longer shows up as `unknown`.
+
+## Cross-references
+
+- Skill contracts: `/apt:ship` §0.5 / §6 / §8, `/apt:execute` §3e-drift, `/apt:close-task` §2.5.
+- CLI contracts: `packages/framework/src/cli/commands/task.mjs` (close, update, prune, close-merged), `packages/framework/src/cli/commands/pr-review.mjs` (close-round cleanup, authorship migration), `packages/framework/src/cli/commands/audit.mjs` (pending-artifacts), `packages/framework/src/cli/commands/workflow.mjs` (destroy --archive).
+- Docs coherence: [`docs-coherence.md`](docs-coherence.md) links here from the "How the planner enforces this" section.