@aperant/framework 0.6.3 → 0.6.5

package/skills/apt/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
@@ -129,6 +130,7 @@ Show available commands table:
 | `apt:resume` | Restore context after session break |
 | `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 |
 | `apt:setup` | Change framework preferences |
 
 Show current state summary and autonomy flags (`--supervised`, `--guided`, `--autonomous`, `--yolo`).
@@ -139,13 +141,118 @@ Show current state summary and autonomy flags (`--supervised`, `--guided`, `--au
 
 The user invoked a specific skill by name (e.g., `/apt plan`, `/apt resume`,
 `/apt:ship`). The router matched the first word against the installed skill
-set and filled in `skill`, `skill_args`, `spawn_agent`, and `agent`.
+set and filled in `skill`, `skill_args`, `spawn_agent`, `agent`, AND
+`task_context` + (optional) `default_track`.
 
-**If `spawn_agent` is true:**
-Spawn the appropriate agent from the routing result. Pass `skill_args` as context.
+Dispatch on `task_context` — never just on `spawn_agent`. The four-branch
+policy below is hardcoded contract; do NOT improvise. See
+`docs/frameworks/spec-gaps.md#g25` for the defect that motivated this.
 
-**If `spawn_agent` is false:**
-Invoke the skill directly: call `apt:{skill}` with `skill_args`.
+### Missing `task_context` — fail-closed
+
+When the envelope's `task_context` is null (the `?? null` fallback in
+`route.mjs:skillIndex.taskContextOf`), print verbatim and STOP. Do NOT
+invoke the skill:
+
+```
+[APT] ERROR — skill "apt:{skill}" has no task_context declared in SKILL.md frontmatter.
+       Cannot dispatch safely until the policy is set. Run /apt:author-skill validate
+       packages/framework/skills/apt-{skill}/SKILL.md to see required keys.
+```
+
+**Note:** In practice, a skill missing `task_context` is dropped by
+`discoverSkills` during the Zod schema validation step and will never reach
+the skill-passthrough branch — it will be absent from `knownSlugs`. The
+user sees the skill disappear silently from routing; run
+`apt-tools route .` to surface dropped skills logged to
+`.aperant/logs/route-dropped.jsonl`. The `task_context: null` path is
+reachable if the field is marked optional in a future schema version —
+this error fires in that case.
+
+### `task_context = none`
+
+No task semantics. Invoke the skill directly with `skill_args` (or spawn
+`agent` when `spawn_agent` is true). No `task create`, no worktree banner.
+
+### `task_context = self-managed`
+
+The skill manages its own task / worktree lifecycle (e.g. `apt:run` calls
+`task create` in its own Step 2; `apt:pr-review` sets up a PR-scoped
+worktree). Dispatch identically to `none` — the skill's own SKILL.md is
+responsible for any task record + worktree banner.
+
+### `task_context = create-new`
+
+Resolve the track, then create a fresh task record before invoking the skill.
+
+**Track resolution chain (first match wins):**
+
+1. Explicit user flag in `skill_args` — `--quick` → `QUICK`, `--deep` → `DEEP`,
+   `--debug` → `DEBUG`.
+2. `envelope.default_track` if present (the skill's declared default).
+3. Per-slug hardcoded fallback:
+   - `quick` → `QUICK`
+   - `debug` → `DEBUG`
+   - `plan` → `STANDARD`
+   - everything else with `task_context: create-new` → `STANDARD`
+
+Then run:
+
+```bash
+node packages/framework/bin/apt-tools.mjs task create . --description "{slug}" --track {track} --autonomy {autonomy} [--scope {scope}]
+```
+
+**Security note:** Do NOT interpolate `{skill_args}` directly into `--description "..."`. `skill_args` is verbatim user input and can contain double-quote characters that break out of the argument boundary and inject extra flags (e.g. `--autonomy`, `--scope`). The task slug is sufficient as the description; `skill_args` is passed to the skill separately after the task record is created.
+
+(Use `--scope framework` only when the user is on a framework-scoped task —
+otherwise omit and let the default `project` scope apply.)
+
+Parse `task_id`, `task_dir`, and (if present) `worktree.worktree_path` /
+`worktree.branch` / `worktree.base_branch` from the result. Print the
+worktree banner when `worktree` is returned:
+
+```
+[APT] Working in isolated worktree: {worktree_path}
+[APT] Task branch: {branch} (from {base_branch})
+```
+
+Then invoke `apt:{skill}` with `skill_args` + the new task context
+(`task_id`, `task_dir`, `worktree_path`). When `spawn_agent` is true, spawn
+`agent` with the same context.
+
+### `task_context = require-existing`
+
+Resolve which active task this invocation refers to, then dispatch. Read
+`state.active_tasks` from `.aperant/state.json`.
+
+**Active-task resolution chain (first match wins):**
+
+1. `--task-id <id>` flag present in `skill_args` → use it. If `<id>` is not
+   in `state.active_tasks`, error and stop.
+2. `state.active_tasks` has exactly one entry AND that entry's
+   `lifecycle_phase` is non-terminal (`planning`, `executing`, `verifying`,
+   `reviewing`) → use it. If the single entry is in a terminal phase
+   (`shipped-pending-merge` or `rejected`), fall through to step 4.
+3. `state.active_tasks` has more than one entry with exactly one in a
+   non-terminal lifecycle phase (`planning`, `executing`, `verifying`,
+   `reviewing`) → use it.
+   (Terminal phases in `active_tasks` are `shipped-pending-merge` and
+   `rejected`. Note: `completed` tasks are removed from `active_tasks`
+   entirely at close and can never appear here.)
+4. Otherwise, print the numbered menu and STOP. Auto-mode (autonomy 2/3)
+   does NOT bypass this prompt — multi-task ambiguity is the user's call,
+   never the framework's guess:
+
+   ```
+   [APT] Multiple active tasks — pick one with `--task-id <id>`:
+     1. {task-id-1}  {description}  ({lifecycle_phase})
+     2. {task-id-2}  {description}  ({lifecycle_phase})
+     ...
+   ```
+
+Once resolved, print the worktree banner if the task has a `worktree_path`,
+then invoke `apt:{skill}` with `skill_args` + the resolved `task_id`. When
+`spawn_agent` is true, spawn `agent` with the same context.
 
 ---
 

package/skills/apt-author-skill/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
 default_execution_mode: step
 execution_modes:
   - auto
@@ -129,6 +130,16 @@ the author sees the full checklist of gaps to fill. Group by section:
 The generated structural test only checks tags and numbered steps — the
 TODOs are the semantic gaps the author must close.
 
+**Required frontmatter field — `task_context`.** The scaffold ships with
+`task_context: create-new` as the safest default (the new skill will get a
+fresh task record + worktree via `apt-tools task create` when invoked as
+`/apt <slug>`). Verify this is correct for your skill before merging — the
+allowed values are `create-new | require-existing | self-managed | none`.
+See `packages/framework/docs/skill-passthrough.md` for the four-policy
+contract and the orchestrator dispatch behavior. Missing or wrong values
+are caught by the structural test in
+`packages/framework/src/__tests__/skill-frontmatter-task-context.test.ts`.
+
 ## 4. Show the Structural Test
 
 Read the generated structural test file and echo its contents so the

package/skills/apt-bootstrap/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

package/skills/apt-classify/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: false
 internal: true
 spawns_agent: false
 agent_name: null
+task_context: none
 default_execution_mode: auto
 execution_modes:
   - auto

package/skills/apt-close-task/SKILL.md

@@ -9,12 +9,13 @@ 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, Grep, Glob, Write"
-argument-hint: "apt:close-task [--all | --task <id>]"
+argument-hint: "apt:close-task [--all | --task <id>] [--narrate-only]"
 gates: []
 ---
 <objective>
@@ -69,6 +70,7 @@ Internally, close-merged does:
    a. `apt-tools task close . --id {task-id} --verdict approved` (respects `task_isolation.auto_close_phase`).
    b. Strips `config.pr_review.authorship_overrides['pr-{N}']` if present.
    c. Emits `task.closed.merged` event.
+   d. Appends a `pending_narration[]` ledger row to `.aperant/state.json` so `--narrate-only` (see §4) can pick it up. Additive only; never blocks the close.
 3. When `state !== 'MERGED'`, the task stays in `shipped-pending-merge` with a skip reason the user can inspect.
 
 ## 2.5 Narrate completed phases (moved from /apt:ship in C56 B5)
@@ -84,6 +86,8 @@ For each entry in the close-merged envelope's `closed[]` whose record has a non-
 
 Do NOT wait on the narrator. Its status lands in `.aperant/digests/.last-run.json`. Skip narrator spawn entirely when `closed[]` is empty or no closed item has a phase_id.
 
+After step 2.5 spawns narrators for the just-closed candidates, the skill ALSO drains `state.pending_narration[]` (entries the passive sweep parked there) — see §4.
+
 ## 3. Summary
 
 close-merged emits an envelope with:
@@ -94,6 +98,34 @@ close-merged emits an envelope with:
 
 Report the summary verbatim. If anything landed in `skipped[]` with a recoverable reason (`offline`, `rate_limited`), suggest the user re-run once the network clears.
 
+## 4. Narrate-only mode
+
+When invoked with `--narrate-only`, skip §1 (no `gh pr view` polling) and §2 (no destructive close path). The deterministic close already ran via the passive post-merge sweep — your job is to drain the `state.pending_narration[]` ledger the sweep parked.
+
+Flags:
+- `--narrate-only --all` (default when `--narrate-only` is bare) — drain every ledger entry.
+- `--narrate-only --task <id>` — drain only the entry for `<id>`.
+
+Per ledger entry `{ task_id, scope, phase_id, closed_at, pr_number }`:
+
+1. Run `apt-tools features-audit . --apply-stubs --task <task_id>` so the feature registry catches whatever the closed task introduced. If the subprocess exits non-zero, skip the entry with `reason: 'features-audit-failed'` — never block narration on registry update.
+2. When `phase_id` is non-null, spawn `apt-team-docs-narrator` (background, fire-and-forget) using the same shape as §2.5: `subagent_type: apt-team-docs-narrator`, `run_in_background: true`, `description: Narrate shipped phase {phase_id}`, `prompt: Run in phase-ship mode with --phase {phase_id} --scope {scope}.`. When `phase_id` is null, skip the spawn with `reason: 'no-phase-id'` (quick tasks have no phase to narrate).
+3. On successful spawn (or successful no-phase skip), drain the row via `apt-tools task narration-drain . --task <task_id>` which acquires `withFileLock(state.json)` and removes the matching `pending_narration[]` entry. On spawn failure, leave the row in place with `reason: 'narrator-spawn-failed'` so the user can re-invoke.
+
+Emit a summary envelope:
+
+```json
+{
+  "status": "ok",
+  "command": "close-task-narrate-only",
+  "narrated": [{ "task_id": "<id>", "phase_id": "<p|null>", "scope": "<s>" }],
+  "skipped": [{ "task_id": "<id>", "reason": "no-phase-id|features-audit-failed|narrator-spawn-failed" }],
+  "remaining": <ledger.length>
+}
+```
+
+The regular `apt:close-task` flow ALSO falls through to this drain step at the tail of §2.5 — so users who run the skill manually after the sweep get narration without remembering the flag. The `--narrate-only` flag exists for the explicit "drain only, don't poll gh" case.
+
 </process>
 
 <notes>

package/skills/apt-create-docs/SKILL.md

@@ -9,6 +9,7 @@ user_invocable: true
 internal: false
 spawns_agent: true
 agent_name: apt-docs-author
+task_context: create-new
 default_execution_mode: auto
 execution_modes:
   - auto

package/skills/apt-debug/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: DEBUG
 default_execution_mode: auto
 execution_modes:
   - auto
@@ -19,6 +21,19 @@ gates: []
 ---
 <objective>
 Debug an issue using the scientific method: observe symptoms, form hypotheses, test them systematically, and reach a conclusion. State persists across context resets via `.aperant/debug/{session-id}/DEBUG.md`.
+
+**Diagnose-discipline posture loader (Pocock adoption AC10).** You MUST
+load `appendices/diagnose-discipline.md` into reasoning context at
+session start. It carries the 6-phase loop (Reproduce → Minimise →
+Hypothesise → Instrument → Fix → Regression-test) and the **Phase-1
+prerequisite** constraint: do NOT advance from Observe (Section 2) to
+Hypothesize (Section 3) until DEBUG.md records `repro_loop_verified:
+true`. The appendix carries the rationale, the anti-pattern list
+(sprint-to-hypothesis, stack-trace cargo cult, test-the-fix-not-the-bug,
+logging-without-minimising), and the distinction between Phase 1
+"reproduce" and Phase 2 "minimise". Open question #1 was verified —
+apt:debug's existing Section 2 conflates symptom-gathering with
+reproduction, so loading this appendix is non-trivial.
 </objective>
 
 <your_environment>
@@ -57,18 +72,38 @@ mkdir -p .aperant/debug/{session-id}
 mkdir -p .aperant/debug/{session-id}/checkpoints
 ```
 
-## 2. Observe — Gather Symptoms
+## 2. Observe — Gather Symptoms + Phase 1 (Reproduce — prerequisite)
+
+Collect all available evidence about the bug, then establish a
+**reliable repro loop as a hard prerequisite** before advancing to
+Section 3 (Hypothesize). The Phase-1-reproduce constraint comes from
+`appendices/diagnose-discipline.md` and is load-bearing — you do NOT
+emit any hypothesis until DEBUG.md records `repro_loop_verified: true`.
 
-Collect all available evidence about the bug:
+Sub-steps (the existing 4 + 1 prerequisite check):
 
 1. **User description:** Extract from `$ARGUMENTS` what the issue is
 2. **Error output:** If the user provided error messages, record them verbatim
-3. **Reproduce:** Attempt to reproduce the issue:
-   - Run relevant test commands
-   - Check logs, console output
-   - Identify the exact failure point
+3. **Phase 1 — Reproduce (prerequisite, per appendices/diagnose-discipline.md):**
+   Establish a reliable repro loop. The loop MUST be:
+   - Deterministic (same input → same failure)
+   - Cheap (under 10 seconds preferred; certainly under 60)
+   - Minimal (no irrelevant setup; just enough to fail)
+   Record the repro command + verification in DEBUG.md as
+   `repro_command: "..."` and `repro_loop_verified: true`. If you
+   cannot reproduce reliably, do NOT proceed to Section 3 — instead,
+   loop here: gather more environment context, add logging to the
+   target environment, ask the user for repro details. Hypothesis-driven
+   debugging without a reliable repro is just hope, dressed up as
+   method.
 4. **Context:** Note environment details (branch, recent commits, dependencies)
 
+After Phase 1 succeeds, run **Phase 2 — Minimise** (also from the
+appendix): strip the repro to the smallest case that still fails.
+Record the minimised repro in DEBUG.md as `minimised_repro: "..."`.
+Phase 2 prevents Sections 3-5 from anchoring on the first plausible
+cause inside a 200-line repro.
+
 ```bash
 git log --oneline -10
 git diff --stat

package/skills/apt-debug/appendices/diagnose-discipline.md

@@ -0,0 +1,119 @@
+<!--
+Adapted from Matt Pocock's MIT-licensed skill suite:
+https://github.com/mattpocock/skills/blob/main/skills/engineering/diagnose
+Licensed under MIT. Modifications: ported as an apt:debug posture loader
+so the 6-phase loop attaches to the existing 5-phase apt:debug body
+without forking apt:debug's control flow. Aligned with apt:debug's
+DEBUG.md state file and checkpoint conventions.
+-->
+
+# Diagnose Discipline — apt:debug posture loader (6-phase loop)
+
+This appendix loads into `apt:debug`'s reasoning context as a posture
+upgrade. The existing apt:debug body has 5 phases (Observe → Hypothesize
+→ Checkpoint → Test → Conclude) but its Section 2 "Observe" conflates
+symptom-gathering with reproduction. Open question #1 was verified — the
+gap is real, the appendix is non-trivial.
+
+This appendix carries the 6-phase Pocock discipline. The skill body
+loads it and uses Phase 1 (Reproduce) as a **hard prerequisite** before
+advancing from Observe to Hypothesize.
+
+## The 6-phase loop
+
+1. **Reproduce.** Establish a reliable repro loop. Until you can
+   trigger the bug at will, no hypothesis is testable — you'd be
+   guessing about a moving target. The loop MUST be:
+   - Deterministic (same input → same failure)
+   - Cheap (under 10 seconds preferred; certainly under 60)
+   - Minimal (no irrelevant setup; just enough to fail)
+
+2. **Minimise.** Once you can repro, strip the repro to the smallest
+   case. Remove every component that isn't load-bearing for the
+   failure. A 200-line repro is a hypothesis space; a 10-line repro is
+   a near-confirmed cause.
+
+3. **Hypothesise.** ONLY after minimise: write 3-5 ranked falsifiable
+   hypotheses. Each hypothesis must:
+   - Predict an observable consequence
+   - Be testable by changing ONE variable
+   - Be ordered by prior probability + cost-to-test
+
+4. **Instrument.** Add the minimum logging / breakpoint / probe to test
+   the highest-ranked hypothesis. Change ONE variable. Re-run the
+   minimal repro. Observe.
+
+5. **Fix.** When a hypothesis confirms, write the fix. Run the minimal
+   repro again — it must now PASS (no more failure). Run the full test
+   suite — no new regressions.
+
+6. **Regression-test.** Write a test that pins the fix. The test must
+   fail on the pre-fix code and pass on the fixed code. This is what
+   stops the bug from coming back six months later when someone
+   refactors.
+
+## The Phase-1 prerequisite (load-bearing)
+
+apt:debug's body enforces this constraint: **you do NOT advance from
+Observe to Hypothesize until Phase 1 produces a reliable repro loop**.
+
+If you cannot reproduce reliably:
+
+- Spend the budget on getting the repro working before guessing causes
+- Add logging in the production / target environment to gather more
+  evidence of the failure trigger
+- Ask the user for more context (when does it happen? on what input?
+  intermittent or consistent?)
+
+It is better to spend 80% of your debug budget on the repro and 20% on
+the fix than to spend 100% guessing at causes. Hypothesis-driven
+debugging without a reliable repro is just hope, dressed up as method.
+
+## Distinguishing Phase 1 from apt:debug's existing "Observe"
+
+apt:debug's existing Section 2 collects symptom evidence (error
+messages, user reports, environment). That's still valuable — it's the
+*input* to Phase 1. But "I read the error and inferred the cause"
+DOES NOT count as a repro. The repro is a callable artifact: a
+command-line invocation, a test, a script — something the agent can
+run on demand to trigger the failure.
+
+## Distinguishing Phase 2 (Minimise) from Phase 3 (Hypothesise)
+
+These are different mental modes. Minimise asks "what's the smallest
+thing that still fails?" — a reductive activity. Hypothesise asks
+"WHY does it fail?" — an explanatory activity. Pocock's discipline
+separates them because skipping Phase 2 and going straight from "I can
+repro" to "here's why" tends to anchor on the first plausible cause
+and miss alternatives.
+
+## Practical consequence for the apt:debug body
+
+When this appendix is loaded, apt:debug's Section 2 (Observe) renames
+its "Reproduce" sub-step to **Phase 1 (Reproduce — prerequisite)** and
+adds a gate: the skill MUST NOT emit any hypothesis (Section 3) until
+DEBUG.md records a `repro_loop_verified: true` field.
+
+The appendix's Phase 2 (Minimise) becomes a new sub-section between
+apt:debug's Section 2 (Observe) and Section 3 (Hypothesize). DEBUG.md
+gains a `minimised_repro` field.
+
+apt:debug's Sections 3-5 (Hypothesize / Checkpoint / Test / Conclude)
+align with Phases 3-6 of this appendix; no structural change there.
+
+## Anti-patterns this discipline prevents
+
+- **Sprint-to-hypothesis.** Agent reads the error, picks the first
+  plausible cause, writes a fix, and ships. The bug comes back two
+  days later under different inputs.
+- **Stack-trace cargo cult.** Agent assumes the line at the top of the
+  stack trace IS the bug. Often it's an effect, not a cause.
+- **Test the fix, not the bug.** Agent writes a test that proves the
+  fix works but doesn't exercise the original buggy condition. The
+  regression test is a no-op against the future regression.
+- **Logging without minimising.** Agent adds 50 log lines in a 200-line
+  repro, then drowns in noise. Minimise first; THEN instrument the
+  minimal repro.
+
+Loading this appendix and following its Phase 1 prerequisite cuts most
+of these failure modes by structural constraint.

package/skills/apt-design/SKILL.md

@@ -9,6 +9,8 @@ user_invocable: true
 internal: false
 spawns_agent: false
 agent_name: null
+task_context: create-new
+default_track: STANDARD
 default_execution_mode: step
 execution_modes:
   - auto