@aperant/framework 0.6.3 → 0.6.5

package/skills/apt-triage/AGENT-BRIEF.md

@@ -0,0 +1,84 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/triage/AGENT-BRIEF.md
+Licensed under MIT. Modifications: aligned with Aperant's 5-state
+machine (needs-triage / needs-info / ready-for-agent / ready-for-human /
+wontfix) and the backend-pluggable mirror model (local-only / github-issues / app-inbox).
+-->
+
+# Triage Agent Brief — what to do with each state
+
+## needs-triage (inbound)
+
+A task lands here by default — no state assigned yet. Read the task
+description, the linked artifacts, and CONTEXT.md (if relevant).
+
+Decide:
+
+- Is the task **concrete enough** to act on?
+  - **Yes, agent can act:** → `ready-for-agent`. Note required acceptance
+    criteria and files.
+  - **Yes, but needs human judgment:** → `ready-for-human`. Note WHY
+    (design taste / product call / security review).
+  - **No, missing info:** → `needs-info`. Note what's missing.
+  - **No, not going to act:** → `wontfix`. Note reason.
+
+Category: assign `bug` or `enhancement`. Don't conflate them — bug
+triage and enhancement triage have different priorities downstream.
+
+## needs-info (blocked on the reporter)
+
+Don't keep grilling. Write one clarifying question, surface it to the
+reporter (via the backend adapter or by tagging the user in the
+local-only case), and stop. Re-enter triage when the answer arrives.
+
+If the info is never supplied:
+
+- After 30 days with no response → `wontfix` with reason "no response
+  to clarification request"
+- Earlier than 30 days, only on a clear signal that the reporter
+  abandoned the task
+
+## ready-for-agent
+
+The task is concrete: files identified, acceptance criteria stated,
+no human-judgment-required gates ahead. An agent can take it.
+
+This is NOT a green-light to start `/apt:plan` automatically — the
+triage agent's job ends here. The user (or a downstream skill) picks
+ready-for-agent tasks off the queue and runs them.
+
+## ready-for-human
+
+The task requires human judgment that no agent should auto-resolve.
+Common reasons:
+
+- Design taste (apt:design / apt:mockup needed, then human chooses
+  between variants)
+- Product decision (does this belong in the product at all?)
+- Security review (a credential / auth / data-handling change that
+  needs human eyes)
+- Legal / compliance call
+
+Tag the human reviewer in the backend's mention surface (GitHub
+Issues assignee, app-inbox owner field, or local-only `task.owner`).
+
+## wontfix (closed without implementation)
+
+Record the reason verbatim. Patterns:
+
+- "Out of scope — belongs to {parallel track / v2 / separate area}"
+- "Already addressed by {commit-sha / task-id / decision in
+  context-notes}"
+- "No actionable behavior change — task description was a question
+  better answered by {apt:zoom-out / docs / discussion}"
+- "Reporter abandoned — no response to clarification request after 30 days"
+
+`wontfix` is terminal. Re-opening requires a fresh `needs-triage`
+record.
+
+## When in doubt
+
+Default to `ready-for-human` over `wontfix`. False-positive `wontfix`
+loses real work; false-positive `ready-for-human` just adds one review
+turn. The cost asymmetry favors the more conservative call.

package/skills/apt-triage/OUT-OF-SCOPE.md

@@ -0,0 +1,75 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/triage/OUT-OF-SCOPE.md
+Licensed under MIT. Modifications: aligned with Aperant's pipeline
+(other skills exist for the out-of-scope concerns — explicit pointers).
+-->
+
+# Triage Out-of-Scope
+
+What this skill is NOT. Knowing the boundary prevents triage from
+metastasizing into a catch-all decision-making surface.
+
+## Out-of-scope concerns and where they belong
+
+### Locking decisions
+Triage moves a task between states; it does NOT lock design or
+implementation decisions. Decisions live in
+`.aperant/context/notes/{task-id}.md` (via `/apt:discuss`) or in
+`docs/adr/NNNN-slug.md` (via `apt-tools adr write` if the Nygard
+3-gate filter passes).
+
+### Feature design
+Triage does NOT design features. If a `needs-triage` task contains a
+vision or vague intent ("we should have analytics"), the right move is
+`ready-for-human` with a pointer to `/apt:discuss --brainstorm` — not
+to invent the feature shape inside the triage agent's context.
+
+### Multi-task prioritization
+Triage assigns a state to one task at a time. It does NOT decide which
+ready-for-agent task should be worked on first. That's the roadmap
+surface (`apt-tools roadmap`) or the active-task surface (`apt-tools
+active`).
+
+### Implementation planning
+Triage does NOT emit an `implementation_plan.json`. That's `/apt:plan`'s
+job, invoked AFTER a task is in `ready-for-agent` state.
+
+### Verification / review
+Triage does NOT verify implementation quality. That's `/apt:verify` and
+`/apt:review` AFTER the agent ships.
+
+### Stakeholder communication
+Triage's `needs-info` state surfaces a clarifying question to the
+reporter via the configured backend's mention surface — it does NOT
+own the conversation thread itself. Long back-and-forths belong in the
+backend (GitHub Issues comments, app-inbox replies), not in the triage
+record's `extra` field.
+
+### Coordination layer
+Triage does NOT atomically claim a task for a specific agent worker,
+heartbeat, or coordinate cross-machine. That's the coordination layer
+(team-task roundtable verdicts R1-R16). Triage and coordination share
+data (the task ID, the lifecycle phase) but their surfaces are disjoint.
+
+### Security incident response
+Triage does NOT escalate security incidents through their own
+pipeline. If a `needs-triage` task has a security-sensitive flag (set
+in `extra.security_sensitive` once v2 ships), it routes immediately to
+`ready-for-human` and stops — the human owns the incident response.
+
+## What triage IS
+
+A 5-state machine + bug/enhancement category + extensible metadata
+record. That's it. Every concern above either belongs to a sibling
+skill or stays in the backend that hosts the conversation.
+
+## The metadata extension contract
+
+Triage's v1 schema includes `extra: Record<string, unknown>` for v2 OSS
+contributor primitives. The v1 schema MUST be forward-compatible: v1
+readers MUST ignore unrecognized fields under `extra`, and v2 readers
+MUST gracefully handle missing fields under `extra` (treat as
+undefined; don't crash). This is the non-breaking schema extension
+mechanism — it's what lets us ship v1 today and add v2 fields later
+without a migration.

package/skills/apt-triage/SKILL.md

@@ -0,0 +1,169 @@
+---
+name: apt:triage
+description: "Move a task through the 5-state triage machine (needs-triage → needs-info → ready-for-agent | ready-for-human → wontfix). Mirrors to local triage.json by default; backends pluggable."
+apt-skill-version: {{APT_VERSION}}
+stage: plan
+intent: investigate
+when_to_use: "An inbound task / bug report / feature request needs triage — is it ready for an agent, ready for a human, blocked on more info, or won't-fix? Always available; only the BACKEND it mirrors to is configurable."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: require-existing
+default_track: STANDARD
+default_execution_mode: step
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Read, Write, Bash, Grep, Glob"
+argument-hint: "apt:triage [task-id]"
+gates: []
+config_keys:
+  - task_tracking.backend
+  - task_tracking.publish_to_tracker
+  - task_tracking.tracker_url
+  - task_tracking.tracker_label_vocabulary
+---
+
+# Triage — 5-State Task Machine
+
+This skill moves a task through a 5-state machine. The state machine
+runs identically regardless of backend (local-only / github-issues /
+app-inbox); only the mirror destination changes.
+
+**Pocock adoption attribution.** State machine + AGENT-BRIEF.md +
+OUT-OF-SCOPE.md sub-files ported from Matt Pocock's MIT-licensed
+`triage` skill. Aperant-specific extensions:
+
+- Backend abstraction (configured at `apt:setup` Batch 8 — task_tracking.backend)
+- Local-only default (zero GitHub auth on first run — ID-01: Framework
+  full-featured locally; backends are pluggable)
+- Extensible metadata field `extra: Record<string, unknown>` for v2 OSS
+  contributor primitives (trust tier, repro status, security flag,
+  response templates) — non-breaking schema extension when v2 adds them
+- Fast Path Guarantee: QUICK-routed tasks NEVER enter triage (ID-05)
+
+## When to Use
+
+- An inbound task / bug / feature request needs status assignment
+- Periodic review of `needs-triage` tasks
+- Re-triage when new info arrives on a `needs-info` task
+
+## When NOT to Use
+
+- QUICK-routed tasks (Fast Path Guarantee — they go straight to
+  `/apt:quick` with no triage)
+- Tasks already in a terminal state (`wontfix` or `ready-for-agent`
+  with an active agent run)
+
+## 5-state machine
+
+```
+                                  ┌──→ ready-for-agent  (terminal)
+                                  │
+  needs-triage ──⇄── needs-info ──┼──→ ready-for-human  (terminal)
+       │                          │
+       │                          └──→ wontfix           (terminal)
+       │
+       ├──→ ready-for-agent  (direct)
+       ├──→ ready-for-human  (direct)
+       └──→ wontfix          (direct)
+```
+
+All 8 valid transitions: see prose list below and
+`apt-triage-state-machine.test.ts` for the exhaustive matrix.
+
+States:
+
+- **needs-triage** — inbound default. No state assigned yet.
+- **needs-info** — triage agent identified missing info; blocked on
+  the reporter.
+- **ready-for-agent** — task is concrete enough for `/apt:plan` +
+  `/apt:execute`. Has acceptance criteria, files identified.
+- **ready-for-human** — task requires human judgment (design taste,
+  product decision, security review). NOT for an agent to ship.
+- **wontfix** — closed without implementation. Reason recorded.
+
+Valid transitions (8):
+
+1. `needs-triage` → `needs-info` (need more info)
+2. `needs-triage` → `ready-for-agent`
+3. `needs-triage` → `ready-for-human`
+4. `needs-triage` → `wontfix`
+5. `needs-info` → `ready-for-agent` (info supplied)
+6. `needs-info` → `ready-for-human`
+7. `needs-info` → `wontfix`
+8. `needs-info` → `needs-triage` (re-triage — reset)
+
+All other transitions are invalid and rejected.
+
+Categories (orthogonal to state): `bug` | `enhancement`.
+
+## v1 schema (with extensible metadata for v2)
+
+```jsonc
+{
+  "task_id": "string",
+  "state": "needs-triage | needs-info | ready-for-agent | ready-for-human | wontfix",
+  "category": "bug | enhancement",
+  "transitions": [
+    { "from": "needs-triage", "to": "needs-info", "at": "ISO-8601", "by": "user|agent", "reason": "string" }
+  ],
+  "extra": { /* v2 OSS contributor primitives go here — non-breaking schema extension */ }
+}
+```
+
+The `extra` field is the v2-extension slot. v2 will add:
+
+- `contributor_trust_tier` (number)
+- `repro_status` (string: not-reproduced | reproduced | needs-info)
+- `security_sensitive` (boolean)
+- `response_template_id` (string)
+
+v1 ignores these fields if present; v2 reads them. No schema migration
+needed.
+
+## Backend configuration
+
+`.aperant/config.json.task_tracking.backend` selects the mirror:
+
+| Backend | v1 behavior |
+|---|---|
+| `local-only` (default) | State mirrors to `.aperant/tasks/{task-id}/triage.json` only. Zero network dependency. |
+| `github-issues` | Returns `{status: 'not-implemented', backend: 'github-issues', v2_issue: '#TBD'}`. Implementation deferred to v2. |
+| `app-inbox` | Same as github-issues — stub returning not-implemented. |
+
+Skill body reads `task_tracking.backend` at the start of every
+invocation. If the backend's adapter is not implemented, the skill
+fails fast with the `not-implemented` envelope — it does NOT silently
+fall back to `local-only`.
+
+## Fast Path Guarantee — QUICK never enters triage (AC9, ID-05)
+
+When the router classifies a task as QUICK, the task NEVER enters this
+state machine. `/apt:quick` skips triage by design — it's the one-shot
+path for trivial fixes, and triage ceremony would violate the Fast
+Path Guarantee. apt-triage-quick-exempt.test.ts asserts this constraint
+holds.
+
+## Sub-files (MIT-attributed)
+
+- `AGENT-BRIEF.md` — what an agent does with each state
+- `OUT-OF-SCOPE.md` — what triage explicitly is NOT (decision-locking,
+  feature design, multi-task prioritization)
+
+## Skill body process
+
+1. Parse `task-id` from `$ARGUMENTS`.
+2. Read `.aperant/config.json.task_tracking.backend`.
+3. Read the current `triage.json` state (default `needs-triage`).
+4. Apply the requested transition via the `apt-tools triage` CLI
+   (sub-command on the dispatch map).
+5. Mirror to the backend if configured (local-only = write
+   `.aperant/tasks/{id}/triage.json`).
+6. Output the new state envelope.
+
+State transitions surface the autonomy-aware degradation table
+(`apt-discuss/appendices/grill-discipline.md`) when the transition
+needs the user's judgment (e.g., moving to `wontfix` without
+escalation).

package/skills/apt-update/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -69,6 +70,8 @@ Build the flags list from the runtime ids (e.g. `--claude --codex`) and run:
 node .aperant/deps/node_modules/@aperant/framework/bin/apt-tools.mjs init . <flags>
 ```
 
+**Do NOT add `--yes`, `--solo`, `--team`, or any other Class A flag.** This command is meant to refresh runtime files only — adding `--yes` triggers a config schema migration that can silently flip `share.visibility` to `solo` and re-write `.gitignore`, which is exactly the 0.6.0/0.6.1 dogfood bug. If `init` returns a `requires_input` envelope (schema drift), surface it to the user verbatim and stop; let them decide team vs solo with the explicit flag. From 0.6.4 onward `--yes` infers visibility from existing git tracking, but the skill must still not add it — keep this command scoped to runtime refresh.
+
 Parse the init JSON. Capture for each runtime:
 - `install_root` (shortened to the basename, e.g. `.claude`)
 - `file_count`

package/skills/apt-verify/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: "apt-verifier"
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -18,6 +19,9 @@ argument-hint: "apt:verify [--fast | --cross-verify]"
 gates: 
   - consistency-check
   - all-subtasks-complete
+config_keys:
+  - verification.evidence_capture
+  - verification.max_iterations
 ---
 <objective>
 Verify that the implementation matches the spec, all tests pass, code quality checks succeed, and sign off on the build.

package/skills/apt-verify-proof/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: require-existing
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -16,6 +17,9 @@ execution_modes:
 allowed-tools: "Bash, Read, Write, Edit, Grep, Glob, Task"
 argument-hint: "apt:verify-proof [--multi-model | --video]"
 gates: []
+config_keys:
+  - verification.open_report
+  - verification.report_formats
 ---
 
 # Proof Verification

package/skills/apt-watch-ci/SKILL.md

@@ -0,0 +1,163 @@
+---
+name: apt:watch-ci
+description: "Post-ship CI watcher — polls PR checks, auto-fixes red, pushes, reschedules"
+apt-skill-version: {{APT_VERSION}}
+stage: ship
+intent: x-watch-ci
+when_to_use: "A PR has been shipped and CI is running. Use to watch its checks on a recurring tick, auto-fix red checks from first red, push fixes, and reschedule until green / merged / closed / 5 attempts / 4h wall."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: require-existing
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:watch-ci [--pr N | --tick --pr N | --stop --pr N | --resume --pr N]"
+gates: []
+config_keys:
+  - ci_watch.after_ship
+  - ci_watch.auto_merge_on_green
+---
+
+# /apt:watch-ci — Post-ship CI Watcher
+
+You are a **post-ship CI watcher**. After a PR has been opened by `/apt:ship`, you watch its checks on a recurring tick, auto-fix red checks from the first red, push the fix, and reschedule yourself until the PR is green / merged / closed, or you hit the 5-attempt / 4h wall budget.
+
+This skill is **one-tick-per-invocation** (D-01). It MUST NOT enter a polling loop. The recurring beat is delivered externally — by Claude Code's `CronCreate` on cron-capable hosts, by Pi's `pi-schedule-prompt` on Pi, or by the user re-invoking `/apt:watch-ci --tick --pr N` on non-cron hosts. Each invocation does at most one of: poll + classify + maybe-fix + push + reschedule, then exits.
+
+The locked decisions backing every section are in `.aperant/context/notes/framework-post-ship-ci-watcher.md` (D-01..D-08).
+
+---
+
+## Your environment
+
+- **Working directory:** the task's worktree (or the project root if this is a non-worktree task).
+- **State files:** `.aperant/ci-watches/{pr}.json` (per-PR state, D-04); `.aperant/ci-watches/{pr}.lock` (per-PR atomic lock, D-05). Both ephemeral — they are NOT committed.
+- **Events:** every tick appends a `ci-watch.tick` event to `.aperant/events/{today}.jsonl`; `start` appends `ci-watch.armed`; the fix-and-push path appends `ci-watch.fix-pushed`; terminal actions append `ci-watch.stopped` with a `reason`.
+- **CLI surface:** `apt-tools ci-watch start|stop|status|tick --pr N`. The skill body shells out to those subcommands — DO NOT re-implement the classifier in your prompt; the cmd already does it.
+
+---
+
+## §1. Resolve mode
+
+Parse the flags:
+- No flag → "start a watch for the active task's PR" (resolve PR number from `.aperant/state.json` active task's `pr_url` field).
+- `--tick --pr N` → run one tick for PR N. This is the cron payload's invocation form.
+- `--stop --pr N` → tear down the watch.
+- `--resume --pr N` → clear the `paused: true` flag and return to normal tick.
+
+If no PR can be resolved (no active task, no `pr_url`), print an error and exit — there is nothing to watch.
+
+---
+
+## §2. Lock acquire
+
+For everything except `status`, the imperative work happens inside `apt-tools ci-watch tick`, which acquires the per-PR lock itself. If `tick` returns exit code 2 with `{status:"busy", reason:"lock-held"}`, another invocation is already running for this PR. Print:
+
+```
+Watcher already running for PR {N} (held by sessionId={x}, pid={y}); exiting.
+```
+
+…and exit. Do NOT block, retry, or kill the holder.
+
+---
+
+## §3. One-tick semantics (the heart of D-01)
+
+For the `--tick` mode, execute exactly the following sequence — once — inside this single skill invocation:
+
+1. **Poll.** Call `gh pr checks <N> --json name,bucket,state,conclusion,detailsUrl` and `gh pr view <N> --json state,reviewDecision`. On any `gh` failure, write the captured stderr to a temp file and let the cmd's `tick` route to `infra-backoff` (it surfaces the same action when the gh payload is unavailable).
+2. **Classify + state update.** Call `apt-tools ci-watch tick {worktree} --pr {N}`. The cmd internally:
+   - acquires the per-PR lock (BUSY → exit 2 → step §2);
+   - reads the per-PR state file;
+   - runs the stop-matrix classifier (`packages/framework/src/cli/ci-watch/stop-matrix.mjs`);
+   - applies the action's state mutation (attempts++, last_status fingerprint, paused, etc.);
+   - releases the lock;
+   - returns `{status, action, attempts_used, next_tick_at, reason}`.
+3. **Branch on `action`** — see §4 (terminal), §5 (fix), §6 (non-counting), §7 (pause/resume).
+4. **Reschedule (next tick).** On Claude Code: refresh the `CronCreate` entry's next-fire timestamp (CronCreate is idempotent on the same payload). On Pi: do the equivalent via `pi-schedule-prompt`. On other hosts: print `Next tick: run /apt:watch-ci --tick --pr {N} when you return.` Do NOT register a cron on a non-cron host — the framework would be lying.
+5. **Emit event.** `apt-tools event append . --type ci-watch.tick --data '{...}'` with the cmd's envelope as the data payload. Non-fatal if it fails.
+
+---
+
+## §4. Terminal branches (green / merged / closed / *-cap / identical-log)
+
+When `action ∈ {green, merged, closed, attempts-cap, wall-cap, identical-log}`:
+
+- **green** — print "CI green for PR {N}." If `ci_watch.auto_merge_on_green` is `true` in `.aperant/config.json`, run `gh pr merge {N} --auto --squash` then suggest `/apt:close-task`. Else print the exact D-08 text:
+
+  ```
+  ✅ CI green — merge in browser or run /apt:close-task post-merge
+  ```
+
+- **merged** / **closed** — print a one-line summary. No PR comment needed.
+
+- **attempts-cap** / **wall-cap** / **identical-log** — these are bail conditions. Leave a PR comment via `gh pr comment {N} --body "<summary>"` describing why the watcher stopped (attempt count, deadline, fingerprint). The user comes back to find a structured note in the PR.
+
+In all terminal cases:
+- Stop the host scheduler (`CronDelete` on Claude Code, `pi schedule remove` on Pi, no-op elsewhere).
+- The cmd already deleted the state file when it returned `status: 'stopped'`. Do NOT re-delete it.
+- Emit `ci-watch.stopped` event with the matching `reason`.
+
+---
+
+## §5. Fix-and-push (D-02 — the auto-fix path)
+
+When `action === 'fix'` (or `diverged-rebased`/`diverged-bailed`):
+
+1. **Fetch the failed-check log.** From the gh payload, find the failed check's `detailsUrl` and call `gh run view {runId} --log` to capture the log into a temp file.
+2. **Shell out to the host CLI** to fix it. The watcher does NOT inline a custom fix prompt; it hands the worktree + failed-log to the same CLI binary that's running this skill (detected by `apt-tools host-detect`). Pseudocode:
+
+   ```bash
+   <host-cli-bin> --print "Fix this CI failure for PR {N}. The failed-run log is at {log_path}. Use the worktree at {worktree}. Land + push a commit with the fix." \
+     --cwd {worktree}
+   ```
+
+   The fix-CLI is responsible for the actual edits + verification + commit + push. This is a clean shell-out boundary — the watcher trusts the fix-CLI to land a commit (or to bail with a non-zero exit code, which the watcher treats as "no progress made this tick").
+3. **Did the fix change anything?** Run `git -C {worktree} status --porcelain`. If empty, the fixer made no changes → the next tick's classifier will see the same failure log and emit `identical-log`. Do NOT push.
+4. **Push.** `git -C {worktree} push origin {branch}`. On push failure, the next tick will route through `infra-backoff`.
+5. **Emit event.** `apt-tools event append . --type ci-watch.fix-pushed --data '{pr, attempts, commit_sha}'`.
+6. **Reschedule** per §3 step 4.
+
+For `diverged-rebased`: the cmd already returned the verb; the orchestrator runs `git -C {worktree} fetch && git rebase origin/{base}` BEFORE the fix step. On conflict the action becomes `diverged-bailed` and the watcher exits with a PR comment summarizing the conflict.
+
+---
+
+## §6. Non-counting branches (flake-skip / infra-backoff)
+
+When `action === 'flake-skip'` or `'infra-backoff'`:
+
+- **flake-skip:** Skip the fix path entirely. Reschedule at the normal interval. No PR comment.
+- **infra-backoff:** Same skip — but the next tick interval is doubled by the cmd (it wrote `next_tick_interval_ms *= 2` to state). The cron host re-invocation reads it. After one retry, if the same infra signal persists, post a PR comment marking the failure as `infra-incident`; do NOT keep doubling forever.
+
+---
+
+## §7. --stop / --resume flags
+
+- `--stop --pr N` — releases scheduler handle (`CronDelete` on CC, `pi schedule remove` on Pi, no-op elsewhere), deletes state file, emits `ci-watch.stopped` event with `reason:"user-stop"`. Idempotent — calling `--stop` on a PR with no active watch is fine.
+- `--resume --pr N` — only valid when state has `paused: true` (set by `reviewer-pause`). Clears the flag, returns to normal tick. Error envelope if no paused state for the PR.
+
+When the classifier returns `reviewer-pause`, the state's `paused: true` is set by the cmd, but the scheduler is NOT removed — the cron payload keeps firing, and each tick the cmd checks `paused` and exits early with action `reviewer-pause`. Cheaper than re-registering on `--resume`.
+
+---
+
+## §8. Single-execution-mode contract
+
+Reiterating because this is the most easily-broken invariant:
+
+- One tick = one invocation. **Do not** wrap the §3 sequence in a `while`/`until` loop.
+- **Do not** sleep + re-invoke yourself inside a single session.
+- The recurring beat is delivered by host cron OR by the user re-invoking the skill manually. The watcher's value comes from the host scheduler — it does not impersonate one.
+
+If you find yourself wanting to add "and then wait 5 minutes and run again," STOP. The skill is finished after one tick. Exit.
+
+---
+
+## Notes for the orchestrator
+
+- All gh CLI calls run with the host's existing auth. The watcher introduces no new secret material (per task `dimensions_covered.token-encryption.crossed: false`).
+- `auto_merge_on_green` is snapshotted from `.aperant/config.json` at `start` time (state file's `auto_merge_on_green` field). Changing the config mid-watch does NOT retroactively affect armed watches — re-run `start` to pick up the new value.
+- The fix-CLI shell-out is the cleanest abstraction we have for portability. It's NOT a sub-agent. On Claude Code that means another `claude` invocation; on Codex/Gemini/OpenCode/Pi, the equivalent binary. Detection lives in `apt-tools host-detect`'s `cli` field.

package/skills/apt-zoom-out/SKILL.md

@@ -0,0 +1,130 @@
+---
+name: apt:zoom-out
+description: "Orient yourself in an unfamiliar area of the codebase — load CONTEXT.md, map modules + callers, output a one-page orientation"
+apt-skill-version: {{APT_VERSION}}
+stage: plan
+intent: investigate
+when_to_use: "The user is dropped into a part of the codebase they don't know and wants a one-page architectural orientation before planning or editing. Natural-language triggers: 'give me a broader picture of X', 'I'm lost in this area', 'explain how this fits'."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_track: STANDARD
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Grep, Glob"
+argument-hint: "apt:zoom-out [area-name]"
+gates: []
+---
+
+# Zoom-Out — One-page Architectural Orientation
+
+Tiny skill. High signal. The user named an area; you produce a one-page
+orientation so they (or a future agent) can plan or edit without
+re-learning the codebase from scratch.
+
+**Pocock adoption note.** This skill descends from Matt Pocock's `zoom-out`
+discipline. Aperant's router is dynamic and LLM-driven, so unlike Pocock's
+upstream this skill is **router-invocable** (no `disable-model-invocation:
+true` flag). The work-intent — "give me a broader picture of X" — is
+genuine and the router resolves natural-language triggers without forcing
+the user to remember the verb name.
+
+## When to Use
+
+- Dropped into a new module / package / area of the monorepo
+- About to plan a feature that crosses an unfamiliar boundary
+- The codebase has CONTEXT.md (Pocock glossary) and you want to load it
+  alongside the structural map
+
+## When Not to Use
+
+- The area is one you know well — `/apt:plan` already does targeted
+  investigation
+- You need to lock decisions (use `/apt:discuss` with the
+  `appendices/grill-discipline.md` posture loader instead)
+- The user wants to refactor proactively — that's `/apt:improve`
+
+## Process
+
+### 1. Parse the area name
+
+Extract the area from `$ARGUMENTS`. The area is a noun phrase, not a
+file path: e.g., `"chat session lifecycle"`, `"sparring engine"`,
+`"feature registry"`. If the argument is a file path, narrow the
+orientation to the file's enclosing module.
+
+### 2. Load CONTEXT.md (if present)
+
+If `CONTEXT.md` exists at the project root, read it and pre-load any
+term-blocks whose `Term` matches keywords in the area name (or whose
+`Aliases to avoid` field hints at the area). Carry these terms forward
+into the orientation report so the reader sees the vocabulary the
+codebase actually uses.
+
+If `CONTEXT.md` does not exist, skip silently — orientation still works,
+just without the glossary anchor.
+
+### 3. Map modules and callers
+
+Run Glob + Grep to identify:
+
+- **Entry points** — files in the area that other modules import (high
+  fan-in: many `import`-ers).
+- **State owners** — files that declare the area's persistent
+  state (Zustand stores, Convex queries, libSQL tables).
+- **External boundaries** — files that touch external systems (HTTP,
+  IPC, native modules, child processes).
+- **Known fragile areas** — search for `// TODO`, `// FIXME`, `// HACK`
+  comments + any recent commits touching the area (last 30 days).
+
+### 4. Emit the one-page orientation
+
+Output to stdout (no file written — this is a read-only orientation):
+
+```markdown
+# Orientation: {area name}
+
+## Purpose
+{One paragraph: what does this area exist to do?}
+
+## Entry points
+- `{path}` — {one-line role}
+- `{path}` — {one-line role}
+
+## State owners
+- `{path}` — {one-line: what state, what scope}
+
+## External boundaries
+- `{path}` — {one-line: which external system, what direction}
+
+## Known fragile areas
+- `{path}:{line}` — `// TODO` / `// FIXME` summary + age
+- {recent-commit-shortlog one-liner if relevant}
+
+## Glossary (from CONTEXT.md)
+- **{Term}** — definition + aliases-to-avoid
+- {…}
+
+## Pointers for the next agent
+- {one-line: where to start reading}
+- {one-line: which test file to read first}
+- {one-line: which CONTEXT.md term resolves the most ambiguity}
+```
+
+The orientation MUST fit on one screen. If it doesn't, you've gone too
+deep — re-scope the area name and try again.
+
+## Output contract
+
+- **Read-only.** This skill never writes files. It is a context-loader,
+  not a planner.
+- **Stops at orientation.** Do NOT pivot into `/apt:plan` automatically.
+  The user invokes `/apt:plan` (or `/apt:improve`) as a follow-up if the
+  orientation surfaces a planning opportunity.
+- **No grill posture.** This skill does NOT load
+  `apt-discuss/appendices/grill-discipline.md` — orientation is
+  descriptive, not normative. Locking decisions is `apt:discuss`'s job.