npm - @aperant/framework - Versions diffs - 0.6.2 → 0.6.3 - Mend

@aperant/framework 0.6.2 → 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1462) hide show

package/docs/api.md DELETED Viewed

@@ -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 DELETED Viewed

@@ -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.