@aperant/framework 0.6.2

package/dist/capture/types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Capture Adapter Types
+ *
+ * Platform-agnostic interface for recording video/screenshots from applications.
+ * Adapters implement this interface for different capture mechanisms:
+ * - CDP (Chrome DevTools Protocol) — Electron, Tauri, browsers, React Native
+ * - Playwright — web apps via browser automation
+ * - ADB — Android devices and emulators
+ * - Simulator — iOS simulator
+ * - Manual — user provides their own recording
+ */
+/** Configuration for starting a capture session */
+export interface CaptureConfig {
+    /** Output file path for the recording */
+    outputPath: string;
+    /** Maximum duration in seconds (default: 60) */
+    duration?: number;
+    /** Target frames per second (default: 2 for efficiency, max ~15 via CDP) */
+    fps?: number;
+    /** Max width in pixels (default: 1280) */
+    maxWidth?: number;
+    /** Max height in pixels (default: 720) */
+    maxHeight?: number;
+    /** Image format for frames (default: 'jpeg') */
+    format?: 'jpeg' | 'png';
+    /** JPEG quality 0-100 (default: 80) */
+    quality?: number;
+}
+/** Configuration specific to CDP-based capture */
+export interface CDPCaptureConfig extends CaptureConfig {
+    /** CDP debug port (default: 9222) */
+    port?: number;
+    /** CDP host (default: 'localhost') */
+    host?: string;
+    /** Target page index or ID (default: first page) */
+    targetId?: string;
+}
+/** Result from a completed capture session */
+export interface CaptureResult {
+    /** Whether capture succeeded */
+    success: boolean;
+    /** Output file path */
+    outputPath: string;
+    /** Number of frames captured */
+    frameCount: number;
+    /** Actual duration in seconds */
+    duration: number;
+    /** File size in bytes */
+    fileSizeBytes: number;
+    /** Error message if failed */
+    error?: string;
+    /** Individual frame paths (if saved as frame sequence) */
+    framePaths?: string[];
+}
+/** Metadata about a single captured frame */
+export interface CaptureFrame {
+    /** Frame index (0-based) */
+    index: number;
+    /** Timestamp offset from start in milliseconds */
+    timestampMs: number;
+    /** Base64-encoded image data */
+    data: string;
+    /** Image format */
+    format: 'jpeg' | 'png';
+    /** Frame dimensions */
+    width?: number;
+    height?: number;
+}
+/**
+ * Platform-agnostic capture adapter interface.
+ *
+ * Lifecycle: create → start → (frames arrive) → stop → getResult
+ */
+export interface CaptureAdapter {
+    /** Human-readable name of this adapter (e.g., 'cdp', 'playwright', 'adb') */
+    readonly name: string;
+    /** Check if this adapter can capture in the current environment */
+    isAvailable(): Promise<boolean>;
+    /** Start capturing. Returns when capture is actively recording. */
+    start(config: CaptureConfig): Promise<void>;
+    /** Stop capturing and finalize output. */
+    stop(): Promise<CaptureResult>;
+    /** Optional: callback for each frame as it arrives (for live preview) */
+    onFrame?: (frame: CaptureFrame) => void;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/capture/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/capture/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,mDAAmD;AACnD,MAAM,WAAW,aAAa;IAC7B,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4EAA4E;IAC5E,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0CAA0C;IAC1C,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,gDAAgD;IAChD,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,CAAA;IACvB,uCAAuC;IACvC,OAAO,CAAC,EAAE,MAAM,CAAA;CAChB;AAED,kDAAkD;AAClD,MAAM,WAAW,gBAAiB,SAAQ,aAAa;IACtD,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,sCAAsC;IACtC,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,oDAAoD;IACpD,QAAQ,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC7B,gCAAgC;IAChC,OAAO,EAAE,OAAO,CAAA;IAChB,uBAAuB;IACvB,UAAU,EAAE,MAAM,CAAA;IAClB,gCAAgC;IAChC,UAAU,EAAE,MAAM,CAAA;IAClB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAA;IAChB,yBAAyB;IACzB,aAAa,EAAE,MAAM,CAAA;IACrB,8BAA8B;IAC9B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,0DAA0D;IAC1D,UAAU,CAAC,EAAE,MAAM,EAAE,CAAA;CACrB;AAED,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC5B,4BAA4B;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAA;IACnB,gCAAgC;IAChC,IAAI,EAAE,MAAM,CAAA;IACZ,mBAAmB;IACnB,MAAM,EAAE,MAAM,GAAG,KAAK,CAAA;IACtB,uBAAuB;IACvB,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IAErB,mEAAmE;IACnE,WAAW,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IAE/B,mEAAmE;IACnE,KAAK,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAE3C,0CAA0C;IAC1C,IAAI,IAAI,OAAO,CAAC,aAAa,CAAC,CAAA;IAE9B,yEAAyE;IACzE,OAAO,CAAC,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAA;CACvC"}

package/dist/capture/types.js

@@ -0,0 +1,13 @@
+/**
+ * Capture Adapter Types
+ *
+ * Platform-agnostic interface for recording video/screenshots from applications.
+ * Adapters implement this interface for different capture mechanisms:
+ * - CDP (Chrome DevTools Protocol) — Electron, Tauri, browsers, React Native
+ * - Playwright — web apps via browser automation
+ * - ADB — Android devices and emulators
+ * - Simulator — iOS simulator
+ * - Manual — user provides their own recording
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/capture/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/capture/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}

package/dist/cli/artifacts/classification.d.mts

@@ -0,0 +1,72 @@
+/**
+ * Return the ordered list of committable globs. Deterministic. Frozen array
+ * (consumers should not mutate it).
+ *
+ * @returns {readonly string[]}
+ * @internal
+ */
+export function listCommittableGlobs(): readonly string[];
+/**
+ * Return the ordered list of ephemeral globs. Deterministic. Frozen array.
+ *
+ * @returns {readonly string[]}
+ * @internal
+ */
+export function listEphemeralGlobs(): readonly string[];
+/**
+ * Classify a repo-relative path.
+ *
+ *   - Returns 'committable' or 'ephemeral' when a rule matches.
+ *   - Returns `null` when the path is outside `.aperant/` OR when it's under
+ *     `.aperant/` but unmatched (unknown → forces the caller to pick).
+ *
+ * The glob matcher is the same one used by task outputs (`**` matches any
+ * sequence incl. `/`, `*` matches non-`/`). No negation, no braces.
+ *
+ * @param {string} relPath path relative to the repo root (e.g.
+ *   `.aperant/roadmap/framework/milestones.json`). Leading `./` stripped.
+ * @param {{}} [_opts] reserved for future options (no-op today).
+ * @returns {'committable' | 'ephemeral' | null}
+ * @internal
+ */
+export function classifyArtifactPath(relPath: string, _opts?: {}): "committable" | "ephemeral" | null;
+/**
+ * Detailed variant — returns `{ class, pattern, why }` or `null`. Intended for
+ * diagnostics (unknown-path reports, audit output).
+ *
+ * @param {string} relPath
+ * @returns {{ class: string, pattern: string, why: string } | null}
+ * @internal
+ */
+export function classifyArtifactPathDetailed(relPath: string): {
+    class: string;
+    pattern: string;
+    why: string;
+} | null;
+/**
+ * Filter: return paths that classify committable. Drops unknown/null + ephemeral.
+ *
+ * @param {string[]} paths
+ * @returns {string[]} filtered subset (preserves input order; no dedupe).
+ * @internal
+ */
+export function filterCommittable(paths: string[]): string[];
+/**
+ * Filter: return paths that classify ephemeral.
+ *
+ * @param {string[]} paths
+ * @returns {string[]} filtered subset (preserves input order; no dedupe).
+ * @internal
+ */
+export function filterEphemeral(paths: string[]): string[];
+/**
+ * Artifact classification codomain. Frozen enum-ish object; never add values
+ * without updating every consumer of the classifier return shape.
+ *
+ * @internal
+ */
+export const ARTIFACT_CLASS: Readonly<{
+    COMMITTABLE: "committable";
+    EPHEMERAL: "ephemeral";
+}>;
+//# sourceMappingURL=classification.d.mts.map

package/dist/cli/artifacts/classification.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.d.mts","sourceRoot":"","sources":["../../../src/cli/artifacts/classification.mjs"],"names":[],"mappings":"AAuRA;;;;;;GAMG;AACH,wCAHa,SAAS,MAAM,EAAE,CAO7B;AAED;;;;;GAKG;AACH,sCAHa,SAAS,MAAM,EAAE,CAO7B;AAED;;;;;;;;;;;;;;;GAeG;AACH,8CANW,MAAM,UAEN,EAAE,GACA,aAAa,GAAG,WAAW,GAAG,IAAI,CAW9C;AAED;;;;;;;GAOG;AACH,sDAJW,MAAM,GACJ;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAalE;AAED;;;;;;GAMG;AACH,yCAJW,MAAM,EAAE,GACN,MAAM,EAAE,CAMpB;AAED;;;;;;GAMG;AACH,uCAJW,MAAM,EAAE,GACN,MAAM,EAAE,CAMpB;AA1VD;;;;;GAKG;AACH;;;GAGE"}

package/dist/cli/artifacts/classification.mjs

@@ -0,0 +1,385 @@
+/**
+ * @internal
+ * classification.mjs — the ground-truth contract for which `.aperant/`
+ * subpaths are committable (belong in version control + reviewable) vs
+ * ephemeral (runtime/coordination/transient) (C56 B4).
+ *
+ * This module is the single source of truth consumed by:
+ *   - `apt-tools audit pending-artifacts` (bucket committable/ephemeral/unknown)
+ *   - self-staging helper (`git add -f` committable writes)
+ *   - roadmap/task/pr-review CLIs (call self-staging after mutations)
+ *   - future auditors (e.g. retention prune gates)
+ *
+ * Classification table — see spec.md §B4. Closed-world: any `.aperant/*`
+ * path that doesn't hit a rule returns `null`, forcing the caller to pick
+ * explicitly. Paths outside `.aperant/` also return `null`.
+ *
+ * Design constraints:
+ *   - Deterministic iteration order (array-of-rules, not object map).
+ *   - No I/O — pure string classification, safe to call from tight loops.
+ *   - Frozen exports; callers can't mutate the rule set at runtime.
+ *   - Glob matcher reused from outputs-guard.mjs so the dialect matches the
+ *     task outputs allowlist exactly (important: self-staging checks BOTH).
+ */
+import { globToRegex } from '../task/outputs-guard.mjs';
+/**
+ * Artifact classification codomain. Frozen enum-ish object; never add values
+ * without updating every consumer of the classifier return shape.
+ *
+ * @internal
+ */
+export const ARTIFACT_CLASS = Object.freeze({
+    COMMITTABLE: 'committable',
+    EPHEMERAL: 'ephemeral',
+});
+// Rule table. Ordered — first match wins, so more-specific rules must come
+// before their more-general parents (e.g. the round-snapshot committable rule
+// is listed before the generic pr-reviews rounds ephemeral rule).
+//
+// Each rule: { pattern: glob string, class: 'committable' | 'ephemeral', why: string }.
+// `why` is kept for documentation & diagnostic output — the classifier returns
+// only the class; callers needing the reason use `classifyArtifactPathDetailed`.
+const RULES = Object.freeze([
+    // ── Committable: long-term reviewable state ───────────────────────────
+    {
+        pattern: '.aperant/roadmap/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Roadmap — reviewable long-term state; covered by roadmap sync helper.',
+    },
+    {
+        pattern: '.aperant/context/notes/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Decision ledger the team consumes.',
+    },
+    {
+        pattern: '.aperant/decisions/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Roundtable outcomes, stress-test reports.',
+    },
+    {
+        pattern: '.aperant/features/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Features registry (docs-coherence policy).',
+    },
+    {
+        pattern: '.aperant/seeds.json',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Seeds register (cross-scope thematic initiatives).',
+    },
+    {
+        pattern: '.aperant/project.json',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Product context.',
+    },
+    {
+        pattern: '.aperant/project_index.json',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Derived-but-reviewable feature-surface index (docs-coherence).',
+    },
+    {
+        pattern: '.aperant/axes.json',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Product taxonomy (axes) — reviewable project metadata.',
+    },
+    {
+        pattern: '.aperant/config.json',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Durable project preferences (per-PR keys migrate out via A3).',
+    },
+    {
+        pattern: '.aperant/rationalizations/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Per-model failure-mode tables (reviewed artifact).',
+    },
+    {
+        pattern: '.aperant/templates/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Shared templates (rationalization skeletons, etc.).',
+    },
+    {
+        pattern: '.aperant/prompts/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Agent prompt templates (versioned + reviewable).',
+    },
+    {
+        pattern: '.aperant/benchmarks/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Benchmark definitions + eval suites (reviewable).',
+    },
+    {
+        pattern: '.aperant/stress-tests/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Planner stress-test fixtures (reviewable).',
+    },
+    {
+        pattern: '.aperant/roundtables/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Structured debate outputs (reviewable decision records).',
+    },
+    {
+        pattern: '.aperant/context/installed/**',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Installed-context snapshots (reviewable).',
+    },
+    // ── Ephemeral: pr-review state is local framework coordination ─────────
+    // pr-state.json + per-round snapshots are LOCAL coordination data, not
+    // audit trail. Rationale (2026-04 design re-evaluation):
+    //   1. pr-state.json embeds a PID in `lock.owner` — same security
+    //      reasoning that classifies state.json ephemeral.
+    //   2. Empirically, the prior COMMITTABLE classification was never
+    //      honored — across 9 prior merged PRs in this repo, every state
+    //      file accumulated locally and zero made it into git history. The
+    //      `git add -f` self-staging without a follow-up commit step was a
+    //      designed-in leak.
+    //   3. Field-by-field, the snapshot is a denormalized cache of GitHub
+    //      data: head_sha_by_round and comment_timeline reconstruct from
+    //      `gh pr view --json commits,timelineItems` and the comments API.
+    //      `superseded_findings` is computable from rounds/N/review.json
+    //      diffs. Optional fields were empty in 9/9 snapshots checked.
+    //   4. Architectural separation: GitHub PR API owns PR-level audit;
+    //      `.aperant/` owns local framework coordination; richer
+    //      cross-machine AI-performance telemetry belongs in Aperant the
+    //      app, not in every consumer's git repo.
+    {
+        pattern: '.aperant/pr-reviews/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Per-PR coordination + scratch; rebuildable from GitHub PR API. Forensic insights belong in Aperant the app, not git.',
+    },
+    // ── Ephemeral: coordination, runtime, transient ────────────────────────
+    {
+        pattern: '.aperant/state.json',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Coordination board (contains PIDs).',
+    },
+    {
+        pattern: '.aperant/active.json',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Legacy-shim aggregate of team-status/*.json (C31).',
+    },
+    {
+        pattern: '.aperant/team.json',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Team-mode flag + metadata (runtime coordination).',
+    },
+    {
+        pattern: '.aperant/pending-effects.jsonl',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Effects outbox — drained in-process; transient.',
+    },
+    {
+        pattern: '.aperant/events/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Append-only daily log of lifecycle transitions.',
+    },
+    {
+        pattern: '.aperant/team-status/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Per-agent liveness board (PID + incarnation guard).',
+    },
+    {
+        pattern: '.aperant/workflows/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Workflow run files (post-A1: unlinked or archived on destroy).',
+    },
+    {
+        pattern: '.aperant/tasks/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Per-task artifacts (spec, plan, progress) — gitignored.',
+    },
+    {
+        pattern: '.aperant/proof/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Screenshots, videos, HTML reports.',
+    },
+    {
+        pattern: '.aperant/logs/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Route-dropped, route-classify, etc.',
+    },
+    {
+        pattern: '.aperant/worktrees/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Gitignored via .gitignore; never commit.',
+    },
+    {
+        pattern: '.aperant/locks/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Coordination file locks.',
+    },
+    {
+        pattern: '.aperant/digests/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Narrator bookkeeping digests.',
+    },
+    {
+        pattern: '.aperant/quick/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Quick-task scratch dirs (ephemeral, recycled).',
+    },
+    {
+        pattern: '.aperant/paused/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Paused-session checkpoints (restored by /apt:resume).',
+    },
+    {
+        pattern: '.aperant/reviews/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Legacy review scratch (round artifacts).',
+    },
+    {
+        pattern: '.aperant/plans/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Plan-mode scratch before task-id assignment.',
+    },
+    {
+        pattern: '.aperant/tmp/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Transient scratch; never commit.',
+    },
+    {
+        pattern: '.aperant/wfrun/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'YAML workflow run artifacts (C17).',
+    },
+    {
+        pattern: '.aperant/design/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Design-scan outputs (tokens, extracted repo, synthesis) — rebuildable.',
+    },
+    // ── Explicit ephemeral: secrets/tokens MUST never classify committable ─
+    {
+        pattern: '.aperant/secrets/**',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'Secrets — never committable (R-02 belt).',
+    },
+    {
+        pattern: '.aperant/tokens.json',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'OAuth/integration tokens — never committable (R-02 belt).',
+    },
+    // ── Dotfiles at `.aperant/` root (gitignore meta) ──────────────────────
+    {
+        pattern: '.aperant/.gitignore',
+        class: ARTIFACT_CLASS.COMMITTABLE,
+        why: 'Gitignore meta — committable project policy artifact.',
+    },
+    {
+        pattern: '.aperant/.gitignore.pre-c31.backup',
+        class: ARTIFACT_CLASS.EPHEMERAL,
+        why: 'One-shot migration backup — not versioned long-term.',
+    },
+]);
+// Precompile regexes for hot-path classification. Keep the original rule
+// reference so callers that want `why` can find it by index.
+const COMPILED = RULES.map((rule) => ({ ...rule, regex: globToRegex(rule.pattern) }));
+/**
+ * Return the ordered list of committable globs. Deterministic. Frozen array
+ * (consumers should not mutate it).
+ *
+ * @returns {readonly string[]}
+ * @internal
+ */
+export function listCommittableGlobs() {
+    return Object.freeze(RULES.filter((r) => r.class === ARTIFACT_CLASS.COMMITTABLE).map((r) => r.pattern));
+}
+/**
+ * Return the ordered list of ephemeral globs. Deterministic. Frozen array.
+ *
+ * @returns {readonly string[]}
+ * @internal
+ */
+export function listEphemeralGlobs() {
+    return Object.freeze(RULES.filter((r) => r.class === ARTIFACT_CLASS.EPHEMERAL).map((r) => r.pattern));
+}
+/**
+ * Classify a repo-relative path.
+ *
+ *   - Returns 'committable' or 'ephemeral' when a rule matches.
+ *   - Returns `null` when the path is outside `.aperant/` OR when it's under
+ *     `.aperant/` but unmatched (unknown → forces the caller to pick).
+ *
+ * The glob matcher is the same one used by task outputs (`**` matches any
+ * sequence incl. `/`, `*` matches non-`/`). No negation, no braces.
+ *
+ * @param {string} relPath path relative to the repo root (e.g.
+ *   `.aperant/roadmap/framework/milestones.json`). Leading `./` stripped.
+ * @param {{}} [_opts] reserved for future options (no-op today).
+ * @returns {'committable' | 'ephemeral' | null}
+ * @internal
+ */
+export function classifyArtifactPath(relPath, _opts) {
+    if (typeof relPath !== 'string' || relPath.length === 0)
+        return null;
+    const path = normalizeRel(relPath);
+    if (!path.startsWith('.aperant/') && path !== '.aperant')
+        return null;
+    for (const rule of COMPILED) {
+        if (rule.regex.test(path))
+            return rule.class;
+    }
+    return null;
+}
+/**
+ * Detailed variant — returns `{ class, pattern, why }` or `null`. Intended for
+ * diagnostics (unknown-path reports, audit output).
+ *
+ * @param {string} relPath
+ * @returns {{ class: string, pattern: string, why: string } | null}
+ * @internal
+ */
+export function classifyArtifactPathDetailed(relPath) {
+    if (typeof relPath !== 'string' || relPath.length === 0)
+        return null;
+    const path = normalizeRel(relPath);
+    if (!path.startsWith('.aperant/') && path !== '.aperant')
+        return null;
+    for (const rule of COMPILED) {
+        if (rule.regex.test(path)) {
+            return Object.freeze({ class: rule.class, pattern: rule.pattern, why: rule.why });
+        }
+    }
+    return null;
+}
+/**
+ * Filter: return paths that classify committable. Drops unknown/null + ephemeral.
+ *
+ * @param {string[]} paths
+ * @returns {string[]} filtered subset (preserves input order; no dedupe).
+ * @internal
+ */
+export function filterCommittable(paths) {
+    if (!Array.isArray(paths))
+        return [];
+    return paths.filter((p) => classifyArtifactPath(p) === ARTIFACT_CLASS.COMMITTABLE);
+}
+/**
+ * Filter: return paths that classify ephemeral.
+ *
+ * @param {string[]} paths
+ * @returns {string[]} filtered subset (preserves input order; no dedupe).
+ * @internal
+ */
+export function filterEphemeral(paths) {
+    if (!Array.isArray(paths))
+        return [];
+    return paths.filter((p) => classifyArtifactPath(p) === ARTIFACT_CLASS.EPHEMERAL);
+}
+/**
+ * Normalize a repo-relative path for classification:
+ *   - drop a leading `./`
+ *   - normalize backslashes to forward slashes (Windows paths from git porcelain)
+ *   - trim trailing slash
+ *
+ * @param {string} p
+ * @returns {string}
+ * @internal
+ */
+function normalizeRel(p) {
+    let s = p.replace(/\\/g, '/');
+    if (s.startsWith('./'))
+        s = s.slice(2);
+    if (s.endsWith('/') && s.length > 1)
+        s = s.slice(0, -1);
+    return s;
+}
+//# sourceMappingURL=classification.mjs.map

package/dist/cli/artifacts/classification.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"classification.mjs","sourceRoot":"","sources":["../../../src/cli/artifacts/classification.mjs"],"names":[],"mappings":"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"}

package/dist/cli/artifacts/self-stage.d.mts

@@ -0,0 +1,21 @@
+/**
+ * Self-stage the committable subset of `changedPaths`.
+ *
+ * @param {string} projectDir absolute path to repo root where `.aperant/` lives.
+ * @param {string[]} changedPaths repo-relative paths that were just written
+ *   by the caller. Absolute paths are tolerated — they're relativized here.
+ * @param {{ outputs?: readonly string[] | null }} [opts]
+ * @returns {{ staged: string[], skipped: Array<{ path: string, reason: string }>, warnings: string[] }}
+ * @internal
+ */
+export function selfStageCommittableWrites(projectDir: string, changedPaths: string[], opts?: {
+    outputs?: readonly string[] | null;
+}): {
+    staged: string[];
+    skipped: Array<{
+        path: string;
+        reason: string;
+    }>;
+    warnings: string[];
+};
+//# sourceMappingURL=self-stage.d.mts.map

package/dist/cli/artifacts/self-stage.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-stage.d.mts","sourceRoot":"","sources":["../../../src/cli/artifacts/self-stage.mjs"],"names":[],"mappings":"AA8BA;;;;;;;;;GASG;AACH,uDAPW,MAAM,gBACN,MAAM,EAAE,SAER;IAAE,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAA;CAAE,GACpC;IAAE,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAiGtG"}