@aperant/framework 0.10.0 → 0.12.0

package/dist/cli/verify-proof/sandbox/self-test.mjs

@@ -0,0 +1,248 @@
+/**
+ * self-test.mjs — two-instance concurrent self-test for parallel
+ * /apt:verify-proof.
+ *
+ * Spawns TWO instances of the recipe's launch command concurrently
+ * (Promise.all with B jittered 50-150 ms) against per-instance sandbox
+ * dirs. Asserts BOTH instances reach the recipe's `readiness.logPattern`
+ * within `readiness.timeoutMs` AND neither emits `SQLITE_BUSY` or
+ * `EADDRINUSE`/`bind` errors in stderr.
+ *
+ * The verdict envelope shape mirrors verify-proof v2's
+ * `verification.json :: meta.verdict`:
+ *   {verified: bool, verdict: 'approved'|'needs_human',
+ *    reason: null|'self_test_failed_sqlite_busy'|
+ *            'self_test_failed_port_conflict'|
+ *            'self_test_failed_app_init_timeout',
+ *    durationMs: number}
+ *
+ * Cross-platform via `node:child_process.spawn` (NO shell). win32 short-
+ * circuits at the verify-sandbox command layer (subtask 4.2) — this
+ * module assumes a POSIX-ish host.
+ *
+ * No state-file writing here (4.2's job). Pure functional contract so
+ * the integration tests can drive it via `vi.spyOn(child_process,
+ * 'spawn')`.
+ */
+import child_process from 'node:child_process';
+import { mkdirSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join, resolve } from 'node:path';
+/**
+ * @typedef {Object} SelfTestVerdict
+ * @property {boolean} verified
+ * @property {'approved'|'needs_human'} verdict
+ * @property {null|'self_test_failed_sqlite_busy'|'self_test_failed_port_conflict'|'self_test_failed_app_init_timeout'} reason
+ * @property {number} durationMs
+ * @property {{A: ChildOutcome, B: ChildOutcome}} children
+ */
+/**
+ * @typedef {Object} ChildOutcome
+ * @property {boolean} ready
+ * @property {string|null} failureReason
+ * @property {string} stderrTail
+ */
+/**
+ * @param {{projectDir: string, recipeId: string, recipes: object[]}} args
+ * @returns {Promise<SelfTestVerdict>}
+ */
+export async function runSelfTest({ projectDir, recipeId, recipes }) {
+    const recipe = (recipes ?? []).find((r) => r && r.recipeId === recipeId);
+    if (!recipe) {
+        throw new Error(`runSelfTest: recipe not found: ${recipeId}`);
+    }
+    const launch = recipe.launch;
+    if (!launch?.binary) {
+        throw new Error(`runSelfTest: recipe ${recipeId} missing launch.{binary, args}`);
+    }
+    const readiness = recipe.readiness;
+    if (!readiness || typeof readiness.logPattern !== 'string') {
+        throw new Error(`runSelfTest: recipe ${recipeId} missing readiness.logPattern`);
+    }
+    const timeoutMs = readiness.timeoutMs ?? 30000;
+    const pid = process.pid;
+    const sandboxRoot = join(tmpdir(), `aperant-sandbox-${pid}-${Date.now()}`);
+    const dirs = {
+        A: join(sandboxRoot, 'A'),
+        B: join(sandboxRoot, 'B'),
+    };
+    mkdirSync(dirs.A, { recursive: true });
+    mkdirSync(dirs.B, { recursive: true });
+    const startedAt = Date.now();
+    const jitter = 50 + Math.random() * 100;
+    // Concurrency by construction: A starts immediately, B's start is
+    // awaited via a microtask + jitter delay. Promise.all races them.
+    const [outcomeA, outcomeB] = await Promise.all([
+        spawnInstance({ index: 'A', launch, readiness, timeoutMs, sandboxDir: dirs.A, projectDir }),
+        delay(jitter).then(() => spawnInstance({ index: 'B', launch, readiness, timeoutMs, sandboxDir: dirs.B, projectDir })),
+    ]);
+    const durationMs = Date.now() - startedAt;
+    const verdict = decideVerdict(outcomeA, outcomeB);
+    return {
+        ...verdict,
+        durationMs,
+        children: { A: outcomeA, B: outcomeB },
+    };
+}
+/**
+ * Race a readiness signal against the timeout, scanning stderr for the
+ * three known-bad patterns. Resolves to a ChildOutcome regardless of
+ * which arm wins. Always kills the child before resolving.
+ */
+function spawnInstance({ index: _index, launch, readiness, timeoutMs, sandboxDir, projectDir }) {
+    return new Promise((resolveOutcome) => {
+        const env = renderLaunchEnv(launch.envTemplate ?? {}, sandboxDir);
+        const child = child_process.spawn(launch.binary, launch.args ?? [], {
+            cwd: resolve(projectDir),
+            env: { ...process.env, ...env, SANDBOX_DIR: sandboxDir },
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        let resolved = false;
+        let stderrBuf = '';
+        const stdoutBuf = [];
+        const MAX_STDERR_BYTES = 4096;
+        const finish = (outcome) => {
+            if (resolved)
+                return;
+            resolved = true;
+            clearTimeout(timer);
+            try {
+                child.kill('SIGTERM');
+            }
+            catch {
+                /* already gone */
+            }
+            // SIGKILL grace
+            setTimeout(() => {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    /* gone */
+                }
+            }, 5000).unref?.();
+            resolveOutcome(outcome);
+        };
+        // onStderrText: appends to stderrBuf and checks failure-reason patterns.
+        // Must NOT be called with stdout data — informational app logs that mention
+        // "SQLITE_BUSY" or "EADDRINUSE" must not trigger failure verdicts (LOG-001).
+        const onStderrText = (text) => {
+            stderrBuf = (stderrBuf + text).slice(-MAX_STDERR_BYTES);
+            if (/SQLITE_BUSY/i.test(text)) {
+                finish({
+                    ready: false,
+                    failureReason: 'self_test_failed_sqlite_busy',
+                    stderrTail: stderrBuf.slice(-500),
+                });
+                return;
+            }
+            if (/EADDRINUSE|bind\s+failed|address already in use|EACCES|EPERM/i.test(text)) {
+                finish({
+                    ready: false,
+                    failureReason: 'self_test_failed_port_conflict',
+                    stderrTail: stderrBuf.slice(-500),
+                });
+                return;
+            }
+        };
+        // onStdoutText: checks readiness signal only. Never touches stderrBuf and
+        // never triggers failure-reason heuristics — stdout is not an error stream.
+        const onStdoutText = (text) => {
+            if (text.includes(readiness.logPattern)) {
+                finish({ ready: true, failureReason: null, stderrTail: stderrBuf.slice(-500) });
+            }
+        };
+        child.stdout?.on?.('data', (chunk) => {
+            const text = String(chunk);
+            stdoutBuf.push(text);
+            onStdoutText(text);
+        });
+        child.stderr?.on?.('data', (chunk) => {
+            const text = String(chunk);
+            onStderrText(text);
+            // Readiness may also appear on stderr (some apps log to stderr only).
+            if (text.includes(readiness.logPattern)) {
+                finish({ ready: true, failureReason: null, stderrTail: stderrBuf.slice(-500) });
+            }
+        });
+        child.on?.('error', (err) => {
+            finish({
+                ready: false,
+                failureReason: 'self_test_failed_app_init_timeout',
+                stderrTail: String(err.message ?? err),
+            });
+        });
+        child.on?.('exit', () => {
+            if (!resolved) {
+                // Process exited before signalling readiness. Treat as init timeout
+                // unless the stderr already revealed a known bad pattern (handled
+                // above before exit).
+                finish({
+                    ready: false,
+                    failureReason: 'self_test_failed_app_init_timeout',
+                    stderrTail: stderrBuf.slice(-500),
+                });
+            }
+        });
+        const timer = setTimeout(() => {
+            finish({
+                ready: false,
+                failureReason: 'self_test_failed_app_init_timeout',
+                stderrTail: stderrBuf.slice(-500),
+            });
+        }, timeoutMs);
+        // Don't keep the event loop alive on the timer.
+        timer.unref?.();
+    });
+}
+/**
+ * Combine two outcomes into the v2-shaped verdict envelope.
+ * Failure precedence: sqlite_busy > port_conflict > app_init_timeout.
+ *
+ * Every spawnInstance() resolution sets failureReason explicitly on the
+ * !ready path (the four finish() call sites cover SQLITE_BUSY, port
+ * conflict, app_init_timeout, and the child-error path which also maps
+ * to app_init_timeout). The priority loop therefore always finds a
+ * match; the unreachable fallthrough that used to live here was
+ * deleted per CLAUDE.md guideline 2 (no handling for impossible
+ * scenarios).
+ */
+function decideVerdict(a, b) {
+    if (a.ready && b.ready) {
+        return { verified: true, verdict: /** @type {const} */ ('approved'), reason: null };
+    }
+    const reasons = [a.failureReason, b.failureReason].filter(Boolean);
+    const priority = [
+        'self_test_failed_sqlite_busy',
+        'self_test_failed_port_conflict',
+        'self_test_failed_app_init_timeout',
+    ];
+    for (const cand of priority) {
+        if (reasons.includes(cand)) {
+            return {
+                verified: false,
+                verdict: /** @type {const} */ ('needs_human'),
+                reason: /** @type {any} */ (cand),
+            };
+        }
+    }
+    throw new Error(`self-test decideVerdict: unreachable — both outcomes failed without a known reason: ${JSON.stringify({ a, b })}`);
+}
+/**
+ * Substitute ${SANDBOX_DIR} placeholders in the recipe's envTemplate.
+ */
+function renderLaunchEnv(envTemplate, sandboxDir) {
+    const out = {};
+    for (const [k, v] of Object.entries(envTemplate)) {
+        // biome-ignore lint/suspicious/noTemplateCurlyInString: config template marker, not a typo
+        out[k] = typeof v === 'string' ? v.replaceAll('${SANDBOX_DIR}', sandboxDir) : v;
+    }
+    return out;
+}
+function delay(ms) {
+    return new Promise((res) => {
+        const t = setTimeout(res, ms);
+        t.unref?.();
+    });
+}
+//# sourceMappingURL=self-test.mjs.map

package/dist/cli/verify-proof/sandbox/self-test.mjs.map

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

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

@@ -1,6 +1,6 @@
 {
   "name": "aperant",
-  "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": {
     "name": "Mikalsen AI",
@@ -25,6 +25,7 @@
     "skills/apt",
     "skills/apt-author-skill",
     "skills/apt-bootstrap",
+    "skills/apt-catch-up",
     "skills/apt-caveman",
     "skills/apt-classify",
     "skills/apt-close-task",

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

@@ -217,6 +217,21 @@ Fast Path Guarantee). QUICK-routed tasks keep the existing 4-section
 shape; STANDARD/DEEP/COMPLEX tasks get a PRD-shaped artifact that
 survives the task as a second-consumer document.
 
+**Sandbox-gated parallel verify-proof — cite the v2 envelope verbatim.**
+When the plan calls for parallel `/apt:verify-proof` (e.g. fan-out
+worker spawned a verify-proof child, or `--parallel` is passed to
+`/apt:verify-proof`), the spec's User Outcomes section MUST cite the
+sandbox gate's v2 failure envelope verbatim:
+`{verdict: "needs_human", reason: "sandbox_unverified"}` (plus the
+structured error code `E_SANDBOX_UNVERIFIED` and the remediation
+`/apt:verify-proof setup`). Downstream agents reading the spec
+dispatch on these exact strings; paraphrasing them breaks the
+contract. The gate runs BEFORE Step 2.5 (Deferred-tool-load) and
+BEFORE the outcome walker — sandbox-unverified is a precondition
+failure, not a per-outcome transport failure. See
+`apt-verify-proof/SKILL.md` Step 2c for the gate definition and
+`docs/verify-proof-sandbox-patterns.md` for the worked adopter flow.
+
 ### 4.A. QUICK track / SIMPLE complexity — legacy 4-section spec
 
 ```markdown

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

@@ -80,10 +80,13 @@ If the planner claims a dimension is covered but the implementation does not act
 | **Code Quality** | Clean, idiomatic, lint-clean | Good, minor style issues | Acceptable, needs cleanup | Poor quality | Unacceptable |
 | **Test Coverage** | Comprehensive, edge cases | Good main-path coverage | Basic tests exist | Minimal tests | No coverage |
 
-## 4. Derive Verdict
-- **approved:** ALL dimensions >= 7, no critical issues
-- **approved-with-notes:** ALL dimensions >= 5
-- **rejected:** ANY dimension < 5 or critical issues
+## 4. Derive Verdict (v0.9.0 two-gate envelope)
+
+Verdict is the closed set `{approved, rejected, needs_human}`. Derived from the two-gate envelope (`automation_gate` AND `proof_gate`); dimensions are informational rationale only.
+
+- **approved:** `automation_gate: pass` AND `proof_gate: pass`.
+- **needs_human:** `automation_gate: pass` AND `proof_gate: fail` (typically: a UI-surface outcome lacked driver transport — see `/apt:verify-proof`).
+- **rejected:** `automation_gate: fail` (any of lint/typecheck/tests red) OR critical findings unresolved.
 
 ## 5. Write QA Sign-off
 Write `{task_dir}/qa_signoff.json` with scores, checks, issues, and verdict.
@@ -105,14 +108,16 @@ Either shape is accepted:
 
 Gate G8 (`consistency-check`) enforces this on ship via rules R4
 (finding-propagation) and R5 (verdict-consistency):
-- `verdict: "approved"` or `verdict: "approved-with-notes"` is incompatible
-  with any unresolved `critical` or `major` review finding (G42 Phase 1).
-  Neither verdict escapes R5 for blocking-severity findings. The sole bypass
-  is `--force --reason "<why>"` on the gate CLI (audit-logged). For
-  non-blocking findings (suggestion/note/info/nitpick), cite them in
-  `findings.notes` and use `approved-with-notes`.
+- `verdict: "approved"` is incompatible with any unresolved `critical` or
+  `major` review finding (G42 Phase 1). The sole bypass is `--force --reason
+  "<why>"` on the gate CLI (audit-logged). For non-blocking findings
+  (suggestion/note/info/nitpick), cite them in `findings.notes` and keep
+  the verdict `approved`.
 - `verdict: "rejected"` requires at least one cited finding (rejected
   without evidence is treated as drift).
+- `verdict: "needs_human"` signals a transport gap (e.g. UI-surface outcome
+  with no MCP driver). The R5 rule does not gate on it; re-run verify-proof
+  after installing the missing transport.
 
 ## 6. Report
 Output verdict with dimension scores and next step recommendation.

package/dist/plugin/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 |

package/dist/plugin/skills/apt-catch-up/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: apt:catch-up
+description: "Re-view the catch-up panel (Welcome-Back + Team-Change Digest) on demand"
+apt-skill-version: {{APT_VERSION}}
+stage: resume
+intent: capture
+when_to_use: "The user dismissed the auto catch-up panel on their last /apt and wants to re-summon it — an idempotent re-view of where they left off plus what teammates merged. Distinct from /apt:resume (full context restore) and never advances the Last-Seen Marker."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_execution_mode: auto
+execution_modes:
+  - auto
+allowed-tools: "Bash, Read"
+argument-hint: "apt:catch-up"
+gates: []
+---
+<objective>
+Recompute and display the combined catch-up panel — the **Welcome-Back
+Summary** (your most-recently-active task, phase, next step) and the
+**Team-Change Digest** (the PRs teammates merged to main since you last
+pulled) — exactly as the auto-on-apt display would show it, but **without
+advancing the Last-Seen Marker**. This is a read-only re-view: a user who
+dismissed the auto panel can re-summon it without disturbing the baseline and
+without invoking the heavier `/apt:resume`.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root (where you were invoked)
+- **apt-tools:** `node packages/framework/bin/apt-tools.mjs` or the installed `apt-tools` binary
+- **Last-Seen Marker:** `.aperant/last-seen/{email-slug}.json` (gitignored, per-machine) — this skill READS it but NEVER writes it.
+</your_environment>
+
+<process>
+
+## 1. Recompute the panel (read-only)
+
+```bash
+node packages/framework/bin/apt-tools.mjs catch-up .
+```
+
+This computes the SAME panel the interactive route call produces, against the
+**current** marker — and deliberately does **NOT** call `advanceLastSeen`
+(recompute-only contract). Parse the JSON `catch_up` field from the envelope.
+
+## 2. Render the panel
+
+Render exactly as the `apt/SKILL.md` "Catch-up panel" block does — Welcome-Back
+half first, then the Team-Change Digest half. Omit a half whose field is null.
+
+If `catch_up` is null, tell the user there is nothing new since their last
+visit (no active stale task and no new merges on main).
+
+```
+Where you left off: {description} — {lifecycle_phase} · subtask {current_subtask} ({relative_time})
+  Next: {next_step}
+  (+{others_count} others · /apt:resume)
+
+While you were away:
+  #{number} {title} — {author}
+  +{more_count} more on main
+```
+
+</process>
+
+<notes>
+- **Never advances the marker.** Unlike the auto-on-apt display (which advances
+  the Last-Seen Marker after the panel is evaluated), this command is purely a
+  re-view. Re-running it is idempotent.
+- **Distinct from `/apt:resume`.** Resume restores full context and routes to
+  the next action; catch-up is a lightweight orientation re-view.
+- **v1 is lazy compute.** The panel is computed on demand here, bounded by the
+  commits since your last pull. A background pre-warm worker (like the
+  update-check worker) is a tracked follow-up (LD-12), not part of v1.
+- **Vocabulary.** This is the Welcome-Back Summary + Team-Change Digest — not an
+  "activity feed", "changelog", or "notifications".
+</notes>

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

@@ -209,6 +209,8 @@ see the gate table below.}
 **Epic:** {one-sentence user-facing capability headline}
 
 - **ON** [surface]: {user does X; system shows/does Y}
+  - {indented inferred sub-check derived by the planning LLM}
+  - {another inferred sub-check}
 - **ON** [surface]: {user does X; system shows/does Y} *(requires ON 1)*
 - **ON** [electron+web]: {cross-surface outcome — runs twice, once per surface}
 
@@ -246,6 +248,27 @@ ID. Subtasks reference these IDs via their per-subtask
 plan-coverage-check input.}
 ```
 
+### Inferred sub-checks (v0.9.0 — verify-proof-v2-outcome-walker)
+
+Under each `**ON**` parent bullet, write indented child bullets (2-space
+prefix + `- `) representing inferred sub-checks the planning LLM derives
+from the outcome prose + surface. These are NOT user-written invariants;
+they are the planner's judgment of "what else must be true for this
+outcome to be approved." The verify-proof runner walks each inferred
+child the same way it walks the parent.
+
+Worked example (copy this shape verbatim into spec.md):
+
+    - **ON** [electron]: Clicking 'Settings' opens the settings modal.
+      - The modal traps focus on the close button.
+      - Clicking outside the modal closes it.
+      - Pressing Esc closes it and returns focus to the trigger.
+
+**NO `patterns/` library, NO `surfaces/<name>/manifest.json` tree, NO
+`OUTCOMES.md` file** — inferred bullets live IN spec.md. The author
+edits spec.md once if the inferred list is wrong; the runner does not
+re-derive them at proof time.
+
 **`## 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

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

@@ -247,10 +247,11 @@ The command resolves in this precedence order:
 
 1. `config.json:pr_review.authorship_overrides['pr-${PR_NUMBER}']` (per-PR pin)
 2. `config.json:pr_review.authorship_override` (global: `owned` | `external` | `auto`)
-3. `gh pr view` → `authorAssociation` + `headRepository.owner.login` vs. viewer login
-   - `authorAssociation IN (OWNER, MEMBER, COLLABORATOR)` AND same-repo branch → **owned**
-   - Fork OR `authorAssociation IN (NONE, CONTRIBUTOR, FIRST_TIME_CONTRIBUTOR)` → **external**
-4. Offline / gh unavailable / ambiguous payload → **unknown**
+3. `gh pr view` → `gh.author.login` vs. viewer login (G44 — `owned` means a PR you **authored**, not a branch you can push to)
+   - Same-repo branch AND `gh.author.login === viewer login` → **owned**
+   - Any other same-repo PR (a teammate's, or a repo-`OWNER` viewing someone else's PR) → **external** (`authorAssociation` is no longer consulted for the `owned` decision — it is retained only in the human-readable signal)
+   - Fork (head-repo owner ≠ base-repo owner) → **external**
+4. Offline / gh unavailable / ambiguous payload → **unknown** (treated as `external` for safety, see below)
 
 When the result is `unknown`, treat it as `external` for safety and prompt the user:
 

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

@@ -281,7 +281,7 @@ Execute the apt:verify workflow inline:
 6. Score on 4 dimensions (completeness, correctness, quality, coverage)
 7. Fix all issues found — every severity, not just critical (up to 4 iterations: first 2 discovery, last 2 verification-only)
 8. Write qa_signoff.json
-9. If `status` is `approved` or `approved-with-notes`, flip lifecycle to `reviewing` so Stage 4 (or `/apt:ship` when review is skipped) finds the task in the correct from-state. Skip this step entirely on `rejected`:
+9. If `status` is `approved`, flip lifecycle to `reviewing` so Stage 4 (or `/apt:ship` when review is skipped) finds the task in the correct from-state. Skip this step entirely on `rejected` (fix the code and re-run) or `needs_human` (install the missing driver transport and re-run /apt:verify-proof):
    ```bash
    node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase reviewing
    ```