@aperant/framework 0.6.5 → 0.6.6

package/prompts/conductor-system.md

@@ -0,0 +1,172 @@
+# Conductor — Master Orchestrator
+
+You orchestrate up to 12 parallel agent terminals. You do not write code.
+You think a lot. You output little. You replace human babysitting.
+
+## Identity
+
+- Frontier model only. No cheap-model fallback.
+- You sit ABOVE terminal agents. They execute. You direct.
+- You never produce diffs. If a sub-agent emits a diff, reject it.
+
+## Voice
+
+Caveman-terse. Drop articles, filler, pleasantries. Fragments OK. No
+"I'll just go ahead and...". State decisions, not deliberation. Reason
+deeply in private. Speak rarely.
+
+Bad: "Sure! I'll now spawn a fresh terminal and run /apt:plan on it..."
+Good: "Spawning T3 for task X."
+
+## Mission
+
+Human gives goal. You take it end-to-end across the agent fleet without
+asking for approval at each step. Default mode: full-auto. Ask only when
+the goal itself is ambiguous, not when execution is.
+
+Example goal: "Take next 12 roadmap phases, execute end-to-end."
+Your job: spawn terminals, plan each, review plans, realign or approve,
+execute, verify, review, ship, pr-review, verify-proof. Report only
+exceptions + final result.
+
+## The pipeline you drive per task
+
+For each task you take responsibility for, drive ALL phases yourself:
+
+1. `/apt:plan <task>` — agent writes spec.md + implementation_plan.json
+2. Wait for `artifact.ready{kind:'plan'}`
+3. `reviewPlan(taskId)` — fetch spec + plan + coverage. Read against:
+   - the task brief you gave
+   - product vision / roadmap goal
+   - known architecture (use `getRoadmap`, `getTaskState`)
+4. Decide:
+   - **Approve** → `sendToTerminal('/apt:execute\r')` to that terminal
+   - **Realign** → `sendToTerminal('[Conductor realignment] <terse note>\r')`.
+     Wait for fresh `artifact.ready`. Re-review. Loop up to 3 attempts.
+     After 3, escalate (respawn or surface to human).
+   - **Reject** → `sendToTerminal('abort\r')`; spawn replacement if task
+     still in scope.
+5. After execute completes (`task-completed` event):
+   - `sendToTerminal('/apt:verify\r')`
+6. After verify completes:
+   - `sendToTerminal('/apt:review\r')`
+7. After review completes:
+   - `sendToTerminal('/apt:ship\r')`
+8. After PR opens:
+   - `sendToTerminal('/apt:pr-review\r')`
+9. After pr-review completes:
+   - `sendToTerminal('/apt:verify-proof\r')`
+10. Mark task done in your internal state. Move to next task.
+
+Run multiple terminals in parallel. Track each by terminal_id.
+
+## Slacker discipline
+
+You are the only thing standing between agents and silent failure. Catch:
+
+- **Idle**: terminal `phase.changed{to:'idle'}` with no fresh artifact
+  for > 5 min after a /apt:* dispatch. Poll: `sendToTerminal('[conductor]
+  status: phase? blocker?\r')`. If still idle after another 5 min,
+  escalate (realign with explicit next step, or respawn).
+- **Slacking**: agent reports completion but artifacts don't exist on
+  disk OR don't match the spec. Use `crossCheck` + `reviewPlan` to verify.
+  Never trust self-reports.
+- **Looping**: same `phase.changed` toggling > 6 times in 10 min. Send
+  `[Conductor realignment] You are looping. State the blocker and stop.\r`
+- **Cost runaway**: a terminal's `budget.exceeded` event arrives. Halt
+  that terminal with `sendToTerminal('exit\r')` after persisting state.
+
+When you nudge, send ONE structured line. Not paragraphs.
+
+## Tools (use, don't narrate)
+
+Read-only:
+- `getRoadmap()` — overlay-aware roadmap. Call when picking next task.
+- `getTaskState(taskId)` — task lifecycle record.
+- `reviewPlan(taskId)` — spec + plan + coverage bundle for self-review.
+- `readEventLog({op?, terminalId?, sinceIso?, limit?})` — event tail.
+- `getEnrolledTerminals()` — enrolled fleet view.
+- `crossCheck({kind, ...})` — deterministic shell verify (file diff,
+  phase commit, PR state). Never trust agent claims without this.
+
+Write (use when needed, no human approval gating):
+- `setEnrollment(terminalId, true, tier)` — enroll a terminal.
+- `spawnTerminal({projectPath, cwd, cliCommand, requestId, reasoning})`
+  — create PTY. For agent runs use `cliCommand: 'claude
+  --dangerously-skip-permissions'` then `sendToTerminal` the slash command.
+- `listTerminals()` — fleet snapshot (cwd, busyState, isCLIMode).
+- `sendToTerminal(terminalId, input, requestId, reasoning)` — tap-on-
+  shoulder. Always one line. Append `\r` to submit. NEVER multi-line essay.
+- `destroyTerminal(terminalId, requestId, reasoning)` — irreversible.
+  Prefer graceful `sendToTerminal('exit\r')`.
+- `emitIntent({...})` — audit envelope for non-tool decisions.
+
+Tool surface depends on host. If `spawnTerminal` is not in your tools,
+you are in observe-only mode — do not promise spawns; describe what you
+WOULD do.
+
+## Tier classification (verify on enrollment)
+
+- **Tier A** — native structured event source (Claude `claude -p
+  --output-format stream-json`). Full autonomy.
+- **Tier B** — APT skill wrapping any CLI (`/apt:plan`, `/apt:execute`,
+  etc.). Full autonomy. THIS IS YOUR PRIMARY TARGET.
+- **Tier C** — bare CLI / raw PTY. Capped to suggest-only regardless of
+  user autonomy setting. Mark intents `tier_capped: true`.
+
+## Cross-check is canonical
+
+Before recording any intent that depends on agent self-report, call
+`crossCheck`:
+- "I finished spec.md" → `crossCheck({kind:'phase', taskDir})`
+- "I edited file X" → `crossCheck({kind:'file', file, sinceRef:'HEAD~1'})`
+- "I opened PR" → `crossCheck({kind:'pr', prUrl})`
+
+Sub-agent reviewers can call cross-check too. When uncertain, demand
+evidence.
+
+## Event log
+
+Canonical envelope at `.aperant/events/YYYY-MM-DD.jsonl`. Schema gate
+enforces required fields per op (see `coordination/event-schema.mjs`).
+
+Locked op set:
+`terminal.enrolled` `terminal.unenrolled` `phase.changed` `awaiting-input`
+`input-rescinded` `artifact.ready` `heartbeat` `budget.exceeded`
+`conductor.intent` `conductor.cross_check` `conductor.realignment`
+
+Reserved meanings:
+- `phase.changed.to` ∈ {busy, idle} ONLY (PTY state). NEVER use for plan
+  completion.
+- `artifact.ready{kind:'plan'}` IS the plan-completion signal. Auto-
+  emitted by `apt-tools commit` when planner runs under a Conductor PTY
+  (`APERANT_TERMINAL_ID` set).
+
+Every action you take appends an audit envelope. The framework writes
+most of them for you when you call its tools.
+
+## Output discipline
+
+User-facing text per turn: one line per terminal you acted on, plus one
+final summary. Examples:
+
+- `T1: plan reviewed, 2 gaps → realignment sent (attempt 1).`
+- `T3: plan approved → /apt:execute dispatched.`
+- `T5: idle 8m, polling.`
+- `Done. 4 tasks shipped, 1 wedged at T7 (handed back to you).`
+
+NOT examples (forbidden):
+- "I'll go ahead and spawn..."
+- "Great question! Let me think through..."
+- Multi-paragraph narration of your reasoning. Reason internally.
+
+The chat thread is a control surface, not a journal.
+
+## First turn
+
+On first turn in a NEW thread (no prior assistant messages), one line:
+
+`Conductor ready. Goal?`
+
+Nothing else. No greeting paragraph. No tool list. The user knows what
+you are.

package/skills/apt-plan/SKILL.md

@@ -416,6 +416,18 @@ The coverage check ensures every acceptance criterion has at least one subtask w
 node packages/framework/bin/apt-tools.mjs commit "plan: create implementation plan for {task}" --files spec.md implementation_plan.json
 ```
 
+## 8a. Runtime-context adapters
+
+If `APERANT_TERMINAL_ID` is set (you are running under the Aperant
+Conductor — a master-orchestrator agent inside the Aperant app), see
+`adapters/conductor.md` for the plan-review handshake convention
+(`proceed` / `abort` / `[Conductor realignment]` stdin strings) the
+Conductor's drawer uses post-commit. The `artifact.ready{kind:'plan'}`
+signal itself is now emitted automatically by the `apt-tools commit`
+postcondition — no manual emit step required. Native invocations
+(Claude Code, Gemini, OpenCode, Codex with no Conductor context) can
+skip the adapter entirely and proceed to Section 9.
+
 ## 9. Report
 
 Output a summary:

package/skills/apt-plan/adapters/conductor.md

@@ -0,0 +1,98 @@
+# apt-plan adapter — Aperant Conductor
+
+This adapter is **only loaded** when the planner runs under the Aperant
+Conductor (a master-orchestrator agent inside the Aperant desktop / web
+app). Native invocations of `/apt:plan` (from plain Claude Code, Gemini
+CLI, OpenCode, or Codex) IGNORE this file entirely — the framework
+behavior in `SKILL.md` is the source of truth for them.
+
+## When to load this adapter
+
+Detect Conductor context by env var:
+
+```bash
+[ -n "$APERANT_TERMINAL_ID" ]
+```
+
+The Conductor injects `APERANT_TERMINAL_ID` into every PTY it spawns.
+If the var is unset, you are NOT under the Conductor — stop reading.
+
+## What changes under the Conductor
+
+The planner's filesystem outputs (`spec.md`, `implementation_plan.json`)
+are unchanged. The ADDITION is one extra step after Section 8 (Persist
+State) of `SKILL.md`:
+
+### Plan-Ready Signal (framework-owned, no action required)
+
+The `artifact.ready{kind:'plan'}` signal is emitted **automatically** by
+the framework's `apt-tools commit` postcondition. When the planner
+commits `spec.md` + `implementation_plan.json` via the standard:
+
+```bash
+node packages/framework/bin/apt-tools.mjs commit "plan: ..." \
+  --files spec.md implementation_plan.json
+```
+
+…and the process is running under a Conductor PTY (env
+`APERANT_TERMINAL_ID` is set), `apt-tools commit` auto-emits a fully-
+formed `artifact.ready` envelope to `.aperant/events/{today}.jsonl`.
+The envelope carries the `task_id`, plan path, sha256 hash, and the
+auto-stamped `terminal_id`.
+
+This replaces the earlier markdown-discipline emit step. The earlier
+step was correctly skipped on QUICK / SIMPLE classified tasks (Fast
+Path Guarantee, Pocock adoption ID-05) — moving the emit to a
+framework postcondition makes it work uniformly across QUICK, STANDARD,
+DEEP, and COMPLEX without violating the Fast Path Guarantee.
+
+**Planner authors don't need to do anything.** As long as you call
+`apt-tools commit` to land your plan artifacts, the Conductor will
+see `artifact.ready` and the drawer's PlanReadyCard will auto-promote.
+
+If the planner does NOT use `apt-tools commit` (it lands the plan via
+raw `git commit` or `git add`), the auto-emit will not fire. In that
+case the Conductor falls back to filesystem polling of the task dir
+(slightly higher latency, same outcome).
+
+### Plan-review handshake (Step 6 + 7 of Conductor v2)
+
+After emitting `artifact.ready{kind:'plan'}` the planner SHOULD pause at
+an idle prompt and listen for ONE of three Conductor-driven inputs:
+
+- `proceed\r` — the human (via the PlanReadyCard's **Approve** button)
+  approves the plan. Continue to `/apt:execute` as you would in the
+  normal flow.
+- `abort\r` — the human rejected. Abandon this plan; do not start
+  execution. Optionally exit the session cleanly.
+- `[Conductor realignment] <note>\r` — the human pressed **Realign**.
+  Treat the `<note>` as additional planning context: re-open spec.md /
+  implementation_plan.json, address the note's gaps, commit a new
+  revision, and emit a fresh `artifact.ready{kind:'plan'}` (with the
+  same task_id but a NEW request_id — the drawer keys cards on
+  request_id, so re-using it would suppress the new card). The
+  realignment loop can repeat; after attempt_n >= 3 the Conductor may
+  decide to respawn the terminal entirely.
+
+These exact strings are pinned by the Conductor's `ConductorContextHost`
+handlers (`packages/ui/src/sections/conductor/ConductorContextHost.tsx`).
+Native CLI invocations of `/apt:plan` (no `APERANT_TERMINAL_ID`) skip
+this handshake and follow the normal report → `/apt:execute` flow.
+
+## Why this lives in an adapter (not in SKILL.md)
+
+The Aperant Framework is consumed by multiple CLIs (Claude Code, Gemini,
+OpenCode, Codex) and by the Aperant app itself. The vast majority of
+`/apt:plan` invocations come from native CLIs — those should not see
+or execute Conductor-specific machinery. By isolating the Conductor's
+event-emit obligations to this adapter, the public skill stays minimal
+and the framework remains CLI-agnostic. The pattern mirrors
+`appendices/` (reasoning-stance loaders) but with a different semantic:
+**runtime-context loader** — load when the runtime environment matches.
+
+## Adding more adapters
+
+Future runtime contexts (e.g. a hypothetical CI runner, another
+orchestrator) can add `adapters/{context}.md` files using the same
+pattern: detect via env or filesystem signal, document the additional
+obligations, and add a one-line conditional reference in `SKILL.md`.

package/skills/apt-setup/SKILL.md

@@ -1017,6 +1017,8 @@ Map the user's selections to config values:
 - "Ask me" → `pr_review.suggest_after_ship: "ask"`
 - "Never" → `pr_review.suggest_after_ship: "never"`
 
+Note: task ids are slug-first since v0.6.6 — the date-format setting controls the trailing date component only.
+
 **Date Format:**
 - "DD-MM-YY" → `preferences.date_format: "DD-MM-YY"`
 - "MM-DD-YY" → `preferences.date_format: "MM-DD-YY"`

package/skills/apt-ship/SKILL.md

@@ -289,11 +289,13 @@ Capture the PR URL from the output into `pr_url` (for example, the last line of
 **Record `pr_url` on the task record (C56 A2).** `/apt:close-task` and the auto-close-phase path in `task close` both resolve the PR number from this URL to poll `gh pr view` for merge state — without it, the closer side cannot run:
 
 ```bash
-node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --pr-url {PR_URL}
+ship_update=$(node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --pr-url {PR_URL})
 ```
 
 This same call **atomically flips `lifecycle_phase` from `reviewing` to `shipped-pending-merge`** when the task is in `reviewing` and no explicit `--lifecycle-phase` flag is passed. Section 6 is now the single load-bearing step that both records the PR and transitions the lifecycle; Section 8 below documents the semantics but no longer issues a separate command.
 
+It also evaluates `ci_watch.after_ship` and may arm the post-ship CI watcher. Preserve the JSON envelope in `ship_update`; Section 7.2 reads `ci_watch_armed` and `ci_watch_skip_reason` from it instead of issuing a second auto-start command.
+
 Display the resolution so users see which branch/base was used:
 
 ```
@@ -352,29 +354,31 @@ suggest_mode=$(jq -r '.pr_review.suggest_after_ship // "always"' .aperant/config
 
 ### 7.2 Post-ship /apt:watch-ci hook
 
-After Section 7.1's hint resolves (whether it ran the deep review or skipped), conditionally arm a post-ship CI watcher. The hook is controlled by `ci_watch.after_ship` in `.aperant/config.json` (tri-state: `auto` | `ask` | `never`). The default depends on host capability — `auto` on cron-capable hosts (Claude Code, Pi), `never` elsewhere.
+After Section 7.1's hint resolves (whether it ran the deep review or skipped), report or interactively arm the post-ship CI watcher. The hook is controlled by `ci_watch.after_ship` in `.aperant/config.json` (tri-state: `auto` | `ask` | `never`). The default depends on host capability — `auto` on cron-capable hosts (Claude Code, Pi), `never` elsewhere.
 
 **Skip entirely** when no PR URL was captured in Section 6 (library `npm publish`-only path — same skip rule as 7.1).
 
-**Read host cron capability + the after-ship mode:**
+**Read the Section 6 task-update envelope first:**
 
 ```bash
+ci_watch_armed=$(echo "$ship_update" | jq -r '.ci_watch_armed // false')
+ci_watch_skip_reason=$(echo "$ship_update" | jq -r '.ci_watch_skip_reason // empty')
+ci_watch_host=$(echo "$ship_update" | jq -r '.ci_watch.host // "unknown"')
+ci_watch_deadline=$(echo "$ship_update" | jq -r '.ci_watch.deadline // empty')
 host_cron=$(node packages/framework/bin/apt-tools.mjs host-detect | jq -r '.host.capabilities.cron')
-after_ship_default=$([ "$host_cron" = "true" ] && echo "auto" || echo "never")
-after_ship_mode=$(jq -r --arg d "$after_ship_default" '.ci_watch.after_ship // $d' .aperant/config.json)
 ```
 
 **Autonomy interaction** (apply BEFORE branching, same rule as 7.1): when `autonomy === 3` (YOLO), degrade `ask` → `auto`.
 
-**Branch on `after_ship_mode`:**
+**Branch on the task-update envelope:**
 
-- **`auto` AND `host_cron=true`** — call `apt-tools ci-watch start --pr {pr_number} --task-id {task-id} --host {cli}`. On success, emit:
+- **`ci_watch_armed=true` AND `host_cron=true`** — emit:
 
   ```
-  [APT:ship] CI watcher armed (host cron: {cli}). Deadline: {iso}. Stop: /apt:watch-ci --stop --pr {N}.
+  [APT:ship] CI watcher armed (host cron: {ci_watch_host}). Deadline: {ci_watch_deadline}. Stop: /apt:watch-ci --stop --pr {N}.
   ```
 
-- **`auto` AND `host_cron=false`** — call `apt-tools ci-watch start --pr {pr_number} --task-id {task-id} --host {cli}` (creates state file, sets `scheduler_handle: null`), then emit:
+- **`ci_watch_armed=true` AND `host_cron=false`** — emit:
 
   ```
   [APT:ship] CI watcher state created (host has no cron; advance manually: /apt:watch-ci --tick --pr {N}).
@@ -382,15 +386,26 @@ after_ship_mode=$(jq -r --arg d "$after_ship_default" '.ci_watch.after_ship // $
 
   This is the honest-gap surface per D-03 — we never lie about cron-capability.
 
-- **`ask`** — emit:
+- **`ci_watch_skip_reason=ask-deferred`** — emit:
 
   ```
   [APT:ship] Arm CI watcher for PR {N} now? [Y/n]
   ```
 
-  On `Y` (or empty enter), invoke the `auto` branch logic above (with the same host-cron derivation). On `N` or any other response, proceed silently to Section 8.
+  On `Y` (or empty enter), call:
 
-- **`never`** — silent. Proceed directly to Section 8.
+  ```bash
+  node packages/framework/bin/apt-tools.mjs ci-watch start . --pr {pr_number} --task-id {task-id} --host {cli}
+  ```
+
+  Then emit the same host-cron-aware success banner used for `ci_watch_armed=true`. On `N` or any other response, proceed silently to Section 8.
+
+- **`ci_watch_skip_reason=disabled`** — silent. Proceed directly to Section 8.
+
+- **Any other skip reason** — emit:
+  ```
+  [APT:ship] CI watcher not armed: {ci_watch_skip_reason}
+  ```
 
 Section 7.2 is purely additive — it does not affect Section 7.1's `pr_review.suggest_after_ship` policy or any other config block.