@aperant/framework 0.10.0 → 0.12.0

package/dist/types/qa-scoring.d.ts

@@ -7,29 +7,43 @@ export interface QADimensionScore {
     score: number;
     rationale: string;
 }
-/** Threshold constants for QA verdict derivation */
+/**
+ * Threshold constants for QA verdict derivation.
+ *
+ * v0.9.0 (verify-proof-v2-outcome-walker_27-05-26) — `approved_with_notes`
+ * is DELETED. Dimensions are now informational rationale only; the verdict
+ * derives from the two-gate envelope (`automation_gate` + `proof_gate`),
+ * not per-dimension minimums.
+ */
 export declare const QA_DIMENSION_THRESHOLDS: {
     readonly approved: 7;
-    readonly approved_with_notes: 5;
 };
-/** Scored QA signoff — replaces boolean approved/rejected with dimension scores */
+/** Closed set of QA verdicts in v0.9.0+. `approved_with_notes` is deleted. */
+export type QAVerdict = 'approved' | 'rejected' | 'needs_human';
+/** The two boolean gates that drive verdict derivation. */
+export type GateStatus = 'pass' | 'fail';
+/** Scored QA signoff — verdict + checks + dimensions + findings */
 export interface ScoredQASignoff {
-    status: 'approved' | 'approved-with-notes' | 'rejected';
+    status: QAVerdict;
     timestamp: string;
     iterations: number;
     dimensions: QADimensionScore[];
+    gates: {
+        automation_gate: GateStatus;
+        proof_gate: GateStatus;
+    };
     checks: {
         tests: {
-            status: 'pass' | 'fail';
+            status: GateStatus;
             count: number;
             failures: string[];
         };
         typecheck: {
-            status: 'pass' | 'fail';
+            status: GateStatus;
             errors: string[];
         };
         lint: {
-            status: 'pass' | 'fail';
+            status: GateStatus;
             warnings: number;
         };
     };
@@ -40,6 +54,28 @@ export interface ScoredQASignoff {
     }>;
     notes: string;
 }
-/** Derive verdict from dimension scores */
-export declare function deriveVerdict(scores: QADimensionScore[]): ScoredQASignoff['status'];
+/**
+ * Derive the v0.9.0 two-gate verdict from `{automation_gate, proof_gate}`.
+ *
+ * The legacy per-dimension `deriveVerdict(scores: QADimensionScore[])` is
+ * deleted along with `approved_with_notes` — dimensions are now informational
+ * rationale on the report.
+ *
+ * Rules:
+ *   - `automation_gate: fail`  → `rejected` (regardless of `proof_gate`).
+ *   - `proof_gate: fail`       → `needs_human` (signals UI-surface outcomes
+ *     without proof) when automation is green; this aligns with the
+ *     workflow-level rule "any test with needs_human_with_transport rolls
+ *     up to needs_human" (callers that detect a hard fail without a
+ *     transport hole should pass `proof_gate: 'fail'`).
+ *   - Both gates pass → `approved`.
+ *
+ * Per AC13 (spec.md §3): the workflow's Step 7c rolls a `proof_gate: fail`
+ * caused by a UI-surface escape hatch up to `needs_human`; callers driving
+ * deriveVerdict from `{automation_gate, proof_gate}` get the same answer.
+ */
+export declare function deriveVerdict(input: {
+    automation_gate: GateStatus;
+    proof_gate: GateStatus;
+}): QAVerdict;
 //# sourceMappingURL=qa-scoring.d.ts.map

package/dist/types/qa-scoring.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"qa-scoring.d.ts","sourceRoot":"","sources":["../../src/types/qa-scoring.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,eAAO,MAAM,aAAa,2EAKhB,CAAA;AACV,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,WAAW,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CACjB;AAED,oDAAoD;AACpD,eAAO,MAAM,uBAAuB;;;CAI1B,CAAA;AAEV,mFAAmF;AACnF,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,UAAU,GAAG,qBAAqB,GAAG,UAAU,CAAA;IACvD,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,gBAAgB,EAAE,CAAA;IAC9B,MAAM,EAAE;QACP,KAAK,EAAE;YAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;SAAE,CAAA;QACrE,SAAS,EAAE;YAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,EAAE,CAAA;SAAE,CAAA;QACxD,IAAI,EAAE;YAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAA;KACnD,CAAA;IACD,MAAM,EAAE,KAAK,CAAC;QACb,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAA;QACzC,IAAI,EAAE,MAAM,CAAA;QACZ,WAAW,EAAE,MAAM,CAAA;KACnB,CAAC,CAAA;IACF,KAAK,EAAE,MAAM,CAAA;CACb;AAED,2CAA2C;AAC3C,wBAAgB,aAAa,CAAC,MAAM,EAAE,gBAAgB,EAAE,GAAG,eAAe,CAAC,QAAQ,CAAC,CAMnF"}
+{"version":3,"file":"qa-scoring.d.ts","sourceRoot":"","sources":["../../src/types/qa-scoring.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,eAAO,MAAM,aAAa,2EAKhB,CAAA;AACV,MAAM,MAAM,WAAW,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAA;AAExD,mDAAmD;AACnD,MAAM,WAAW,gBAAgB;IAChC,SAAS,EAAE,WAAW,CAAA;IACtB,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;CACjB;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,uBAAuB;;CAE1B,CAAA;AAEV,8EAA8E;AAC9E,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,UAAU,GAAG,aAAa,CAAA;AAE/D,2DAA2D;AAC3D,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,MAAM,CAAA;AAExC,mEAAmE;AACnE,MAAM,WAAW,eAAe;IAC/B,MAAM,EAAE,SAAS,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,UAAU,EAAE,MAAM,CAAA;IAClB,UAAU,EAAE,gBAAgB,EAAE,CAAA;IAC9B,KAAK,EAAE;QACN,eAAe,EAAE,UAAU,CAAA;QAC3B,UAAU,EAAE,UAAU,CAAA;KACtB,CAAA;IACD,MAAM,EAAE;QACP,KAAK,EAAE;YAAE,MAAM,EAAE,UAAU,CAAC;YAAC,KAAK,EAAE,MAAM,CAAC;YAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;SAAE,CAAA;QAChE,SAAS,EAAE;YAAE,MAAM,EAAE,UAAU,CAAC;YAAC,MAAM,EAAE,MAAM,EAAE,CAAA;SAAE,CAAA;QACnD,IAAI,EAAE;YAAE,MAAM,EAAE,UAAU,CAAC;YAAC,QAAQ,EAAE,MAAM,CAAA;SAAE,CAAA;KAC9C,CAAA;IACD,MAAM,EAAE,KAAK,CAAC;QACb,QAAQ,EAAE,UAAU,GAAG,SAAS,GAAG,MAAM,CAAA;QACzC,IAAI,EAAE,MAAM,CAAA;QACZ,WAAW,EAAE,MAAM,CAAA;KACnB,CAAC,CAAA;IACF,KAAK,EAAE,MAAM,CAAA;CACb;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE;IACpC,eAAe,EAAE,UAAU,CAAA;IAC3B,UAAU,EAAE,UAAU,CAAA;CACtB,GAAG,SAAS,CAIZ"}

package/dist/types/qa-scoring.js

@@ -5,21 +5,42 @@ export const QA_DIMENSIONS = [
     'code_quality',
     'test_coverage',
 ];
-/** Threshold constants for QA verdict derivation */
+/**
+ * Threshold constants for QA verdict derivation.
+ *
+ * v0.9.0 (verify-proof-v2-outcome-walker_27-05-26) — `approved_with_notes`
+ * is DELETED. Dimensions are now informational rationale only; the verdict
+ * derives from the two-gate envelope (`automation_gate` + `proof_gate`),
+ * not per-dimension minimums.
+ */
 export const QA_DIMENSION_THRESHOLDS = {
-    approved: 7, // All dimensions >= 7 = approved
-    approved_with_notes: 5, // All dimensions >= 5 = approved-with-notes
-    // Any dimension < 5 = rejected
+    approved: 7, // Retained as informational; the verdict derivation no longer reads it.
 };
-/** Derive verdict from dimension scores */
-export function deriveVerdict(scores) {
-    if (scores.length === 0)
+/**
+ * Derive the v0.9.0 two-gate verdict from `{automation_gate, proof_gate}`.
+ *
+ * The legacy per-dimension `deriveVerdict(scores: QADimensionScore[])` is
+ * deleted along with `approved_with_notes` — dimensions are now informational
+ * rationale on the report.
+ *
+ * Rules:
+ *   - `automation_gate: fail`  → `rejected` (regardless of `proof_gate`).
+ *   - `proof_gate: fail`       → `needs_human` (signals UI-surface outcomes
+ *     without proof) when automation is green; this aligns with the
+ *     workflow-level rule "any test with needs_human_with_transport rolls
+ *     up to needs_human" (callers that detect a hard fail without a
+ *     transport hole should pass `proof_gate: 'fail'`).
+ *   - Both gates pass → `approved`.
+ *
+ * Per AC13 (spec.md §3): the workflow's Step 7c rolls a `proof_gate: fail`
+ * caused by a UI-surface escape hatch up to `needs_human`; callers driving
+ * deriveVerdict from `{automation_gate, proof_gate}` get the same answer.
+ */
+export function deriveVerdict(input) {
+    if (input.automation_gate === 'fail')
         return 'rejected';
-    const min = Math.min(...scores.map((s) => s.score));
-    if (min >= QA_DIMENSION_THRESHOLDS.approved)
-        return 'approved';
-    if (min >= QA_DIMENSION_THRESHOLDS.approved_with_notes)
-        return 'approved-with-notes';
-    return 'rejected';
+    if (input.proof_gate === 'fail')
+        return 'needs_human';
+    return 'approved';
 }
 //# sourceMappingURL=qa-scoring.js.map

package/dist/types/qa-scoring.js.map

@@ -1 +1 @@
-{"version":3,"file":"qa-scoring.js","sourceRoot":"","sources":["../../src/types/qa-scoring.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B,cAAc;IACd,aAAa;IACb,cAAc;IACd,eAAe;CACN,CAAA;AAUV,oDAAoD;AACpD,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,QAAQ,EAAE,CAAC,EAAE,iCAAiC;IAC9C,mBAAmB,EAAE,CAAC,EAAE,4CAA4C;IACpE,+BAA+B;CACtB,CAAA;AAqBV,2CAA2C;AAC3C,MAAM,UAAU,aAAa,CAAC,MAA0B;IACvD,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,UAAU,CAAA;IAC1C,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAA;IACnD,IAAI,GAAG,IAAI,uBAAuB,CAAC,QAAQ;QAAE,OAAO,UAAU,CAAA;IAC9D,IAAI,GAAG,IAAI,uBAAuB,CAAC,mBAAmB;QAAE,OAAO,qBAAqB,CAAA;IACpF,OAAO,UAAU,CAAA;AAClB,CAAC"}
+{"version":3,"file":"qa-scoring.js","sourceRoot":"","sources":["../../src/types/qa-scoring.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B,cAAc;IACd,aAAa;IACb,cAAc;IACd,eAAe;CACN,CAAA;AAUV;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG;IACtC,QAAQ,EAAE,CAAC,EAAE,wEAAwE;CAC5E,CAAA;AA+BV;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,UAAU,aAAa,CAAC,KAG7B;IACA,IAAI,KAAK,CAAC,eAAe,KAAK,MAAM;QAAE,OAAO,UAAU,CAAA;IACvD,IAAI,KAAK,CAAC,UAAU,KAAK,MAAM;QAAE,OAAO,aAAa,CAAA;IACrD,OAAO,UAAU,CAAA;AAClB,CAAC"}

package/dist/types/state.d.ts

@@ -24,12 +24,17 @@ export interface ActiveTask {
     phase: TaskPhase;
     progress: TaskProgress;
 }
-/** A task that has been completed */
+/**
+ * A task that has been completed.
+ *
+ * v0.9.0 — `qa_verdict` is the closed set `{approved, rejected, needs_human}`.
+ * The legacy `approved_with_notes` middle band is DELETED (no shim).
+ */
 export interface CompletedTask {
     id: string;
     description: string;
     completed_at: string;
-    qa_verdict: 'approved' | 'approved_with_notes' | 'rejected';
+    qa_verdict: 'approved' | 'rejected' | 'needs_human';
     commits: string[];
 }
 /** A decision recorded during task execution */

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

@@ -1 +1 @@
-{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/types/state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wDAAwD;AACxD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;AAE/D,sCAAsC;AACtC,MAAM,MAAM,SAAS,GAClB,YAAY,GACZ,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,QAAQ,CAAA;AAEX,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC5B,cAAc,EAAE,MAAM,CAAA;IACtB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACvB,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,EAAE,YAAY,CAAA;CACtB;AAED,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,UAAU,GAAG,qBAAqB,GAAG,UAAU,CAAA;IAC3D,OAAO,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,UAAU,GAAG,IAAI,CAAA;IAC9B,eAAe,EAAE,aAAa,EAAE,CAAA;IAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACvC,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAA;IAClB,oEAAoE;IACpE,UAAU,CAAC,EAAE;QACZ,MAAM,EAAE,OAAO,CAAA;QACf,wBAAwB,EAAE,MAAM,CAAA;QAChC,YAAY,EAAE,MAAM,CAAA;KACpB,CAAA;CACD"}
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../../src/types/state.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,wDAAwD;AACxD,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;AAE/D,sCAAsC;AACtC,MAAM,MAAM,SAAS,GAClB,YAAY,GACZ,UAAU,GACV,WAAW,GACX,WAAW,GACX,WAAW,GACX,WAAW,GACX,QAAQ,CAAA;AAEX,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC5B,cAAc,EAAE,MAAM,CAAA;IACtB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,oDAAoD;AACpD,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACvB,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,EAAE,YAAY,CAAA;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC7B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,UAAU,GAAG,UAAU,GAAG,aAAa,CAAA;IACnD,OAAO,EAAE,MAAM,EAAE,CAAA;CACjB;AAED,gDAAgD;AAChD,MAAM,WAAW,YAAY;IAC5B,KAAK,EAAE,MAAM,CAAA;IACb,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;CACZ;AAED,2DAA2D;AAC3D,MAAM,WAAW,YAAY;IAC5B,OAAO,EAAE,MAAM,CAAA;IACf,cAAc,EAAE,MAAM,CAAA;IACtB,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,UAAU,GAAG,IAAI,CAAA;IAC9B,eAAe,EAAE,aAAa,EAAE,CAAA;IAChC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,YAAY,CAAC,CAAA;IACvC,+DAA+D;IAC/D,SAAS,EAAE,OAAO,CAAA;IAClB,oEAAoE;IACpE,UAAU,CAAC,EAAE;QACZ,MAAM,EAAE,OAAO,CAAA;QACf,wBAAwB,EAAE,MAAM,CAAA;QAChC,YAAY,EAAE,MAAM,CAAA;KACpB,CAAA;CACD"}

package/dist/types/task-record.d.ts

@@ -62,13 +62,21 @@ export interface TaskRecord {
      */
     pr_url?: string;
 }
-/** Completed task row stored under `state.completed_tasks[]`. */
+/**
+ * Completed task row stored under `state.completed_tasks[]`.
+ *
+ * v0.9.0 — `qa_verdict` is the closed set
+ * `{approved, rejected, needs_human, completed}`. The legacy
+ * `approved_with_notes` middle band is DELETED (no shim). `completed`
+ * remains as a phase-only marker for tasks that closed without a
+ * verify-proof verdict.
+ */
 export interface CompletedTaskRecord {
     id: string;
     description: string;
     scope: Scope;
     completed_at: string;
-    qa_verdict: 'approved' | 'approved_with_notes' | 'rejected' | 'completed';
+    qa_verdict: 'approved' | 'rejected' | 'needs_human' | 'completed';
     commits: string[];
     lifecycle_phase?: LifecyclePhase;
 }

package/dist/types/task-record.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"task-record.d.ts","sourceRoot":"","sources":["../../src/types/task-record.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;AAE/D;iEACiE;AACjE,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE;QACL,KAAK,EAAE,KAAK,CAAA;QACZ,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;QAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KACvB,CAAA;IACD,EAAE,EAAE;QACH,KAAK,EAAE,KAAK,CAAA;QACZ,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;QAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KACvB,CAAA;IACD,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;qEACiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,YAAY;IAC5B,cAAc,EAAE,MAAM,CAAA;IACtB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACvB,KAAK,EAAE,KAAK,CAAA;IACZ,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,eAAe,EAAE,cAAc,CAAA;IAC/B,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,QAAQ,EAAE,YAAY,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED,iEAAiE;AACjE,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,KAAK,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,UAAU,GAAG,qBAAqB,GAAG,UAAU,GAAG,WAAW,CAAA;IACzE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,eAAe,CAAC,EAAE,cAAc,CAAA;CAChC"}
+{"version":3,"file":"task-record.d.ts","sourceRoot":"","sources":["../../src/types/task-record.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,aAAa,CAAA;AACjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,SAAS,CAAA;AAEpC,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAA;AAE/D;iEACiE;AACjE,MAAM,WAAW,gBAAgB;IAChC,IAAI,EAAE;QACL,KAAK,EAAE,KAAK,CAAA;QACZ,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;QAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KACvB,CAAA;IACD,EAAE,EAAE;QACH,KAAK,EAAE,KAAK,CAAA;QACZ,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;QAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;KACvB,CAAA;IACD,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,CAAC,EAAE,MAAM,CAAA;IACf;qEACiE;IACjE,cAAc,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,YAAY;IAC5B,cAAc,EAAE,MAAM,CAAA;IACtB,kBAAkB,EAAE,MAAM,CAAA;IAC1B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;CAC9B;AAED,MAAM,WAAW,UAAU;IAC1B,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,SAAS,CAAA;IAChB,QAAQ,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IACvB,KAAK,EAAE,KAAK,CAAA;IACZ,YAAY,EAAE,MAAM,GAAG,IAAI,CAAA;IAC3B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,eAAe,EAAE,MAAM,GAAG,IAAI,CAAA;IAC9B,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,eAAe,EAAE,cAAc,CAAA;IAC/B,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,QAAQ,EAAE,YAAY,CAAA;IACtB,UAAU,EAAE,MAAM,CAAA;IAClB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,gBAAgB,CAAC,EAAE,MAAM,CAAA;IACzB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;GAQG;AACH,MAAM,WAAW,mBAAmB;IACnC,EAAE,EAAE,MAAM,CAAA;IACV,WAAW,EAAE,MAAM,CAAA;IACnB,KAAK,EAAE,KAAK,CAAA;IACZ,YAAY,EAAE,MAAM,CAAA;IACpB,UAAU,EAAE,UAAU,GAAG,UAAU,GAAG,aAAa,GAAG,WAAW,CAAA;IACjE,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,eAAe,CAAC,EAAE,cAAc,CAAA;CAChC"}

package/drivers/mobile/README.md

@@ -0,0 +1,40 @@
+# mobile driver
+
+Unified iOS + Android UI-driving verify-proof driver. Wraps the
+[`mobile-mcp`](https://github.com/mobile-next/mobile-mcp) MCP server
+(mobile-next, Apache-2.0) — one backend for both platforms, driven via the
+native accessibility tree with screenshot-coordinate fallback (ADB for
+Android, idb for iOS).
+
+- **Targets:** `ios`, `android`, `expo`, `react-native`.
+- **Transport:** `{ mcp_server_id: "mobile-mcp" }` (provisioned as
+  `npx -y @mobilenext/mobile-mcp@latest`).
+- **Platform selection:** chosen INSIDE the tool call
+  (`mobile_list_available_devices` → device id), NOT at resolver time — that
+  is why one driver covers both platforms (decision D-01).
+
+## Lifecycle boundary
+
+This driver only **drives UI + captures evidence** against a foregrounded,
+JS-ready app. The app lifecycle — build, install, launch, Metro start, and
+the launch-readiness gate — is owned by `apt-tools mobile prepare`
+(decisions D-03/D-04), which runs BEFORE any verb is dispatched.
+
+## System prerequisites (validated, not installed)
+
+`mobile-mcp` is pure npm, but the underlying device toolchain is NOT:
+
+- **iOS:** `idb-companion` (`brew install idb-companion`) + Xcode + a booted
+  Simulator.
+- **Android:** Android SDK + `adb` (`$ANDROID_HOME/platform-tools`) + an
+  emulator/device.
+
+These are validated by the manifest's `preflight[]` via
+`apt-tools driver doctor` (which records `missing_deps` with guidance) — the
+framework never auto-installs them (decision D-09).
+
+## Out of scope
+
+Real-device runs and Mac Catalyst (separate RFCs). XcodeBuildMCP is an
+optional future escalation for native-Xcode-heavy iOS builds, not a
+dependency of this driver (decision D-02).

package/drivers/mobile/driver.mjs

@@ -0,0 +1,106 @@
+/**
+ * mobile/driver.mjs — bundled unified mobile driver (iOS + Android).
+ *
+ * Wraps the `mobile-mcp` MCP server (mobile-next/mobile-mcp, Apache-2.0),
+ * the single UI-driving backend for BOTH platforms (decision D-01). The
+ * platform/device is chosen INSIDE the tool call (mobile_list_available_
+ * devices → device id), NOT at resolver time — that is why one driver
+ * targets ios/android/expo/react-native.
+ *
+ * The app lifecycle (build / install / launch / Metro / ready-gate) is
+ * owned by `apt-tools mobile prepare`, NOT this driver (D-03/D-04). This
+ * driver assumes a foregrounded, JS-ready app and only drives UI + captures
+ * evidence.
+ *
+ * Per ID-01 — the workflow prose NEVER names mcp__mobile-mcp__* tools; the
+ * verb→tool mapping lives ONLY here. Transport dispatch happens at the
+ * workflow-runner layer (which holds the model's tool surface).
+ *
+ * IDL verb → mobile-mcp tool mapping:
+ *   launch         → mobile_use_device (select the booted device/simulator)
+ *   click          → mobile_click_on_screen_at_coordinates
+ *   type           → mobile_type_keys
+ *   key            → mobile_press_button
+ *   swipe          → mobile_swipe_on_screen
+ *   screenshot     → mobile_save_screenshot
+ *   capture_logs   → mobile_device_logs
+ *   assert_visible → mobile_list_elements_on_screen (element present)
+ *   assert_text    → mobile_list_elements_on_screen (text match)
+ *   teardown       → mobile_terminate_app (best-effort)
+ *
+ * The driver is a thin adapter: it validates input shape via the IDL
+ * arg-metadata and returns a VerbResult. The actual transport dispatch
+ * happens at the workflow runner layer. For conformance testing we expose
+ * the verb signatures as identity stubs returning VerbResult — the SDK
+ * conformance kit then validates the shape contract.
+ */
+
+import { validateVerbArgs } from '../../src/cli/verify-proof/idl/index.mjs'
+
+/** Build a success VerbResult. */
+function ok(evidence_paths = []) {
+	return { status: 'success', evidence_paths, duration_ms: 0, retry_count: 0 }
+}
+function fail(error) {
+	return { status: 'fail', evidence_paths: [], duration_ms: 0, retry_count: 0, error }
+}
+
+/**
+ * Validate args + return a VerbResult shape stub. Real transport invocation
+ * happens at the workflow-runner layer (model holds the tool surface —
+ * mcp__mobile-mcp__*).
+ *
+ * @param {string} verb
+ * @param {Record<string, unknown>} args
+ * @returns {{status: 'success'|'fail'|'skip', evidence_paths: string[], duration_ms: number, retry_count: number, error?: string}}
+ */
+function adaptVerb(verb, args) {
+	const check = validateVerbArgs(verb, args)
+	if (!check.valid) {
+		return fail(`mobile.${verb}: missing required args: ${check.missing.join(', ')}`)
+	}
+	if (verb === 'screenshot' && typeof args.output_path === 'string') {
+		return ok([args.output_path])
+	}
+	return ok([])
+}
+
+export async function launch(args) {
+	return adaptVerb('launch', args)
+}
+
+export async function click(args) {
+	return adaptVerb('click', args)
+}
+
+export async function type(args) {
+	return adaptVerb('type', args)
+}
+
+export async function key(args) {
+	return adaptVerb('key', args)
+}
+
+export async function swipe(args) {
+	return adaptVerb('swipe', args)
+}
+
+export async function screenshot(args) {
+	return adaptVerb('screenshot', args)
+}
+
+export async function capture_logs(args) {
+	return adaptVerb('capture_logs', args)
+}
+
+export async function assert_visible(args) {
+	return adaptVerb('assert_visible', args)
+}
+
+export async function assert_text(args) {
+	return adaptVerb('assert_text', args)
+}
+
+export async function teardown(args) {
+	return adaptVerb('teardown', args)
+}

package/drivers/mobile/manifest.json

@@ -0,0 +1,49 @@
+{
+	"driverId": "mobile",
+	"version": "0.1.0",
+	"targets": ["ios", "android", "expo", "react-native"],
+	"capabilities": [
+		"launch",
+		"click",
+		"type",
+		"key",
+		"swipe",
+		"screenshot",
+		"capture_logs",
+		"assert_visible",
+		"assert_text",
+		"teardown"
+	],
+	"evidence_capabilities": ["screenshot", "capture_logs"],
+	"frameworkApiRange": "^1.0.0",
+	"priority": 80,
+	"stability": "ga",
+	"trust": {
+		"tier": "first_party_signed",
+		"publisher": {
+			"name": "Aperant",
+			"npm_scope": "@aperant",
+			"github_org": "Mikalsen-AI",
+			"verified": true
+		}
+	},
+	"security": {
+		"sandbox_profile": "workspace_write",
+		"network": "deny",
+		"requires_user_approval": false
+	},
+	"audit": { "log_invocations": true, "log_manifest_hash": true },
+	"preflight": [
+		{
+			"name": "xcrun (iOS Simulator toolchain)",
+			"command": { "binary": "xcrun", "args": ["simctl", "help"] },
+			"required": false
+		},
+		{
+			"name": "adb (Android platform-tools)",
+			"command": { "binary": "adb", "args": ["--version"] },
+			"required": false
+		}
+	],
+	"transport": { "mcp_server_id": "mobile-mcp" }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aperant/framework",
-  "version": "0.10.0",
+  "version": "0.12.0",
   "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": "Mikalsen AI <hello@mikalsen.ai>",
   "type": "module",

package/prompts/inbox-clarification.md

@@ -0,0 +1,11 @@
+Run one read-only clarification turn using Work Record context, prior chat history, and the latest user response.
+Return semantic readiness updates and either the next single focused clarification question or ready status, without mutating project files or external systems.
+
+You are the Aperant clarification agent.
+First call readPhaseOutput with phase="triage" to inspect the triage output.
+If triage is already specific and high-confidence, set status="ready" and omit nextChatMessage.
+Otherwise, populate nextChatMessage with EXACTLY ONE focused, concrete question that addresses the highest-impact remaining readiness gap. Do not batch multiple questions into one turn.
+Ground the question in the triage findings, the inbox title and description, and the prior message history. Acknowledge what the user already said when relevant.
+Set nextChatMessage.dimensionKey to the readiness dimension the question targets, and nextChatMessage.cardId to the matching open clarification card when one exists.
+Keep nextClarificationQuestions as the ordered list of remaining open questions (one per open dimension); the UI renders this list as a chip row alongside the chat.
+Use repository tools only when needed to sharpen the question.

package/prompts/inbox-triage.md

@@ -0,0 +1,20 @@
+Refine one Inbox Work Item into structured triage output.
+Use supplied repository evidence and preserve read-only behavior.
+Return semantic findings, readiness evidence, and clarification prompts without mutating project files or external systems.
+
+You are the Aperant triage agent.
+Produce structured JSON only via the provided schema.
+Semantic capability mapping: repository_evidence maps to listFiles and readFile tools.
+Use listFiles and readFile tools to ground claims in repository evidence.
+Return a triage dossier with repo-evidenced facts, inferred assumptions, risks, acceptance criteria, and clarification plan.
+Always include readinessEvaluation with rubricVersion, dimensions, missingDimensions, hardBlockers, and justificationSummary.
+Universal readiness keys: problem_clarity, scope_definition, repo_evidence, risk_identification, acceptance_criteria_quality.
+Bug-specific keys: repro_steps, expected_vs_actual, impact_assessment.
+Feature-specific keys: user_value, solution_shape, dependency_mapping.
+Enhancement-specific keys: current_behavior_baseline, incremental_scope, migration_safety.
+Every readiness dimension requires key, score (0-100), evidence, justification, and optional hardBlocker.
+Only place verified repository findings in repoEvidencedFacts.
+For every inferred assumption, set disposition to requires_hitl_confirmation or accepted_assumption.
+Do not present product commitments as facts unless repository evidence directly supports them.
+Each proposed acceptance criterion must include a verificationMethod and Given/When/Then fields when behavior is being specified.
+Prefer concise summaries and concrete touch points.

package/prompts/qa_orchestrator_agentic.md

@@ -66,10 +66,10 @@ The reviewer writes `qa_report.md` and updates `implementation_plan.json` with a
 
 Read the `qa_signoff` from `implementation_plan.json`. The reviewer now writes dimension scores alongside the status.
 
-Read the dimension scores:
-- If ALL dimensions >= 7 and status is "approved" -> Build passes. Write final QA report. Done.
-- If ALL dimensions >= 5 and status is "approved-with-notes" -> Accept with notes. Write final QA report with improvement suggestions. Done.
-- If ANY dimension < 5 -> Analyze which dimensions are lowest (Phase 4)
+Read the gates + dimension scores:
+- If `automation_gate: pass` AND `proof_gate: pass` AND status is "approved" -> Build passes. Write final QA report. Done.
+- If `automation_gate: pass` AND `proof_gate: fail` AND status is "needs_human" -> Transport gap. Write final QA report listing what the human must install (e.g. an MCP server). Done.
+- If `automation_gate: fail` OR critical findings unresolved -> status is "rejected". Spawn fixer (Phase 4).
 - If no scores written -> Reviewer failed to score. Re-spawn with explicit scoring instructions: "You MUST score all 4 dimensions (completeness, correctness, code_quality, test_coverage) on 1-10 before writing a verdict."
 - If no signoff written at all -> Reviewer failed to update the file. Retry with explicit instructions.
 
@@ -100,10 +100,10 @@ When the reviewer rejects, triage based on dimension scores from the qa_signoff,
 - Documentation formatting
 - Non-functional improvements
 
-**Decision Framework:**
-- If ONLY cosmetic issues and ALL dimension scores >= 5 -> approve with notes (write qa_signoff: approved-with-notes)
-- If ALL dimension scores >= 7 and no critical issues -> approve the build (write qa_signoff: approved)
-- If ANY dimension < 5 -> spawn qa_fixer with targeted guidance focused on the lowest-scoring dimension
+**Decision Framework (v0.9.0 two-gate envelope):**
+- If `automation_gate: pass` AND `proof_gate: pass` AND no critical issues -> approve the build (write qa_signoff: approved)
+- If `automation_gate: pass` AND `proof_gate: fail` (UI-surface outcome missing driver transport) -> write qa_signoff: needs_human with a `transport_gap` array
+- If `automation_gate: fail` OR critical issues unresolved -> spawn qa_fixer with targeted guidance
 - If the same critical issue appears 3+ times -> escalate to human
 
 ### Phase 5: Fix Cycle
@@ -137,19 +137,20 @@ Track iteration count. Your goal is to converge quickly:
 
 ## QUALITY GATES
 
-### Approval Criteria (Score-Based)
+### Approval Criteria (v0.9.0 two-gate envelope)
 Approve when ALL of these are true:
-- All 4 dimension scores >= 7 (for "approved") or >= 5 (for "approved-with-notes")
+- `automation_gate: pass` (tests + typecheck + lint all green)
+- `proof_gate: pass` (every outcome has surface-appropriate evidence)
 - No critical issues in the issues array
-- Automated checks (tests, typecheck, lint) all pass
+- Dimensions land >= 7 as informational rationale (does NOT drive the verdict)
 
-### Score Thresholds
-- **approved**: ALL dimensions >= 7 AND no critical issues
-- **approved-with-notes**: ALL dimensions >= 5 AND no critical issues
-- **rejected**: ANY dimension < 5 OR critical issues found
+### Verdict Closed Set
+- **approved**: `automation_gate: pass` AND `proof_gate: pass` AND no critical issues
+- **needs_human**: `automation_gate: pass` AND `proof_gate: fail` (transport gap)
+- **rejected**: `automation_gate: fail` OR critical issues unresolved
 
-### Acceptable Imperfections (for approved-with-notes)
-These should NOT block approval when all dimensions are >= 5:
+### Acceptable Imperfections (cited in `findings.notes` on an `approved` verdict)
+These do NOT block approval and ride along as notes:
 - Missing optional features (if spec marks them as optional)
 - Code style deviations (if functionality is correct)
 - Missing edge case handling for unlikely scenarios

package/prompts/qa_reviewer.md

@@ -37,13 +37,15 @@ You MUST score 4 dimensions on a 1-10 scale. The verdict is DERIVED from scores
 **3-4 (Poor):** Significant problems. Multiple issues.
 **1-2 (Failed):** Fundamentally broken or missing.
 
-### Verdict Derivation (NOT your choice -- derived from scores)
+### Verdict Derivation (v0.9.0 two-gate envelope; NOT your choice -- derived from gates)
 
-- **approved**: ALL dimensions >= 7 AND no critical issues
-- **approved-with-notes**: ALL dimensions >= 5 AND no critical issues
-- **rejected**: ANY dimension < 5 OR critical issues found
+Verdict is the closed set `{approved, rejected, needs_human}`. It derives from the two-gate envelope (`automation_gate` AND `proof_gate`) per `/apt:verify-proof`. Dimensions are informational rationale only.
 
-You MUST write scores BEFORE writing the verdict. The verdict follows from the scores.
+- **approved**: `automation_gate: pass` AND `proof_gate: pass` AND no critical findings.
+- **needs_human**: `automation_gate: pass` AND `proof_gate: fail` (typically: UI-surface outcome with no driver transport — see verify-proof workflow).
+- **rejected**: `automation_gate: fail` OR critical findings unresolved.
+
+You MUST write scores BEFORE writing the verdict. The verdict follows from the gates, with dimensions as rationale.
 
 ---
 
@@ -440,7 +442,7 @@ Create a comprehensive QA report with dimension scores:
 | test_coverage | {N}/10 | {evidence} |
 
 **Minimum score:** {min}
-**Derived verdict:** {approved|approved-with-notes|rejected}
+**Derived verdict:** {approved|rejected|needs_human}
 
 ## Summary
 
@@ -514,7 +516,7 @@ For each critical/major issue, describe what the Coder Agent should do:
 
 **Next Steps**:
 - [If approved: Ready for merge]
-- [If approved-with-notes: List notes for future improvement]
+- [If needs_human: Install the missing driver transport (e.g. MCP server) and re-run /apt:verify-proof]
 - [If rejected: List of fixes needed, then re-run QA]
 ```
 
@@ -566,17 +568,17 @@ EOF
 # Only commit actual code changes to the project
 ```
 
-### If APPROVED-WITH-NOTES:
+### If NEEDS_HUMAN (transport gap):
 
-Same as approved, but with status "approved-with-notes" and an additional `notes` array:
+Same as approved, but with status `"needs_human"` and a `transport_gap` array describing what the human must install (e.g. an MCP server, a binary):
 
 ```json
 {
   "qa_signoff": {
-    "status": "approved-with-notes",
-    "notes": [
-      "Minor issue: [description]",
-      "Suggestion: [description]"
+    "status": "needs_human",
+    "transport_gap": [
+      "Missing MCP server: puppeteer (drivers/browser/manifest.json :: transport.mcp_server_id)",
+      "After install, re-run /apt:verify-proof"
     ],
     "dimension_scores": {
       "completeness": "[N]",
@@ -762,11 +764,11 @@ QA will automatically re-run after fixes.
 
 The QA -> Fix -> QA loop continues until:
 
-1. **All dimension scores >= 7** (for approved) or **>= 5** (for approved-with-notes)
+1. **`automation_gate: pass`** (lint + typecheck + tests all green) AND **`proof_gate: pass`** (every outcome has surface-appropriate evidence)
 2. **No critical issues remain**
 3. **All tests pass**
 4. **No regressions**
-5. **QA derives approved or approved-with-notes verdict**
+5. **QA derives `approved`** (the only ship-eligible verdict; `needs_human` requires installing the missing transport, `rejected` requires code fixes)
 
 Maximum iterations: 5 (configurable)
 

package/skills/apt/SKILL.md

@@ -75,6 +75,34 @@ SessionStart hook — zero latency on /apt. If `update_check` is null,
 no chip. Skip the chip entirely once the user has run `/apt:update`
 in the current session (the cache is cleared there).
 
+**Catch-up panel (runtime-agnostic):** if the route envelope includes a
+non-null `catch_up` field, print the combined panel BEFORE the mode handler
+runs, regardless of runtime (Claude Code, Codex, Gemini, Cursor, …). The
+panel has two halves; render `catch_up.welcome_back` first, then
+`catch_up.team_digest`. Omit a half whose field is null.
+
+If `catch_up.welcome_back` is present (your own half-finished work):
+
+```
+Where you left off: {description} — {lifecycle_phase}{current_subtask ? " · subtask " + current_subtask : ""} ({relative_time})
+{next_step ? "  Next: " + next_step : ""}
+{others_count > 0 ? "  (+" + others_count + " others · /apt:resume)" : ""}
+```
+
+If `catch_up.team_digest` is present (what teammates merged while you were away):
+
+```
+While you were away:
+{for each entry in team_digest.entries: "  #" + number + " " + title + " — " + author}
+{team_digest.more_count > 0 ? "  +" + team_digest.more_count + " more on main" : ""}
+```
+
+This is display-only here — the Last-Seen Marker advance happens in route.mjs,
+not in this skill. The panel is computed lazily on interactive (TTY) calls
+only; non-TTY/background/spawned calls carry no `catch_up` field. Do not call
+it an "activity feed", "changelog", or "notifications" — it is the
+Welcome-Back Summary + Team-Change Digest.
+
 Then proceed to the matching mode handler below. Do NOT deviate from the routing decision.
 </mandatory_first_step>
 
@@ -129,6 +157,7 @@ Show available commands table:
 | `apt:scan` | Discover standards + refresh feature registry |
 | `apt:docs` | Generate/update documentation |
 | `apt:resume` | Restore context after session break |
+| `apt:catch-up` | Re-view the catch-up panel (Welcome-Back + Team-Change Digest) — never advances the Last-Seen Marker |
 | `apt:pause` | Human-initiated handoff — save state when YOU need to stop |
 | `apt:ship` | Create PR with traceability |
 | `apt:close-task` | Post-merge closer — confirm PR merged, flip phase, drain narration ledger |