@aperant/framework 0.6.2

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

@@ -0,0 +1,373 @@
+---
+name: apt:ship
+description: "Create PR with QA scores, decision traceability, and commit mapping"
+apt-skill-version: {{APT_VERSION}}
+stage: ship
+intent: ship
+when_to_use: "The build + review are done and the user wants a PR with QA scores, decision traceability, and commit mapping."
+user_invocable: true
+internal: false
+spawns_agent: false
+agent_name: null
+default_execution_mode: auto
+execution_modes:
+  - auto
+  - step
+allowed-tools: "Bash, Read, Write, Edit, Grep, Glob"
+argument-hint: "apt:ship [--draft | --title \"...\"]"
+gates: 
+  - review-clean
+  - all-subtasks-complete
+  - gitignore-in-sync
+---
+<objective>
+Create a pull request (or publish a package) with full traceability from decisions to implementation. The PR body includes QA dimension scores, decision audit trail, and commit-to-subtask mapping. This is the final step in any track -- after verify passes, ship it.
+</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
+- **GitHub CLI:** `gh` must be installed and authenticated
+</your_environment>
+
+<state_files>
+## State Files
+
+**Reads:**
+- `.aperant/state.json` — Active task, completed subtasks; resolve the active plan via `active_tasks[*].spec.path` / `implementation_plan` or the most-recent `.aperant/tasks/{task-id}/implementation_plan.json`.
+- `review.json` — QA scores and findings (if review was run)
+- `.aperant/context/notes/` — Decision traceability (gray areas, discuss outcomes)
+
+**Writes:**
+- Nothing locally -- creates PR externally via `gh pr create`
+- Updates `.aperant/state.json` to clear active task after shipping
+</state_files>
+
+<process>
+
+## 0. Hard Gate Check
+
+Before gathering context or building any PR artifacts, run the hard-gate check for the `ship` skill:
+
+```bash
+node packages/framework/bin/apt-tools.mjs gate check . --task-id {task-id} --skill ship
+```
+
+Parse the JSON envelope:
+- If `status == "ok"`: proceed to Section 1.
+- If `status == "fail"` AND `forced` is empty (i.e. the user did NOT pass `--force`): STOP. Report the failed gates verbatim from `failed:[{id, severity, reason}]`, then emit:
+  ```
+  Hard gate failed. Fix the issues above, or re-run with:
+    --force --reason "<explanation>"
+  The override will be logged to .aperant/events/{today}.jsonl.
+  ```
+  Exit the skill. Do NOT auto-apply `--force` — force is an explicit human decision.
+
+The ship gate covers constitution-read, verify-approved (qa_signoff.json verdict), review-clean (no unresolved critical/warning findings), gitignore-in-sync (.aperant/.gitignore conformance), and consistency-check (G8 — cross-artifact consistency between spec.md, implementation_plan.json, review.json, qa_signoff.json, and build-progress.json). Because these gates run here, Sections 1–3 below no longer need to re-check the verify verdict or block on review findings — the gate already did it.
+
+## 0.5 Pre-PR Committable Drift Check (C56 B2)
+
+Before gathering PR context, audit for uncommitted committable `.aperant/` state and stage anything the self-staging helper missed. This closes the artifact-leak class that the framework shipped with pre-C56: phases flipped in-progress, roadmap JSON touched, decision notes written — none of which followed into the PR's commits.
+
+```bash
+node packages/framework/bin/apt-tools.mjs audit pending-artifacts . --stage
+```
+
+Parse the JSON envelope:
+
+- **`unknown[]` is non-empty** → HARD STOP. A file changed under `.aperant/` that the classification contract does not recognize. Either the file is committable and the contract needs to be extended (framework change), or the file is ephemeral and must be added to the ignored-path set. Report the list, exit the skill:
+  ```
+  [APT:ship] Cannot ship — .aperant/ contains files the classification contract does not recognize:
+    - {path1}
+    - {path2}
+  Extend packages/framework/src/cli/artifacts/classification.mjs or add to ephemeral set, then re-run /apt:ship.
+  ```
+- **`committable[]` is non-empty AFTER --stage ran** → `audit pending-artifacts --stage` already `git add`-ed those paths on your behalf. Amend them into the next commit before PR creation, OR create a one-line `chore(aperant): artifact drift pre-ship` commit if the rest of the branch is already landed cleanly:
+  ```bash
+  if ! git diff --cached --quiet; then
+    git commit -m "chore(aperant): pre-ship artifact drift capture"
+  fi
+  ```
+- **Envelope status == `clean`** → proceed to Section 1.
+
+Classification reference: `packages/framework/docs/artifact-lifecycle.md` (committable vs ephemeral matrix for every `.aperant/` subpath).
+
+## 1. Gather Context
+
+Read all available context for building the PR:
+
+```bash
+# Active task info
+cat .aperant/state.json
+
+# Plan spec (active task, if any) — resolve via state first, then fall back to most-recent task dir
+#   Prefer: .aperant/tasks/$(jq -r '.active_tasks | to_entries[0].key' .aperant/state.json)/implementation_plan.json
+
+# QA scores (if review was run)
+cat review.json 2>/dev/null
+
+# Decision context files
+ls .aperant/context/notes/ 2>/dev/null
+
+# Commit log for this branch
+git log main..HEAD --oneline
+```
+
+Extract:
+- **Task description** from `state.json` active task
+- **Subtask list** from the plan spec
+- **QA scores** from `review.json` (scores object)
+- **Review findings** from `review.json` (stats object)
+- **Decisions** from `.aperant/context/notes/` files (gray areas resolved, discuss outcomes)
+- **Commit list** from git log
+
+## 2. Build Commit-to-Subtask Map
+
+Parse commit messages for subtask references. Commits from `apt:execute` follow the pattern:
+```
+feat({scope}): {message}
+fix({scope}): {message}
+refactor({scope}): {message}
+```
+
+Map each commit to the subtask it implements by matching scope and message content against the plan's subtask list.
+
+Format as a markdown table:
+
+| Commit | Subtask | Description |
+|--------|---------|-------------|
+| `abc1234` | #1 | Implement auth middleware |
+| `def5678` | #2 | Add token refresh logic |
+
+If no plan exists (ad-hoc task), list commits without subtask mapping.
+
+## 3. Build PR Body
+
+**Title:** Derived from task description. Keep it short (<70 characters).
+
+**Body structure:**
+
+```markdown
+## Summary
+
+{1-3 sentence description of what was built and why}
+
+## QA Scores
+
+| Dimension | Score |
+|-----------|-------|
+| Completeness | {N}/10 |
+| Correctness | {N}/10 |
+| Code Quality | {N}/10 |
+| Coverage | {N}/10 |
+
+{If review was run, add review scores:}
+
+| Review Dimension | Score |
+|------------------|-------|
+| Logic | {N}/10 |
+| Security | {N}/10 |
+| Quality | {N}/10 |
+| Architecture | {N}/10 |
+| Performance | {N}/10 |
+
+## Decision Traceability
+
+| Decision | Description | Outcome |
+|----------|-------------|---------|
+| {id} | {what was decided} | {chosen option and rationale} |
+
+{If no decisions were recorded: "No gray areas encountered -- implementation followed plan directly."}
+
+## Commits
+
+| Commit | Subtask | Description |
+|--------|---------|-------------|
+| `{sha}` | #{n} | {description} |
+
+## Review Findings
+
+{If review was run:}
+- Critical: {n}
+- Warnings: {n}
+- Suggestions: {n}
+- Nitpicks: {n}
+- Auto-fixed: {n}
+
+{If no review: "No code review was run for this task."}
+
+---
+
+Built with [Aperant Framework](https://github.com/Mikalsen-AI/aperant-cloud-desktop/tree/main/packages/framework)
+```
+
+## 4. Determine Ship Mode
+
+Read `.aperant/config.json` for `project_type`.
+
+**If `project_type` is `library` or `cli-tool`:**
+- Ask the user: "This is a {project_type}. Create a PR, publish to npm, or both?"
+- **If publish:**
+  1. Check `package.json` for current version
+  2. Suggest version bump: patch (bug fixes), minor (new features), major (breaking changes)
+  3. Run `npm version {bump}` (or `pnpm version {bump}`)
+  4. Run `npm publish` (or `pnpm publish`)
+  5. Report: "Published {package}@{version} to npm"
+- **If PR:** Proceed to Step 5
+- **If both:** Publish first, then create PR
+
+**If any other `project_type`:** Proceed directly to Step 5.
+
+## 5. Sync Team Bookkeeping (before PR)
+
+Before creating the PR, commit any uncommitted team bookkeeping files so teammates stay in sync. This runs **regardless of whether a PR is being created** and only touches an allowlisted set of files under `.aperant/` (never source code).
+
+```bash
+node packages/framework/bin/apt-tools.mjs team sync . --push
+```
+
+Behaviour:
+- If team mode is disabled, this is a no-op (`status: "skipped"`).
+- If nothing needs syncing, this is a no-op (`committed: false`).
+- Otherwise it stages `.aperant/tasks/INDEX.md`, `.aperant/team.json`, and any dirty `.aperant/roadmap/*.md|*.json`, commits with `chore(aperant): sync team bookkeeping` + an `Aperant Framework` co-author trailer, and pushes. Per-agent `.aperant/team-status/{agent-id}.json` records are gitignored and intentionally not synced.
+- The push is best-effort — if it fails (e.g. protected branch), the result includes `push_error` but the commit still exists locally.
+
+Do **not** skip this step when publishing a package without a PR; the commit is the point, not the PR.
+
+## 6. Create PR
+
+Check prerequisites:
+```bash
+# Verify gh is installed
+which gh || echo "ERROR: GitHub CLI (gh) is required. Install: https://cli.github.com/"
+
+# Verify authentication
+gh auth status || echo "ERROR: Run 'gh auth login' first"
+```
+
+Handle branch state. First resolve the active task's worktree/branch metadata:
+
+```bash
+node packages/framework/bin/apt-tools.mjs task get . --id {task_id}
+```
+
+Parse `worktree_path`, `branch`, and `base_branch` from the result.
+
+- **If the task record has `branch` and `worktree_path` (task-level worktree isolation active):**
+  ```bash
+  git -C {worktree_path} push -u origin {branch}
+  gh pr create --title "{title}" --body "{body}" --base {base_branch} --head {branch}
+  ```
+  The PR targets the recorded `base_branch` (the branch the task was forked from), NOT `main`. This is the correct target when the user is shipping an intermediate milestone onto a longer-lived feature branch.
+
+- **If the task record has `branch` but no `worktree_path`:** Push the branch from the current cwd and create the PR against `base_branch`:
+  ```bash
+  git push -u origin {branch}
+  gh pr create --title "{title}" --body "{body}" --base {base_branch} --head {branch}
+  ```
+
+- **If no task branch is recorded and we're on main/master:** Legacy behaviour — create a feature branch first:
+  ```bash
+  git checkout -b {task-slug}
+  git push -u origin {task-slug}
+  gh pr create --title "{title}" --body "{body}"
+  ```
+
+- **If no task branch is recorded and we're already on a feature branch:** Legacy behaviour — push HEAD and open a PR against `main`:
+  ```bash
+  git push -u origin HEAD
+  gh pr create --title "{title}" --body "{body}"
+  ```
+
+Capture the PR URL from the output into `pr_url` (for example, the last line of `gh pr create` stdout). Section 7.1 references `$pr_url` when parsing the PR number for the post-ship review hint, so binding the name here at capture time keeps the two sections coherent.
+
+**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}
+```
+
+Display the resolution so users see which branch/base was used:
+
+```
+[APT:ship] task branch: {branch}
+[APT:ship] base branch:  {base_branch}
+[APT:ship] worktree:     {worktree_path or "(none)"}
+[APT:ship] pr_url:       {PR_URL}
+```
+
+## 7. Report
+
+Print the ship summary:
+
+```
+Shipped: {PR URL}
+Title: {title}
+QA: completeness={n} correctness={n} quality={n} coverage={n}
+Review: logic={n} security={n} quality={n} architecture={n} performance={n}
+Commits: {count}
+Review findings: {count by severity or "none"}
+Decisions traced: {count}
+```
+
+### 7.1 Post-ship /apt:pr-review hint
+
+After printing the ship summary, conditionally emit a tip suggesting `/apt:pr-review` for a deep multi-agent review of the freshly-opened PR. The hint is controlled by `pr_review.suggest_after_ship` in `.aperant/config.json` (tri-state: `always` | `ask` | `never`; default when absent: `always`).
+
+**Skip entirely** when no PR URL was captured in Section 6 — the library `npm publish`-only path (Section 4) ships to npm without opening a PR, so there is no PR to review.
+
+**Parse the PR number** from the captured PR URL using the regex `/pull/(\d+)` (Bash: `pr_number=$(echo "$pr_url" | sed -nE 's|.*/pull/([0-9]+).*|\1|p')`). If the regex fails to match (malformed URL, capture missed), skip the hint and proceed to Section 8.
+
+**Read the mode from config:**
+```bash
+suggest_mode=$(jq -r '.pr_review.suggest_after_ship // "always"' .aperant/config.json)
+```
+
+**Autonomy interaction** (apply BEFORE branching on `suggest_mode`): read the task's autonomy level from `.aperant/state.json` (`active_tasks[{task-id}].autonomy`, falling back to `autonomy.default`). When `autonomy === 3` (YOLO), degrade `ask` → `always` — one fewer prompt in unattended auto-chains. Autonomy 0-2 preserve `ask` unchanged (0-1 stay supervised/guided; 2 was opted into non-destructive auto-chaining but one last stop before a deep review is reasonable).
+
+**Branch on the effective `suggest_mode`:**
+
+- **`always`** — emit two banner lines matching the `:261-263` shape:
+  ```
+  [APT:ship] Tip: run a deep multi-agent review with: /apt:pr-review --pr {pr_number}
+  [APT:ship] (disable or change to ask/never via /apt:setup → "PR Review Auto-Suggest")
+  ```
+
+- **`ask`** — emit the structured question:
+  ```
+  [APT:ship] Run /apt:pr-review --pr {pr_number} now for deep multi-agent review? [Y/n]
+  ```
+  On `Y` (or empty enter), invoke `/apt:pr-review --pr {pr_number}` inline after Section 8 flips the task to `shipped-pending-merge` — do NOT block the lifecycle transition. On `N` or any other response, proceed silently to Section 8.
+
+- **`never`** — silent. Proceed directly to Section 8.
+
+`suggest_after_ship` is purely additive — it does not affect `authorship_override`, `authorship_overrides`, or `max_rounds` in the same `pr_review` block.
+
+## 8. Transition lifecycle to `shipped-pending-merge` (C56 B5)
+
+Ship is NOT the final closer. The PR has just been opened — it won't merge for minutes, hours, or days, and no agent will be present on merge. Instead of closing the task now, flip its lifecycle to `shipped-pending-merge` — the intermediate state between `reviewing` and `completed`. `/apt:close-task` runs post-merge (either manually via `/apt:close-task --all` or by the user when they return to the repo) and performs the actual closeout: phase flip, documentation narration, worktree GC, per-PR config strip, task archive.
+
+```bash
+node packages/framework/bin/apt-tools.mjs task update . --id {task-id} --lifecycle-phase shipped-pending-merge
+```
+
+The task stays in `state.active_tasks[*]` with `lifecycle_phase: "shipped-pending-merge"`. Do NOT call `task close` here — that would mark it `completed` before the PR is actually merged, producing the same artifact drift C56 was built to eliminate.
+
+The linked phase (if any) stays `in-progress` — it only flips to `completed` when `/apt:close-task` confirms via `gh pr view` that the PR's state is `MERGED`.
+
+**Documentation narration moved.** Any ROADMAP.md "Recent activity" prose updates run from `/apt:close-task` on confirmed merge, not from ship. The "shipped" moment is not the "landed" moment — and a landed-work claim belongs with the closer, not the opener.
+
+</process>
+
+<autonomy_interaction>
+## Autonomy Levels
+
+| Level | Behavior |
+|-------|----------|
+| 0-1 | Show full PR body preview. Ask for approval before creating the PR. Allow edits to title and body. |
+| 2 | Create the PR automatically. Show the result (URL, title, scores). |
+| 3 | Create the PR silently. Show only the PR URL. |
+
+For library/cli-tool publish flow: always ask regardless of autonomy level (publishing to npm is an elevated-risk action per design principle 1.5 -- risk class overrides autonomy).
+</autonomy_interaction>