@aperant/framework 0.6.2

package/dist/plugin/skills/apt-pr-review/prompts/fp-gate-codex.md

@@ -0,0 +1,82 @@
+<!--
+  fp-gate-codex.md — cross-model false-positive gate prompt (R6).
+
+  Used by /apt:pr-review Phase 5 step 9 (external mode only) to run a
+  second-model check on HIGH and MEDIUM findings before they get
+  posted publicly via Phase 6b's gh pr review --comment.
+
+  Substitute {FINDING_JSON}, {FILE_SNIPPET}, {CLAUDE_MD}, and
+  {REVIEWER_EVIDENCE} before invoking via codex exec. Keep the
+  response-format section exact — downstream parsing is strict.
+-->
+
+# Cross-Model Falsification — /apt:pr-review external review
+
+You are adjudicating a PR-review finding produced by a different model.
+Your job is NOT to find new problems. Your job is to decide whether the
+reviewer's finding is supported by the cited code, or whether it is a
+false positive that should NOT be posted publicly to the PR author.
+
+## Finding under review
+
+```json
+{FINDING_JSON}
+```
+
+## Reviewer's cited evidence
+
+```
+{REVIEWER_EVIDENCE}
+```
+
+## File snippet (authoritative)
+
+The lines the reviewer claims to be reading:
+
+```
+{FILE_SNIPPET}
+```
+
+## Project context (CLAUDE.md excerpt)
+
+```
+{CLAUDE_MD}
+```
+
+## Your task
+
+Using ONLY the file snippet above (not your training data, not
+external knowledge beyond CLAUDE.md), answer these questions:
+
+1. Does the cited code actually contain the issue the reviewer
+   describes? (YES/NO, with a 1-sentence justification that quotes
+   the exact tokens you saw.)
+2. Is the severity the reviewer assigned appropriate for the behavior
+   in the file snippet? (PLAUSIBLE / OVER-STATED / UNDER-STATED)
+3. Is there an obvious reason this would be a false positive in
+   context — e.g. the line is inside a test, behind a feature flag,
+   clearly marked TODO, or the code path is unreachable?
+
+Then output your verdict.
+
+## Response format (strict)
+
+Emit exactly this JSON on stdout, with no preamble and no trailing
+commentary:
+
+```json
+{
+  "verdict": "confirm" | "falsify",
+  "reasoning": "1-2 sentence summary of why",
+  "evidence_quote": "exact tokens from the file snippet that back your verdict",
+  "severity_assessment": "plausible" | "over-stated" | "under-stated"
+}
+```
+
+`verdict = "falsify"` means: post-as-is would be a false positive.
+The orchestrator will mark the finding
+`validation_status=dismissed_cross_model_falsification` and attach your
+`reasoning` + `evidence_quote` as `fp_gate_result`.
+
+`verdict = "confirm"` means: the finding is supported by the snippet
+you were shown. Post it.

package/dist/plugin/skills/apt-pr-review/templates/external-comment.md

@@ -0,0 +1,34 @@
+<!--
+  external-comment.md — body template for Phase 6b (R4).
+
+  Substitute the {PLACEHOLDERS} below before posting via
+  `gh pr review {PR} --comment --body-file …`.
+
+  Keep the HTML footer EXACTLY as-is — downstream rounds parse it to
+  correlate comments with review ids.
+-->
+
+## /apt:pr-review — Round {ROUND}
+
+Automated review of this PR. This comment replaces the fix-and-push flow we use on internal branches; please treat it as a normal code review.
+
+### Auto-checks
+
+{AUTO_CHECK_SUMMARY}
+
+### Confirmed findings
+
+{CONFIRMED_FINDINGS_BY_SEVERITY}
+
+### Dismissed false positives
+
+The validator dismissed the following candidate findings. Included for transparency — no action needed from you.
+
+{DISMISSED_FPS}
+
+### Notes
+
+- This is round {ROUND} of at most 4. Further rounds will only trigger if you push new commits and explicitly request another review.
+- If you believe a confirmed finding is wrong, reply to it with `/apt dispute` and a short rationale; the next round will treat it as `author_contested` and a human maintainer will arbitrate.
+
+<!-- apt-pr-review round={ROUND} review_id={REVIEW_ID} authorship=external -->

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

@@ -0,0 +1,271 @@
+---
+name: apt:quick
+description: "Fast task execution — skip planning, go straight to implementation"
+apt-skill-version: {{APT_VERSION}}
+stage: quick
+intent: implement
+when_to_use: "The user has a small task (typo, copy change, rounding fix, single-file edit) that is obvious from the description and does not need planning."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Read, Write, Edit, Bash, Grep, Glob"
+argument-hint: "apt:quick [task description]"
+gates: []
+---
+<objective>
+Execute a small task quickly without full pipeline overhead. For small fixes, doc updates, config changes, and ad-hoc tasks. Skip planning — go straight to implementation with atomic commits and lightweight state tracking.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root (where you were invoked) UNLESS an active task has a task-level worktree (see below).
+- **Constitution:** Read `AGENTS.md` in the project root if it exists
+- **State directory:** `.aperant/quick/{task-id}/`
+- **Task-level worktree isolation:** If `.aperant/state.json` has an active task with a `worktree_path`, run all editing Bash commands with `cd {worktree_path} &&` prefix. `apt-tools` calls still take the project root as `<project-dir>` so they coordinate through the main repo's shared `.aperant/`. The quick task's `.aperant/quick/{task-id}/` directory lives in the main repo, not the worktree.
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `AGENTS.md` — Project constitution (conventions, tech stack)
+- Codebase files relevant to the task
+
+**Writes:**
+- `.aperant/quick/{task-id}/TASK.md` — Human-readable task record
+- `.aperant/quick/{task-id}/task.json` — Machine-readable task record (aggregatable)
+- `.aperant/quick/{task-id}/evidence/` — Screenshots from visual verification
+- `.aperant/quick/INDEX.md` — Running index of all quick tasks
+</state_files>
+
+<process>
+
+## 1. Parse Task
+
+Extract the task description from `$ARGUMENTS`.
+
+Generate a task ID: `quick-{YYYYMMDD}-{short-slug}` (e.g., `quick-20260410-fix-typo`).
+
+```bash
+mkdir -p .aperant/quick/{task-id}
+```
+
+**Source finding (best-effort — do not block if nothing found):**
+- If the user mentions a priority ID like "P1-1", "P2-3", etc., note it as `source_finding.priority_id`
+- If there is a recent verify-proof run directory under `.aperant/proof/` that covers the affected area, note its path as `source_finding.proof_run`
+- If the user references a specific test ID from a proof run, note it as `source_finding.test_id`
+
+## 2. Assess Scope
+
+Quickly verify this is appropriate for `/apt:quick`:
+- **Good fit:** Single-file fix, typo, config change, small refactor, doc update, dependency bump, adding a missing import, tweaking styles
+- **Too big:** Multi-file feature, architectural change, new subsystem, anything requiring tests
+
+If the task is too complex:
+```
+This task looks too complex for /apt:quick.
+Consider using /apt:plan + /apt:execute instead.
+
+Reason: {why it is too complex}
+```
+Ask the user if they want to proceed anyway or switch to the full pipeline.
+
+## 2.5. Dimension Check (Lightweight)
+
+QUICK tasks skip the full planner, but they still must respect architectural obligations:
+
+1. Read CLAUDE.md — scan for **MUST** obligation language (especially "Deployment Modes (Obligations)")
+2. If `.aperant/axes.json` exists, skim the axes list
+3. Does this task touch persistence, auth, storage, tokens, or data flow? If YES:
+   - This task crosses the deployment-mode axis and likely needs all 3 modes covered
+   - A task that needs multi-mode coverage is **too big for QUICK** — escalate:
+     ```
+     This task crosses deployment-mode obligations (3 modes must be covered).
+     Escalating to /apt:plan for proper dimensional coverage.
+     ```
+   - Ask the user to confirm escalation, or let them override if they're sure it's single-mode only
+
+If the task does NOT cross any obligation axes, proceed normally.
+
+## 3. Load Context
+
+1. Read `AGENTS.md` if it exists — extract relevant conventions
+2. Use Glob/Grep to find the files that need changes
+3. Read those files to understand current state
+
+## 4. Implement
+
+Make the changes directly:
+- Follow existing code patterns and conventions
+- Keep changes minimal — solve the stated problem, nothing more
+- If touching code with tests, run the tests to make sure nothing breaks
+
+## 5. Verify (Lightweight)
+
+Run a quick sanity check appropriate to the change:
+- **Code change:** Run typecheck and affected tests
+  ```bash
+  pnpm typecheck 2>&1 | tail -20
+  ```
+- **Config change:** Validate the config is syntactically correct
+- **Doc change:** No verification needed unless `--verify` flag is set
+- **Style change:** Run lint on changed files
+
+If visual verification is performed via MCP screenshots:
+- Save the screenshot to `.aperant/quick/{task-id}/evidence/` (not /tmp)
+- Record the relative path in `task.json` as `verification.evidence_path`
+
+If verification fails:
+- Fix the issue
+- Re-run verification
+- If stuck after 2 attempts, report the failure and let the user decide
+
+## 6. Commit
+
+Create an atomic commit with a descriptive message:
+
+```bash
+git add {changed-files}
+git commit -m "{type}: {description}"
+```
+
+Use appropriate conventional commit type:
+- `fix:` for bug fixes
+- `docs:` for documentation
+- `style:` for formatting/style
+- `chore:` for config, dependencies, maintenance
+- `refactor:` for code restructuring
+- `feat:` for small features (rare for quick tasks)
+
+## 7. Record Task
+
+Write `.aperant/quick/{task-id}/TASK.md`:
+
+```markdown
+# Quick Task: {task-id}
+
+## Description
+{what was done}
+
+## Files Changed
+- {file1}: {brief change description}
+
+## Verification
+- {what was checked and result}
+
+## Commit
+- {commit hash}: {commit message}
+
+## Timestamp
+{ISO date}
+```
+
+Write `.aperant/quick/{task-id}/task.json` (conforming to the `QuickTask` schema in `@aperant/framework/schemas`):
+
+```json
+{
+  "id": "{task-id}",
+  "description": "{what was done}",
+  "files_changed": [
+    { "path": "{file}", "change": "{brief description}" }
+  ],
+  "verification": {
+    "typecheck": "pass|fail|skip",
+    "lint": "pass|fail|skip",
+    "visual": "pass|fail|skip",
+    "test": "pass|fail|skip",
+    "evidence_path": "{relative path to screenshot, if captured}"
+  },
+  "commit": {
+    "hash": "{short commit hash}",
+    "message": "{commit message}"
+  },
+  "source_finding": {
+    "proof_run": "{path if found}",
+    "test_id": "{id if referenced}",
+    "priority_id": "{e.g. P1-1 if mentioned}"
+  },
+  "timestamp": "{ISO 8601 datetime}",
+  "duration_seconds": "{elapsed seconds if tracked}"
+}
+```
+
+Omit `source_finding` entirely if no linkage was found. Omit `evidence_path` if no screenshot was taken. Omit `duration_seconds` if not tracked.
+
+Update `.aperant/quick/INDEX.md`:
+- If the file does not exist, create it with this header:
+  ```markdown
+  # Quick Task Index
+
+  | Task | Description | Commit |
+  |------|-------------|--------|
+  ```
+- Append one row:
+  ```
+  | [{task-id}]({task-id}/TASK.md) | {one-line description} | {short commit hash} |
+  ```
+- Keep the table under 100 rows; if it exceeds 100 rows, trim the oldest entries from the top of the table (preserve the header).
+
+## 8. Report
+
+```
+Quick task complete: {task-id}
+  Changed: {file list}
+  Commit: {commit message}
+  Verified: {yes/no/skipped}
+
+State: .aperant/quick/{task-id}/TASK.md
+       .aperant/quick/{task-id}/task.json
+```
+
+If this fix addresses a verify-proof finding:
+  Suggest: "Run /apt:verify-proof {area} to re-verify the fix."
+  Do NOT run it automatically — the user decides.
+
+### Post-quick verify prompt
+
+After printing the completion report, decide whether to offer an `apt:verify`
+pass. Behaviour is gated by `preferences.quick_task_post_verify` in
+`.aperant/config.json` (default `"ask"` when the key is absent — older configs
+that predate C32 do not need regeneration).
+
+Resolution table:
+
+| Setting           | TTY?     | Action                                                                                  |
+|-------------------|----------|-----------------------------------------------------------------------------------------|
+| `"never"`         | any      | Skip silently — print nothing, exit.                                                    |
+| any value         | non-TTY  | Skip silently — non-interactive callers (spawned subagents, CI) get no prompt.          |
+| `"always"`        | TTY      | Invoke `apt:verify` with `{task-id}` immediately.                                       |
+| `"ask"` (default) | TTY      | Print `Run verify now? (y/n)` and read one line via `readline` with a 30-second timeout. `y`/`yes` (any case) → invoke `apt:verify {task-id}`. Anything else, including timeout → print `Skipping verify. Run manually with /apt:verify {task-id}.` and exit. |
+
+The `process.stdin.isTTY` check is non-negotiable: if stdin is not a TTY the
+skill MUST exit silently regardless of the config value, so spawned subagents
+never block on a prompt that no human will answer.
+
+```bash
+# Pseudocode the model executes inline:
+node -e '
+  const fs = require("fs");
+  const path = require("path");
+  const cfgPath = path.join(process.cwd(), ".aperant/config.json");
+  let mode = "ask";
+  try {
+    const cfg = JSON.parse(fs.readFileSync(cfgPath, "utf-8"));
+    if (cfg && cfg.preferences && cfg.preferences.quick_task_post_verify) {
+      mode = cfg.preferences.quick_task_post_verify;
+    }
+  } catch {}
+  if (mode === "never" || !process.stdin.isTTY) process.exit(0);
+  if (mode === "always") { /* invoke apt:verify {task-id} */ process.exit(0); }
+  // mode === "ask": readline prompt with 30s timeout, default = skip.
+'
+```
+
+This is skill markdown — the model executes the behaviour above; nothing here
+ships as runtime code.
+
+</process>

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

@@ -0,0 +1,202 @@
+---
+name: apt:resume
+description: "Restore context from a paused session or recover from a crash"
+apt-skill-version: {{APT_VERSION}}
+stage: resume
+intent: capture
+when_to_use: "The user is returning to paused work or recovering from a crash and needs to restore context from CONTINUE artifacts or the active-task state."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Grep, Glob, Write, Edit, Task"
+argument-hint: "apt:resume [task-id]"
+gates: []
+---
+<objective>
+Restore context and continue work after a session break — whether it was a graceful pause (CONTINUE files exist) or a crash/disconnect (no CONTINUE but state.json has an active task). Supports multiple paused sessions — shows all and lets the user pick which to resume.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root (where you were invoked)
+- **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary
+- **Constitution:** Read `AGENTS.md` in the project root if it exists
+- **Pause index:** `.aperant/CONTINUE_INDEX.md` (lists all paused sessions)
+- **Legacy handoff:** `.aperant/CONTINUE.md` (pre-v2 single-file format, migrate if found)
+- **State:** `.aperant/state.json` (always exists if initialized)
+- **Cross-agent team signal:** `.aperant/team-status/{agent-id}.json` records (gitignored, TTL-expired) are the canonical "who's working on what" surface; `state.active_tasks` is this agent's local view.
+- **Task-level worktree isolation:** after selecting a session, check `state.active_tasks[taskId].worktree_path`. If present, restore the working directory by prefixing subsequent Bash calls with `cd {worktree_path} &&` (or pass it as spawned-agent `cwd`). `apt-tools` commands still take the main repo as `<project-dir>`. Task artifacts (`.aperant/tasks/{id}/`) are shared through the main repo.
+</your_environment>
+
+<process>
+
+## 1. Discover Paused Sessions
+
+### 1a. Check for pause index
+Read `.aperant/CONTINUE_INDEX.md` if it exists — this is the primary source of paused sessions.
+
+### 1b. Check for legacy CONTINUE.md
+If `.aperant/CONTINUE.md` exists (pre-v2 format), treat it as one paused session. Migrate it after resume:
+- Move it to the appropriate task dir or `.aperant/paused/` location
+- Add it to the index
+
+### 1c. Scan for task-level CONTINUE files
+As a fallback, scan for CONTINUE.md files that might not be in the index:
+```bash
+find .aperant/tasks/*/CONTINUE.md .aperant/paused/*/CONTINUE.md 2>/dev/null
+```
+
+### 1d. Check state.json for active tasks
+```bash
+node packages/framework/bin/apt-tools.mjs health-check .
+node packages/framework/bin/apt-tools.mjs task list .
+```
+
+Combine all sources into a unified list of resumable sessions.
+
+## 2. Present Sessions
+
+### If multiple paused sessions found:
+
+```
+Paused Sessions
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  1. Chat UI Polish + Sidebar Redesign
+     Branch: closing-phase-4 | Paused: 2026-04-13
+     Progress: 6/9 items done
+     → .aperant/paused/paused-20260413-chat-ui-polish/CONTINUE.md
+
+  2. Onboarding State Unification
+     Branch: feat/onboarding-sync | Paused: 2026-04-13
+     Progress: executing subtask 3/5
+     → .aperant/tasks/task-20260413-onboarding-sync/CONTINUE.md
+
+  3. Fix DB Path in services.ts
+     Branch: closing-phase-4 | Paused: 2026-04-12
+     Progress: planned, not started
+     → .aperant/tasks/task-20260412-fix-db-path/CONTINUE.md
+
+Which session to resume? (number, or "all" to see full context for each)
+```
+
+Wait for user selection before proceeding.
+
+### If one paused session found:
+Proceed directly to Step 3 with that session.
+
+### If no paused sessions but active tasks in state.json:
+Follow crash recovery flow (Step 4).
+
+### If nothing found:
+```
+No paused sessions or active tasks found.
+
+→ Start something new: /apt "describe your task"
+```
+
+## 3. Resume Selected Session
+
+Read the selected CONTINUE.md and extract:
+- **Task description** — What was being worked on
+- **Branch** — Which branch to be on
+- **Decisions made** — Context that must not be lost
+- **Remaining work** — What still needs to be done
+- **Current state** — Pipeline stage, progress
+- **Next steps** — Ordered list of what to do next
+
+### Check Branch
+```bash
+git branch --show-current
+```
+If not on expected branch: suggest `git checkout {expected-branch}`
+
+### Restore Stashed Work
+If CONTINUE.md indicates stashed changes, find and pop the matching stash:
+```bash
+git stash list | grep "apt-pause: {task description}"
+```
+
+### Present Context Summary
+Display all key context from CONTINUE.md, then suggest the next action based on pipeline stage.
+
+### Clean Up After Resume
+After user confirms they have context:
+- Remove the CONTINUE.md file that was resumed
+- Remove its row from CONTINUE_INDEX.md
+- If the index is now empty, delete CONTINUE_INDEX.md
+
+## 4. Crash Recovery (no CONTINUE, stale active_tasks)
+
+This is the hard path — the session ended ungracefully.
+
+### Step 1: Run Health Check
+
+Parse `health-check` output for issues:
+
+**Stale locks:**
+```bash
+node packages/framework/bin/apt-tools.mjs lock cleanup .
+```
+Report: "Cleaned up {N} stale lock(s) from interrupted execution."
+
+**Orphaned events:**
+Report which subtasks were claimed but never completed. These need re-execution or manual resolution.
+
+**Dirty working tree:**
+```bash
+git status --porcelain
+```
+If uncommitted changes exist, present options:
+- "Commit these changes" — they may be partial work from the interrupted subtask
+- "Stash them" — save for later, continue with clean tree
+- "Discard them" — dangerous, only if the user confirms
+
+### Step 2: Reconstruct Context from State
+
+Read state.json `active_tasks` and the plan artifacts for each:
+- `.aperant/tasks/{task-id}/implementation_plan.json` — find completed vs pending subtasks
+- `.aperant/tasks/{task-id}/spec.md` — original requirements
+
+### Step 3: Present Recovery Summary
+
+```
+Crash Recovery
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Task: {description}
+Track: {track} | Phase: {phase}
+Progress: {completed}/{total} subtasks
+Last activity: {relative_time} ago
+
+Recovery actions taken:
+  {✓ Cleaned N stale locks | No stale locks}
+  {✓ Found N orphaned events | No orphaned events}
+  {⚠ N uncommitted files — awaiting your decision | Working tree clean}
+
+Completed subtasks:
+  1. ✓ {subtask-1}
+  2. ✓ {subtask-2}
+
+Remaining subtasks:
+  3. ○ {subtask-3} {← interrupted here, if orphaned event found}
+  4. ○ {subtask-4}
+
+→ Recommended: continue executing from subtask 3
+  Also: re-plan remaining work | verify what's done so far | start fresh
+```
+
+### Step 4: Route
+
+| Situation | Action |
+|-----------|--------|
+| Execution was interrupted mid-subtask | Resume from the interrupted subtask |
+| Execution completed but verify didn't run | Run apt:verify |
+| Plan exists but execution never started | Run apt:execute |
+| Only context exists (discuss done, no plan) | Run apt:plan |
+
+</process>