@aperant/framework 0.8.4 → 0.8.6

package/dist/driver-sdk/manifest.d.ts

@@ -0,0 +1,93 @@
+/**
+ * manifest.ts — TypeScript shape of a driver manifest.
+ *
+ * Mirrors `packages/framework/src/cli/verify-proof/manifest-schema.json`
+ * (ST03) one-to-one. The JSON Schema is the runtime validator (publish-
+ * time + load-time); this TS type is what third-party driver authors
+ * `import type` to author manifests with intellisense.
+ *
+ * Spec authority: spec.md §ID-03 (trust tiers) + §ID-04 (driver layout).
+ */
+export type TrustTier = 'first_party_signed' | 'community_verified' | 'community_unverified' | 'local_unverified';
+export type Stability = 'experimental' | 'beta' | 'ga';
+export type SandboxProfile = 'read_only' | 'workspace_write' | 'system_write';
+export type NetworkPosture = 'deny' | 'allowlist' | 'allow';
+/** Structured local-command — strings are NEVER accepted (ID-03). */
+export interface LocalCommand {
+    readonly binary: string;
+    readonly args: readonly string[];
+}
+/** Transport — exactly one of the variants. */
+export type Transport = {
+    readonly mcp_server_id: string;
+} | {
+    readonly local_command: LocalCommand;
+} | {
+    readonly http_endpoint: string;
+} | {
+    readonly npm_package: string;
+} | {
+    readonly builtin: true;
+};
+export interface Publisher {
+    readonly name: string;
+    readonly npm_scope?: string;
+    readonly github_org?: string;
+    readonly verified?: boolean;
+}
+export interface Provenance {
+    readonly scheme?: 'sigstore' | 'npm-provenance' | 'gpg' | 'none';
+    readonly identity?: string;
+    readonly signature?: string;
+    readonly certificate?: string;
+}
+export interface Integrity {
+    readonly manifest_sha256?: string;
+    readonly artifact_digest?: string;
+}
+export interface TrustBlock {
+    readonly tier: TrustTier;
+    readonly publisher?: Publisher;
+    readonly provenance?: Provenance;
+    readonly integrity?: Integrity;
+}
+export interface SecurityBlock {
+    readonly sandbox_profile: SandboxProfile;
+    readonly network: NetworkPosture;
+    readonly allowed_executables?: readonly string[];
+    readonly allow_shell?: boolean;
+    readonly requires_user_approval?: boolean;
+}
+export interface AuditBlock {
+    readonly log_invocations: boolean;
+    readonly log_manifest_hash: boolean;
+}
+export interface PreflightCheck {
+    readonly name: string;
+    readonly command?: LocalCommand;
+    readonly required: boolean;
+}
+export interface DriverManifest {
+    readonly driverId: string;
+    readonly version: string;
+    readonly targets: readonly string[];
+    readonly capabilities: readonly string[];
+    readonly evidence_capabilities?: readonly string[];
+    readonly frameworkApiRange: string;
+    readonly requires?: {
+        readonly allOf?: readonly string[];
+        readonly anyOf?: readonly string[];
+    };
+    readonly os?: readonly string[];
+    readonly arch?: readonly string[];
+    readonly container_support?: boolean;
+    readonly conflicts_with?: readonly string[];
+    readonly priority: number;
+    readonly stability: Stability;
+    readonly trust: TrustBlock;
+    readonly security: SecurityBlock;
+    readonly audit?: AuditBlock;
+    readonly preflight?: readonly PreflightCheck[];
+    readonly transport: Transport;
+}
+//# sourceMappingURL=manifest.d.ts.map

package/dist/driver-sdk/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/driver-sdk/manifest.ts"],"names":[],"mappings":"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"}

package/dist/driver-sdk/manifest.js

@@ -0,0 +1,12 @@
+/**
+ * manifest.ts — TypeScript shape of a driver manifest.
+ *
+ * Mirrors `packages/framework/src/cli/verify-proof/manifest-schema.json`
+ * (ST03) one-to-one. The JSON Schema is the runtime validator (publish-
+ * time + load-time); this TS type is what third-party driver authors
+ * `import type` to author manifests with intellisense.
+ *
+ * Spec authority: spec.md §ID-03 (trust tiers) + §ID-04 (driver layout).
+ */
+export {};
+//# sourceMappingURL=manifest.js.map

package/dist/driver-sdk/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/driver-sdk/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/driver-sdk/retry.d.ts

@@ -0,0 +1,33 @@
+/**
+ * retry.ts — exponential backoff helper with abort signal.
+ *
+ * Used by driver implementations that want to retry transient transport
+ * failures (DriverInvocationError) before giving up. Pure, dependency-free.
+ */
+export interface RetryOptions {
+    /** Total maximum attempts including the first. Default 3. */
+    readonly max_attempts?: number;
+    /** Initial delay in ms before the second attempt. Default 100. */
+    readonly base_delay_ms?: number;
+    /** Cap each delay at this many ms. Default 5000. */
+    readonly max_delay_ms?: number;
+    /**
+     * Multiplier applied to delay after each failed attempt. Default 2 →
+     * 100ms, 200ms, 400ms, 800ms, …
+     */
+    readonly multiplier?: number;
+    /** Optional AbortSignal — abort short-circuits the retry loop. */
+    readonly signal?: AbortSignal;
+    /**
+     * Optional predicate. When provided, only retry when shouldRetry(err) is
+     * true; otherwise re-throw immediately. Default: retry every error.
+     */
+    readonly shouldRetry?: (err: unknown) => boolean;
+}
+/**
+ * Run `fn` with exponential backoff. Returns the result of the first
+ * successful call. If every attempt fails (or the signal aborts), throws
+ * the last error.
+ */
+export declare function retryWithBackoff<T>(fn: () => Promise<T>, opts?: RetryOptions): Promise<T>;
+//# sourceMappingURL=retry.d.ts.map

package/dist/driver-sdk/retry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.d.ts","sourceRoot":"","sources":["../../src/driver-sdk/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,YAAY;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B;;;OAGG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;IAC7B;;;OAGG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,KAAK,OAAO,CAAA;CAChD;AAED;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,CAAC,EACvC,EAAE,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,IAAI,GAAE,YAAiB,GACrB,OAAO,CAAC,CAAC,CAAC,CAqCZ"}

package/dist/driver-sdk/retry.js

@@ -0,0 +1,50 @@
+/**
+ * retry.ts — exponential backoff helper with abort signal.
+ *
+ * Used by driver implementations that want to retry transient transport
+ * failures (DriverInvocationError) before giving up. Pure, dependency-free.
+ */
+/**
+ * Run `fn` with exponential backoff. Returns the result of the first
+ * successful call. If every attempt fails (or the signal aborts), throws
+ * the last error.
+ */
+export async function retryWithBackoff(fn, opts = {}) {
+    const maxAttempts = Math.max(1, opts.max_attempts ?? 3);
+    const baseDelay = Math.max(0, opts.base_delay_ms ?? 100);
+    const maxDelay = Math.max(0, opts.max_delay_ms ?? 5000);
+    const multiplier = opts.multiplier ?? 2;
+    const signal = opts.signal;
+    const shouldRetry = opts.shouldRetry ?? (() => true);
+    let lastErr;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+        if (signal?.aborted) {
+            throw signal.reason instanceof Error ? signal.reason : new Error('retryWithBackoff aborted');
+        }
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (attempt >= maxAttempts)
+                break;
+            if (!shouldRetry(err))
+                break;
+            const delay = Math.min(maxDelay, baseDelay * multiplier ** (attempt - 1));
+            await new Promise((resolve, reject) => {
+                const timer = setTimeout(resolve, delay);
+                if (signal) {
+                    const onAbort = () => {
+                        clearTimeout(timer);
+                        reject(signal.reason instanceof Error
+                            ? signal.reason
+                            : new Error('retryWithBackoff aborted'));
+                    };
+                    signal.addEventListener('abort', onAbort, { once: true });
+                }
+            });
+        }
+    }
+    throw lastErr instanceof Error ? lastErr : new Error(String(lastErr));
+}
+//# sourceMappingURL=retry.js.map

package/dist/driver-sdk/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../src/driver-sdk/retry.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAuBH;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACrC,EAAoB,EACpB,OAAqB,EAAE;IAEvB,MAAM,WAAW,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,CAAC,CAAC,CAAA;IACvD,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,aAAa,IAAI,GAAG,CAAC,CAAA;IACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC,CAAA;IACvD,MAAM,UAAU,GAAG,IAAI,CAAC,UAAU,IAAI,CAAC,CAAA;IACvC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAA;IAC1B,MAAM,WAAW,GAAG,IAAI,CAAC,WAAW,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,CAAA;IAEpD,IAAI,OAAgB,CAAA;IACpB,KAAK,IAAI,OAAO,GAAG,CAAC,EAAE,OAAO,IAAI,WAAW,EAAE,OAAO,EAAE,EAAE,CAAC;QACzD,IAAI,MAAM,EAAE,OAAO,EAAE,CAAC;YACrB,MAAM,MAAM,CAAC,MAAM,YAAY,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,0BAA0B,CAAC,CAAA;QAC7F,CAAC;QACD,IAAI,CAAC;YACJ,OAAO,MAAM,EAAE,EAAE,CAAA;QAClB,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACd,OAAO,GAAG,GAAG,CAAA;YACb,IAAI,OAAO,IAAI,WAAW;gBAAE,MAAK;YACjC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC;gBAAE,MAAK;YAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,QAAQ,EAAE,SAAS,GAAG,UAAU,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC,CAAA;YACzE,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;gBACrC,MAAM,KAAK,GAAG,UAAU,CAAC,OAAO,EAAE,KAAK,CAAC,CAAA;gBACxC,IAAI,MAAM,EAAE,CAAC;oBACZ,MAAM,OAAO,GAAG,GAAG,EAAE;wBACpB,YAAY,CAAC,KAAK,CAAC,CAAA;wBACnB,MAAM,CACL,MAAM,CAAC,MAAM,YAAY,KAAK;4BAC7B,CAAC,CAAC,MAAM,CAAC,MAAM;4BACf,CAAC,CAAC,IAAI,KAAK,CAAC,0BAA0B,CAAC,CACxC,CAAA;oBACF,CAAC,CAAA;oBACD,MAAM,CAAC,gBAAgB,CAAC,OAAO,EAAE,OAAO,EAAE,EAAE,IAAI,EAAE,IAAI,EAAE,CAAC,CAAA;gBAC1D,CAAC;YACF,CAAC,CAAC,CAAA;QACH,CAAC;IACF,CAAC;IACD,MAAM,OAAO,YAAY,KAAK,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,CAAA;AACtE,CAAC"}

package/dist/plugin/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "version": "0.8.4",
+  "version": "0.8.6",
   "description": "AI coding framework — composable skills for planning, executing, verifying, and reviewing code with any LLM provider. Works as Claude Code commands, Codex tasks, or programmatically.",
   "author": {
     "name": "Mikalsen AI",
@@ -46,6 +46,7 @@
     "skills/apt-prototype",
     "skills/apt-quick",
     "skills/apt-release-notes",
+    "skills/apt-research",
     "skills/apt-resume",
     "skills/apt-review",
     "skills/apt-roadmap",

package/dist/plugin/agents/apt-planner.md

@@ -240,6 +240,11 @@ survives the task as a second-consumer document.
 
 ### 4.B. STANDARD / DEEP / COMPLEX — PRD-shaped spec.md
 
+**Three orthogonal user-facing sections — keep them distinct.** User
+Stories (motivation prose), User Outcomes (verify-proof input contract),
+and Acceptance Criteria (code-level invariants) serve distinct
+purposes. Do NOT collapse them — STANDARD/DEEP specs carry all three.
+
 ```markdown
 # Spec: {task title}
 
@@ -257,6 +262,22 @@ survives the task as a second-consumer document.
 {One **US-NN (persona).** story per user-value slice. Stories map 1:1
 onto subtasks in implementation_plan.json.}
 
+## User Outcomes
+{Verify-proof input contract. One bolded `**Epic:**` headline + N
+atomic outcomes. Authors write the LITERAL string `**ON**` — IDs are
+POSITIONAL and synthesized by the parser (first row becomes O1, second
+O2, ...). Closed surface set: `electron | web | cli | api | electron+web`.
+Optional cross-refs via `*(requires ON N)*`. Refactor-only specs MAY
+use the empty-with-note escape (verbatim string,
+italic underscores + em dash + period required):}
+
+`_No user-observable changes — pure refactor._`
+
+**Epic:** {one-sentence user-facing capability headline}
+
+- **ON** [surface]: {user does X; system shows/does Y}
+- **ON** [surface]: {user does X; system shows/does Y} *(requires ON 1)*
+
 ## Implementation Decisions
 {Load-bearing principles carried into every subtask. Format:
 "### ID-NN: {title}" + rationale + practical consequence.}
@@ -279,9 +300,19 @@ reference these IDs via the per-subtask `acceptance_criteria` field.}
 ```
 
 **PRD section ordering is load-bearing.** `apt-tools coverage-check
-validate` greps `## Acceptance Criteria`; `apt-tools consistency check`
-greps `## Solution` and `## User Stories`. Renaming or reordering these
-sections breaks downstream tooling and the C15 consistency rules.
+validate` greps `## Acceptance Criteria` AND `## User Outcomes`;
+`apt-tools consistency check` greps `## Solution` and `## User Stories`.
+Renaming or reordering these sections breaks downstream tooling and the
+C15 consistency rules.
+
+**`## User Outcomes` synthesis directive.** Outcomes are
+user-observable (a user does X; the system shows/does Y); Acceptance
+Criteria are code-level invariants (a function returns X; a config key
+exists). Do NOT collapse them — they parse through different gates and
+serve different consumers. STANDARD/DEEP specs carry both sections in
+parallel. IDs are POSITIONAL: the parser counts outcome rows in
+document order and synthesizes `O1`, `O2`, ... — authors MUST write
+the literal `**ON**` token, never `**O1**`/`**O2**`.
 
 **Do NOT interview the user.** The PRD is synthesized from the task
 description + codebase investigation + AGENTS.md, not from a clarifying

package/dist/plugin/skills/apt-plan/SKILL.md

@@ -161,6 +161,14 @@ and is committable as a second-consumer document. Section ordering is
 **load-bearing** — downstream tooling (`apt-tools coverage-check`,
 `apt-tools consistency check`) reads sections by header.
 
+**Three orthogonal user-facing sections — keep them distinct.** User
+Stories carry product motivation, User Outcomes carry the
+verify-proof input contract, and Acceptance Criteria carry code-level
+invariants. The three do NOT subsume each other; a STANDARD/DEEP spec
+carries all three. See the `## User Outcomes` block below for the
+verify-proof unit shape (Epic line + atomic outcomes + surface tags
++ empty-with-note escape).
+
 ```markdown
 # Spec: {task title}
 
@@ -184,6 +192,29 @@ ships: new files, modified files, new flags, new config, new skills.}
 {persona}, when I {trigger}, I want {behavior} so I can {outcome}."
 Stories map 1:1 onto subtasks in implementation_plan.json.}
 
+## User Outcomes
+
+{The verify-proof input contract. One bolded `**Epic:**` headline + N
+atomic outcomes tagged by surface. Authors write the LITERAL string
+`**ON**` — IDs are POSITIONAL and synthesized by the parser (the first
+outcome row becomes `O1`, the second `O2`, etc.). Closed surface set:
+`electron | web | cli | api | electron+web`. Optional cross-references
+via `*(requires ON N)*` where `N` is the digit of a prior outcome's
+position. For pure-refactor specs with no user-observable changes, the
+body MAY be exactly `_No user-observable changes — pure refactor._`
+(italic underscores required, exact em dash, period mandatory).
+Coverage-check parses this section into a `user_outcomes` payload —
+see the gate table below.}
+
+**Epic:** {one-sentence user-facing capability headline}
+
+- **ON** [surface]: {user does X; system shows/does Y}
+- **ON** [surface]: {user does X; system shows/does Y} *(requires ON 1)*
+- **ON** [electron+web]: {cross-surface outcome — runs twice, once per surface}
+
+(Refactor-only escape:)
+_No user-observable changes — pure refactor._
+
 ## Implementation Decisions
 
 {Load-bearing principles carried forward into every subtask. Format:
@@ -215,6 +246,25 @@ ID. Subtasks reference these IDs via their per-subtask
 plan-coverage-check input.}
 ```
 
+**`## User Outcomes` is the verify-proof input contract (STANDARD/DEEP
+only — QUICK is hard-exempt per ID-05 / Fast Path Guarantee).** The
+section sits between `## User Stories` (product motivation prose) and
+`## Implementation Decisions` (load-bearing engineering principles).
+Coverage-check (`apt-tools coverage-check validate .`) parses the
+section into a `user_outcomes` payload with this gate behavior:
+
+| Header present? | Body shape | Gate result (v0.8.x) | v0.9.0 hard cutover |
+|---|---|---|---|
+| no | — | `warn` (migration deadline emitted) | `block` |
+| yes | `outcomes` (≥1 `**ON**` row) | `pass` | `pass` |
+| yes | exactly `_No user-observable changes — pure refactor._` | `pass` | `pass` |
+| yes | empty (header but nothing under it) | `block` | `block` |
+
+Closed surface set: `electron | web | cli | api | electron+web`. The
+`electron+web` tag means the outcome runs on both surfaces during
+verify-proof (split screenshot trees, two test entries in
+`verification.json`).
+
 **Constraint — do NOT interview the user.** The PRD is synthesized from
 the task description + codebase investigation + AGENTS.md, not from a
 clarifying interview. If a section truly cannot be filled, write

package/dist/plugin/skills/apt-pr-review/SKILL.md

@@ -1081,7 +1081,7 @@ For every finding with `validation_status == "confirmed_valid"` AND `severity
    - `{REVIEWER_EVIDENCE}` — the finding's `evidence` field verbatim.
 3. Invoke codex using the shape configured at `.aperant/config.json:router.llm.providers.codex`:
    ```bash
-   codex exec --model gpt-5.3-codex --input-file /tmp/fp-gate-${FINDING_ID}.md
+   codex exec --input-file /tmp/fp-gate-${FINDING_ID}.md
    ```
    Parse the JSON response `{verdict, reasoning, evidence_quote, severity_assessment}`.
 4. If `verdict == "falsify"`, set the finding's `validation_status = "dismissed_cross_model_falsification"` and copy the codex response into `fp_gate_result`. If `verdict == "confirm"`, pass through unchanged.