@aperant/framework 0.7.0 → 0.7.3

package/dist/plugin/skills/apt-release-notes/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: apt:release-notes
+description: "Persona-aware user-facing release notes — draft, compile, publish"
+apt-skill-version: {{APT_VERSION}}
+stage: ops
+intent: capture
+when_to_use: "The user wants to draft, compile, or publish persona-aware user-facing release notes for a project that opted in via /apt:setup."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+task_context: none
+default_track: DEEP
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:release-notes [--draft --pr <n> | --compile <tag> | --publish <tag>]"
+gates: []
+---
+
+<objective>
+Produce user-facing release notes for a project that opted in via
+`/apt:setup` → Batch 9 → "Publish user-facing release notes? Yes". This
+skill is separate from `/apt:docs changelog` — the dev-flavored
+`CHANGELOG.md` surface stays its responsibility; this skill owns the
+persona-voice-tuned narrative that ships to end users.
+
+Three modes:
+
+- `--draft --pr <n>` — write a per-PR fragment file (towncrier-style).
+  Usually called automatically by `/apt:close-task` on merge; rarely
+  invoked by hand.
+- `--compile <tag>` — at release time, read every accumulated fragment,
+  filter by the configured persona tier, write a single per-tag
+  narrative file, and clear the unreleased dir.
+- `--publish <tag>` — shell `gh release create/edit` to push the
+  compiled body to the GitHub Release.
+
+Rules of the road (locked):
+
+- **Per-project opt-in (spec ID-7).** Presence of `.aperant/personas.json`
+  does NOT auto-enable this skill. The toggle is
+  `config.changelog.release_notes.enabled` — opt-in is explicit via
+  `/apt:setup` Batch 9.
+- **No LLM calls in the CLI (spec ID-3).** The deterministic verbs
+  (`apt-tools release-notes draft|compile|publish`) handle file I/O only.
+  Persona-voice tuning is authored by you — the host LLM — using the
+  `appendices/persona-voice.md` loader.
+- **Triage bucket is non-negotiable (spec ID-6).** Fragments without a
+  recognized persona tag MUST surface in a `## Needs Triage` section at
+  compile time. Never silent-drop. This is the human curator's safety
+  net against trust collapse over time.
+- **Fast Path Guarantee (CLAUDE.md).** This skill is DEEP-track-only
+  surface area. `/apt:quick` never enters this skill; the
+  `apt-release-notes-quick-exempt.test.ts` regression test pins the
+  exemption.
+</objective>
+
+<your_environment>
+- **Working directory:** The project root
+- **apt-tools path:** `node packages/framework/bin/apt-tools.mjs` or the locally installed `apt-tools` binary.
+- **gh CLI dependency:** required only for `--publish`. The `publish` verb returns a graceful `{status: 'skipped', reason: 'gh-not-found'}` envelope when `gh` is unavailable — the skill never crashes the host on a missing binary.
+- **Output:** `docs/releases/_unreleased/PR-<n>.md` (fragments) + `docs/releases/<tag>.md` (compiled) + GitHub Release body (when published).
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `.aperant/config.json` — `changelog.release_notes.{enabled, output_dir, persona_filter, require_pr_field}` and the stage blocks.
+- `.aperant/personas.json` — persona roster + tier; used by `compile` to filter fragments.
+- `docs/releases/_unreleased/PR-*.md` — fragments accumulated since the last tag.
+- `PROJECT.md` (when present) — Core Value section feeds the hero narrative the host LLM authors at compile time.
+
+**Writes:**
+- `docs/releases/_unreleased/PR-<n>.md` — towncrier-style fragments (draft mode).
+- `docs/releases/<tag>.md` — per-tag compiled narrative (compile mode).
+- GitHub Release body via `gh release create/edit` (publish mode).
+</state_files>
+
+<process>
+
+## 0. Hard-Gate + Opt-in Check
+
+No hard gates (`gates: []`). Before running ANY mode, confirm the project opted in:
+
+```bash
+rn_enabled=$(jq -r '.changelog.release_notes.enabled // false' .aperant/config.json)
+if [ "$rn_enabled" != "true" ]; then
+  echo "[apt:release-notes] This project has not opted into user-facing release notes."
+  echo "                    Run /apt:setup → 'Changelog & Release Notes' to enable."
+  exit 0
+fi
+```
+
+When opted out, exit cleanly — never crash, never write any file.
+
+## 1. Parse Flags
+
+The skill's three modes are mutually exclusive. Parse `$ARGUMENTS`:
+
+- `--draft --pr <n> --note "<text>" [--persona <name>] [--commits <sha,sha,...>] [--date <YYYY-MM-DD>]` → Draft mode (§2).
+- `--compile <tag>` → Compile mode (§3).
+- `--publish <tag> [--dry-run]` → Publish mode (§4).
+
+If no mode flag is passed, display a short usage message and exit.
+
+## 2. Draft Mode
+
+Used to write a per-PR fragment. Usually this is called automatically by `/apt:close-task` on merge (see `apt-close-task/SKILL.md` §2.6), but it can be invoked by hand for backfills or for manual fragments.
+
+Hand the inputs to the deterministic CLI:
+
+```bash
+node packages/framework/bin/apt-tools.mjs release-notes draft . \
+  --pr {pr_number} \
+  --note "{one-sentence user-impact note}" \
+  [--persona {persona-name}] \
+  [--date {ISO-date}]
+```
+
+The CLI is idempotent — re-running with identical inputs returns `{status: 'ok', written: false, reason: 'no-change'}`. Trust the envelope; do NOT manually inspect the file before running.
+
+When you (the host LLM) compose the note, consult `appendices/persona-voice.md` for the persona-voice posture loader. The fragment goes into the user-facing pipeline; voice-tune accordingly.
+
+## 3. Compile Mode
+
+Used at release time to fold every accumulated fragment into a single per-tag narrative. The CLI does the deterministic work — your job is the narrative pass on the compiled body if the user wants polish beyond the structured per-PR list.
+
+```bash
+node packages/framework/bin/apt-tools.mjs release-notes compile . --tag {tag}
+```
+
+The envelope reports:
+
+```json
+{
+  "status": "ok",
+  "command": "release-notes-compile",
+  "tag": "{tag}",
+  "path": "docs/releases/{tag}.md",
+  "fragments_total": N,
+  "fragments_in_body": M,
+  "fragments_in_triage": K,
+  "fragments_filtered": F,
+  "cleared_unreleased": true
+}
+```
+
+If `fragments_in_triage > 0`, ALERT the user before proceeding to publish — those fragments need persona curation. Offer two options:
+
+1. Edit the compiled file directly to move triage entries into the right tier section (and re-tag the persona in the original PR if appropriate).
+2. Proceed to publish with the triage section intact — sometimes the right call when the unmapped change is genuinely cross-cutting.
+
+If `fragments_total === 0`, gently note that there's nothing to compile yet (likely the user hasn't merged any PRs since the last release).
+
+## 4. Publish Mode
+
+Push the compiled body to the GitHub Release:
+
+```bash
+node packages/framework/bin/apt-tools.mjs release-notes publish . --tag {tag}
+```
+
+The CLI handles both `gh release create` (new release) and `gh release edit` (existing release). When `gh` is not on PATH, the envelope returns `{status: 'skipped', reason: 'gh-not-found'}` — surface the message to the user and suggest installing the GitHub CLI.
+
+For local-only verification, pass `--dry-run` to skip the network call and just confirm the body file exists.
+
+## 5. Re-invocation
+
+Each mode is safe to re-run:
+
+- `draft` — idempotent per spec AC2.
+- `compile` — overwrites `<tag>.md` and re-clears `_unreleased/`. Running compile twice in a row with no new fragments produces an empty body — careful.
+- `publish` — `gh release edit` is the second call's branch, so the GitHub Release body is replaced cleanly.
+
+</process>
+
+<appendices>
+- `appendices/persona-voice.md` — Aperant-authored posture loader for voice-tuning the note text per persona archetype.
+</appendices>
+
+<integration>
+| Skill | How it interacts |
+|-------|------------------|
+| `/apt:setup` Batch 9 | Writes the opt-in toggle + audience + persona-filter that this skill reads. |
+| `/apt:ship` §2.6 | Auto-drafts the `Release note: …` line in the PR body BEFORE this skill runs; ship blocks if `require_pr_field=true` AND no signal. |
+| `/apt:close-task` §2.6 | Invokes `apt-tools release-notes draft` on merge — drops the per-PR fragment automatically. |
+| `/apt:docs changelog` | The dev-flavored sibling. Stays its own surface; this skill does NOT touch `CHANGELOG.md`. |
+| `/apt:personas` | Produces the `.aperant/personas.json` roster that compile mode filters against. |
+</integration>

package/dist/plugin/skills/apt-release-notes/appendices/persona-voice.md

@@ -0,0 +1,59 @@
+# Persona-voice posture loader
+
+Aperant-authored posture loader consumed by `apt-release-notes/SKILL.md`.
+Per the CLAUDE.md `appendices/` convention, this file augments the parent
+skill's context — it is NOT independently router-invocable.
+
+## Why this exists
+
+The dev `CHANGELOG.md` (owned by `/apt:docs changelog`) describes WHAT
+changed in engineering terms: file paths, function names, task IDs,
+schema bumps. Release notes describe WHY the change matters to a
+specific human. Same merge, different voice. The release-notes pipeline
+hands you a structured fragment payload — your job is to tune the prose
+so the line reads like product-marketing copy for the persona, not like
+a commit message with the prefix stripped.
+
+## Posture rules (apply when composing a `Release note: …` line)
+
+1. **Verb first.** Start with the user's outcome — "See your shipped
+   builds in one tab" — not the implementation ("Added a `/builds` tab
+   to the dashboard"). The reader doesn't care that you added a tab;
+   they care that they can now see builds.
+2. **Persona-specific framing.**
+   - **End-user persona (audience: `end-user`)** — plain language, no
+     jargon. Avoid framework names, file paths, API endpoint paths.
+     One sentence. Concrete value.
+   - **Developer / API persona (audience: `developer-api`)** — API + SDK
+     semantics are the value proposition. Naming a new method is good.
+     Linking the migration page is good. Don't hide the implementation
+     details; they ARE the user-visible surface for this persona.
+   - **Internal-team persona (audience: `internal-team`)** — lighter
+     polish, faster cadence. One sentence is still ideal but the
+     internal team is fine with a touch of process-jargon ("we now
+     auto-rotate session tokens") when it conveys real value.
+3. **Triage bucket is your friend.** If you don't have strong signal
+   for the persona's framing — leave the line in the form the auto-draft
+   produced. The compile step will surface it under `## Needs Triage`
+   and the human curator can decide whether to ship it. Forced
+   confidence in the note voice is a regression class.
+4. **Tone matches the persona's archetype.** "The Vibe Coder" persona
+   wants energy ("Now you can branch off any session in one click").
+   "The Reviewer" persona wants precision ("Branch-from-session now
+   preserves your review queue with exact ordering"). Read the
+   archetype field in personas.json before composing.
+5. **No emoji unless the project's design taste explicitly calls for
+   it.** Aperant's house style is restrained; consumer-facing apps with
+   "playful" design tokens may differ — defer to the project's design
+   brief if one exists.
+
+## What this loader does NOT cover
+
+- Compile-time narrative beyond the per-PR sentence — that's the host
+  LLM's wider job at `/apt:release-notes --compile`, informed by
+  `PROJECT.md` Core Value, the personas roster, and the structured
+  per-tier sections the compiler writes.
+- Translating between audience values — picking the right audience is
+  set at `/apt:setup` Batch 9 time. The audience field doesn't change
+  mid-release; voice changes only at the per-fragment level inside the
+  audience already chosen.

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

@@ -18,6 +18,8 @@ allowed-tools: "Read, Bash, Grep, Glob"
 argument-hint: "apt:review [--skip-docs | --fix-all]"
 gates: 
   - verify-approved
+config_keys:
+  - pipeline.skip_review
 ---
 <objective>
 Review the code produced by a task's execution, analyzing logic, security, quality, architecture, and performance. Fix all findings. Update task documentation. Report what's next.

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

@@ -17,10 +17,13 @@ execution_modes:
   - plan-mode
   - plan-only
 allowed-tools: "Bash, Read, Write, Edit, Grep, Glob, Task"
-argument-hint: "apt:run [task description] [--skip-review]"
+argument-hint: "apt:run [task description] [--skip-review] [--phase-mode auto|agent-team|sub-agents|sequential]"
 gates: 
   - constitution-read
   - constitution-coverage
+config_keys:
+  - parallelization.enabled
+  - parallelization.max_agents
 ---
 <objective>
 Run the full Aperant pipeline: plan a task, execute all subtasks, verify the implementation, and optionally review the code. This is the one-command experience — from task description to verified, reviewed code.
@@ -63,12 +66,14 @@ node packages/framework/bin/apt-tools.mjs state .
 
 ## 1b. Resolve Orchestration Mode
 
-Run reconcile to determine the effective orchestration strategy for this pipeline run:
+Run reconcile to determine the effective orchestration strategy for this pipeline run. Pass the task's track via `--track <quick|standard|deep>` so per-track defaults from `.aperant/config.json:orchestration.per_track` apply (roundtable 2026-05-14 R7):
 
 ```bash
-node packages/framework/bin/apt-tools.mjs reconcile .
+node packages/framework/bin/apt-tools.mjs reconcile . --track {track}
 ```
 
+**Per-invocation override:** if the user passed `--phase-mode {auto|agent-team|sub-agents|sequential}` on the invocation, use that value as `PHASE_MODE` directly (it wins over both `per_track` and the global `phase_delegation`). Still call reconcile so `review_mode` and `debate_mode` are resolved against host capabilities.
+
 Parse the result and display:
 
 ```
@@ -81,7 +86,7 @@ If `downgrades` is present in the result, display each downgrade warning:
 [APT] Warning: {downgrade.field} requested '{downgrade.requested}' but host does not support it — using '{downgrade.resolved}'. {downgrade.reason}
 ```
 
-Store `resolved.phase_delegation` as `PHASE_MODE` for use in the pipeline steps below.
+Store `resolved.phase_delegation` (or the explicit `--phase-mode` override) as `PHASE_MODE` for use in the pipeline steps below.
 
 ## 2. Create Feature Branch (or task worktree)
 
@@ -161,6 +166,19 @@ Execute the apt:execute workflow inline:
 
 ## 5. Stage 3 — Verify (apt:verify)
 
+**De-anchored re-read (PHASE_MODE=sequential only — roundtable 2026-05-14 R2):**
+
+When `PHASE_MODE` is `"sequential"` and the same agent that ran Stage 2 is about to run Stage 3 in the same context window, treat the boundary as an attention reset before proceeding. The agent MUST:
+
+1. **Re-read `spec.md` from disk** — do not rely on its in-context summary from earlier in the conversation
+2. **Re-read the diff from disk** via `git diff {base_branch}...HEAD` — verify what was actually written, not what was intended
+3. **Adopt adversarial QA posture** — for the duration of Stage 3 you are not the implementer; you are reading this code for the first time, asking "what does this break?" rather than "did I do this right?"
+4. **Ignore your prior reasoning chain** — the executor's "why I did it this way" rationalization is in-window but MUST NOT anchor the verifier's reading. If a finding conflicts with prior reasoning, prefer the finding
+
+This block exists because the roundtable's STANDARD-track de-anchoring relies on prompt-level discipline rather than fresh-context isolation. The exit condition: if verify completeness+correctness scores drop >0.5 points across 10+ STANDARD tasks measured under R6 telemetry, flip `orchestration.per_track.standard` to `"sub-agents"` (R3 — the named fallback preserved from Systems Analyst + Risk Analyst dissent). See `.aperant/roundtables/phase-mode-per-track-20260514/REPORT.md` §Dissenting Views.
+
+Sub-agents and agent-team modes skip this block — they get fresh-context isolation by spawning, which makes the de-anchored re-read redundant.
+
 Execute the apt:verify workflow inline:
 
 1. Check all subtasks completed
@@ -188,6 +206,16 @@ Stop pipeline (do not proceed to review).
 
 **Skip if** `--skip-review` flag is set.
 
+**De-anchored re-read (PHASE_MODE=sequential only — roundtable 2026-05-14 R2):**
+
+Same attention-reset discipline as Stage 3 applies before review starts. In sequential mode the reviewer is the same agent that planned, executed, and verified — the rationalization chain is in-window. Before the 6-pass loop:
+
+1. **Re-read `spec.md` and `qa_signoff.json` from disk** — do not summarize from in-context recall
+2. **Re-read changed files** at their post-execution state via `git show HEAD:{path}` or direct Read
+3. **Adopt fresh-reviewer posture** — you are reading this code as if a colleague wrote it, not as if you wrote it. The 6 review passes (logic / security / quality / architecture / performance / docs-coherence) are independent lenses; treat each lens as a fresh adversarial reading
+
+Pattern reference: `packages/core/src/workflows/sparring/engine.ts` implements this exact discipline for sparring reviewers (fresh `streamText` per lens, lens prompt in system slot). This SKILL.md block is the same idea applied to verify/review in a single-context pipeline.
+
 Execute the apt:review workflow inline (see `apt-review/SKILL.md`):
 
 1. Load context — spec, QA results, constitution