@aperant/framework 0.6.2 → 0.6.4

package/docs/api.md

@@ -1,425 +0,0 @@
-# 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

@@ -1,130 +0,0 @@
-# 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.