@plainconceptsplatform/agent-harness 2.4.1 → 2.5.0

package/harness/.agents/skills/pc-ops-evidence/SKILL.md

@@ -1,127 +1,133 @@
----
-name: pc-ops-evidence
-description: Writes a capturePlan in evidence.json for the Visual Evidence CI workflow to execute on a runner with Docker and Chrome access. Load after a change is implemented. Invoked by /ops-evidence and the plan-goal pipeline.
-license: MIT
----
-
-# Ops Evidence
-
-Write a capture plan so the Visual Evidence CI workflow can capture screenshots on a runner with full Docker and Chrome access.
-
-The agent runs inside the awf sandbox where Docker-in-Docker is unsupported and headless Chromium's sandbox is blocked by the container security policy. The agent cannot capture screenshots itself. Instead, it analyzes the diff and writes a `capturePlan` in `evidence.json`. A separate CI workflow executes the plan.
-
-## Convention
-
-Every platform project has `pnpm run dev` at root that starts the **full stack** (database + API + web). The app runs with mock auth in development mode (no real authentication needed). This is the only contract — no per-project evidence harness, fixture apps, or scenario registries.
-
-## Input
-
-The caller provides (all optional):
-- change id: locates `openspec/changes/{change-id}/` (or the archived `archive/*{change-id}/`).
-- issue / work-item ref and PR number: where to publish.
-- output mode (`default` / `push` / `pr`): whether the branch was pushed.
-- operation: `capture` (default), `publish`, or `both`.
-
-## Part 1: Capture (operation: capture / both)
-
-**Step 1: Decide whether evidence is required.** Inspect the change's diff:
-- Required when changed files include user-visible UI: `*.tsx/jsx/vue/svelte`, `*.css/scss/less`, pages, layouts, components, navigation.
-- Skipped when docs-only, internal refactor, dependency-only, test-only, backend-only.
-- Mixed or unknown: required (be safe).
-
-If skipped: write `evidence.json` with `status: "skipped"` and reason. Done.
-
-**Step 2: Discover routes from git diff.** Parse changed files to determine which routes to screenshot:
-- `pages/**/*.tsx` or `app/**/page.tsx` → extract the route path
-- `features/**/*.tsx` or `components/**/*.tsx` → screenshot the homepage and any routes that import the changed component
-- If no routes found → screenshot `/` only
-- Always include `/` (homepage) as a baseline
-
-**Step 3: Write `evidence.json` with `capturePlan`.** The agent never attempts to start the app stack or launch a browser — those always fail inside the awf sandbox. Instead, write a `capturePlan` immediately.
-
-### The `capturePlan` schema
-
-```
-capturePlan:
-  routes:           # Array of route objects to screenshot (at minimum [{ path: "/" }])
-    - path: string  # URL path, e.g. "/quotes/:id"
-      sampleId:     # string | "first" | "any" — how to resolve dynamic segments
-      caption:      # string — human-readable description of what this screenshot shows
-  viewports:        # Array of viewport objects
-    - width: number
-      height: number
-      label: string # "desktop" | "mobile" | custom
-  requireApi:       # boolean — true when the route needs the backend API running
-  requireLogin:     # boolean — true when the route needs authentication
-  loginMethod:      # string — "mock-sso" | "none" | custom method identifier
-  reason:           # string — why evidence was blocked and what the screenshots should show
-```
-
-### Rules for writing capturePlan
-
-1. `routes` MUST always include `{ path: "/", caption: "Homepage" }` as the first entry.
-2. Every additional route discovered from the diff goes after the homepage entry.
-3. `sampleId: "first"` means the CI workflow should use the first record returned by the API (e.g. the first quote from the seed data). `sampleId: "any"` means any valid ID.
-4. `requireApi` is `true` when any route needs the backend to return data. It is `false` only for purely static pages (login, not-found).
-5. `requireLogin` is `true` when any route needs authentication. For dev mode with mock auth, `loginMethod` is `"mock-sso"`.
-6. `reason` should explain both WHY capture was blocked and WHAT the screenshots should show once captured.
-
-### Example `evidence.json`
-
-```json
-{
-  "version": 1,
-  "changeId": "currency-in-project-details",
-  "required": true,
-  "status": "blocked",
-  "assets": [],
-  "capturePlan": {
-    "routes": [
-      { "path": "/", "sampleId": "any", "caption": "Homepage / accounts list" },
-      { "path": "/quotes/:id", "sampleId": "first", "caption": "Quote editor with currency selector in ProjectDetailsCard" }
-    ],
-    "viewports": [
-      { "width": 1280, "height": 720, "label": "desktop" },
-      { "width": 375, "height": 667, "label": "mobile" }
-    ],
-    "requireApi": true,
-    "requireLogin": true,
-    "loginMethod": "mock-sso",
-    "reason": "Currency selector moved from editor body into ProjectDetailsCard; visual change in quote editor page."
-  },
-  "reason": "Visual evidence cannot be captured inside the awf sandbox (Docker-in-Docker unsupported, headless Chromium sandbox blocked). A capturePlan has been written for the Visual Evidence CI workflow.",
-  "prMarkdown": "## Evidence\n\nVisual evidence for this change is **blocked** in this agent run. A `capturePlan` has been written to `evidence.json` — the Visual Evidence CI workflow will execute it on a runner with full Docker and Chrome access.\n\nAutomated verification that did run:\n- Lint: clean\n- Tests: all pass\n- Build: success"
-}
-```
-
-### When evidence is not required
-
-If evidence is skipped (no UI files changed), write without a `capturePlan`:
-
-```json
-{
-  "version": 1,
-  "changeId": "{change-id}",
-  "required": false,
-  "status": "skipped",
-  "assets": [],
-  "reason": "No user-visible UI files changed in this PR.",
-  "prMarkdown": "## Evidence\n\nSkipped: no user-visible UI changes."
-}
-```
-
-Capture never commits, stages, or pushes. The caller owns git.
-
-## Part 2: Publish (operation: publish / both)
-
-Preconditions:
-- An issue/PR number was provided. Else skip.
-- Image URLs resolve only if the branch was pushed (`pr`/`push` modes).
-- Backlog platform from `.opencode/harness.json`; `none` means skip.
-
-<!-- PC-PLATFORM-EVIDENCE-START -->
-<!-- PC-PLATFORM-EVIDENCE-END -->
-
-## Report
-
-One block: the `status` (passed/skipped/failed/blocked) and why; capturePlan written or why not. Never present a blocked capture as passed.
+---
+name: pc-ops-evidence
+description: Writes a capturePlan in evidence.json for the Visual Evidence CI workflow to execute on a runner with Docker and Chrome access. Load after a change is implemented. Invoked by /ops-evidence.
+license: MIT
+---
+
+# Ops Evidence
+
+Write a capture plan so the Visual Evidence CI workflow can capture screenshots on a runner with full Docker and Chrome access.
+
+The agent runs inside the awf sandbox where Docker-in-Docker is unsupported and headless Chromium's sandbox is blocked by the container security policy. The agent cannot capture screenshots itself. Instead, it analyzes the diff and writes a `capturePlan` in `evidence.json`. A separate CI workflow executes the plan.
+
+## Convention
+
+Every platform project has `pnpm run dev` at root that starts the **full stack** (database + API + web). The app runs with mock auth in development mode (no real authentication needed). This is the only contract — no per-project evidence harness, fixture apps, or scenario registries.
+
+## Input
+
+The caller provides (all optional):
+- change id: locates `openspec/changes/{change-id}/` (or the archived `archive/*{change-id}/`).
+- issue / work-item ref and PR number: where to publish.
+- output mode (`default` / `push` / `pr`): whether the branch was pushed.
+- operation: `capture` (default), `publish`, or `both`.
+
+## Part 1: Capture (operation: capture / both)
+
+**Step 1: Decide whether evidence is required.** Inspect the change's diff:
+- Required when changed files include user-visible UI: `*.tsx/jsx/vue/svelte`, `*.css/scss/less`, pages, layouts, components, navigation.
+- Skipped when docs-only, internal refactor, dependency-only, test-only, backend-only.
+- Mixed or unknown: required (be safe).
+
+If skipped: write `evidence.json` with `status: "skipped"` and reason. Done.
+
+**Step 2: Discover routes from git diff.** Parse changed files to determine which routes to screenshot:
+- `pages/**/*.tsx` or `app/**/page.tsx` → extract the route path
+- `features/**/*.tsx` or `components/**/*.tsx` → screenshot the homepage and any routes that import the changed component
+- If no routes found → screenshot `/` only
+- Always include `/` (homepage) as a baseline
+
+**Step 3: Write `evidence.json` with `capturePlan`.** The agent never attempts to start the app stack or launch a browser — those always fail inside the awf sandbox. Instead, write a `capturePlan` immediately.
+
+### The `capturePlan` schema
+
+```
+capturePlan:
+  routes:           # Array of route objects to screenshot (at minimum [{ path: "/" }])
+    - path: string  # URL path, e.g. "/items/:id"
+      sampleId:     # string | "first" | "any" — how to resolve dynamic segments
+      caption:      # string — human-readable description of what this screenshot shows
+  viewports:        # Array of viewport objects
+    - width: number
+      height: number
+      label: string # "desktop" | "mobile" | custom
+  requireApi:       # boolean — true when the route needs the backend API running
+  requireLogin:     # boolean — true when the route needs authentication
+  loginMethod:      # string — "mock-sso" | "none" | custom method identifier
+  reason:           # string — why evidence was blocked and what the screenshots should show
+```
+
+### Rules for writing capturePlan
+
+1. `routes` MUST always include `{ path: "/", caption: "Homepage" }` as the first entry.
+2. Every additional route discovered from the diff goes after the homepage entry.
+3. `sampleId: "first"` means the CI workflow should use the first record returned by the API. `sampleId: "any"` means any valid ID.
+4. `requireApi` is `true` when any route needs the backend to return data. It is `false` only for purely static pages (login, not-found).
+5. `requireLogin` is `true` when any route needs authentication. For dev mode with mock auth, `loginMethod` is `"mock-sso"`.
+6. `reason` should explain both WHY capture was blocked and WHAT the screenshots should show once captured.
+
+### Example `evidence.json`
+
+Adapt the routes and captions to this repository. Edits between the
+`PC-PROJECT-EXAMPLE` markers are carried over when the harness updates;
+anything outside them is replaced by the shipped version.
+
+<!-- PC-PROJECT-EXAMPLE-START -->
+```json
+{
+  "version": 1,
+  "changeId": "status-badge-in-detail-panel",
+  "required": true,
+  "status": "blocked",
+  "assets": [],
+  "capturePlan": {
+    "routes": [
+      { "path": "/", "sampleId": "any", "caption": "Homepage" },
+      { "path": "/items/:id", "sampleId": "first", "caption": "Item detail with the new status badge" }
+    ],
+    "viewports": [
+      { "width": 1280, "height": 720, "label": "desktop" },
+      { "width": 375, "height": 667, "label": "mobile" }
+    ],
+    "requireApi": true,
+    "requireLogin": true,
+    "loginMethod": "mock-sso",
+    "reason": "Status badge added to the item detail panel; visual change on the detail page."
+  },
+  "reason": "Visual evidence cannot be captured inside the awf sandbox (Docker-in-Docker unsupported, headless Chromium sandbox blocked). A capturePlan has been written for the Visual Evidence CI workflow.",
+  "prMarkdown": "## Evidence\n\nVisual evidence for this change is **blocked** in this agent run. A `capturePlan` has been written to `evidence.json` — the Visual Evidence CI workflow will execute it on a runner with full Docker and Chrome access.\n\nAutomated verification that did run:\n- Lint: clean\n- Tests: all pass\n- Build: success"
+}
+```
+<!-- PC-PROJECT-EXAMPLE-END -->
+
+### When evidence is not required
+
+If evidence is skipped (no UI files changed), write without a `capturePlan`:
+
+```json
+{
+  "version": 1,
+  "changeId": "{change-id}",
+  "required": false,
+  "status": "skipped",
+  "assets": [],
+  "reason": "No user-visible UI files changed in this PR.",
+  "prMarkdown": "## Evidence\n\nSkipped: no user-visible UI changes."
+}
+```
+
+Capture never commits, stages, or pushes. The caller owns git.
+
+## Part 2: Publish (operation: publish / both)
+
+Preconditions:
+- An issue/PR number was provided. Else skip.
+- Image URLs resolve only if the branch was pushed (`pr`/`push` modes).
+- Backlog platform from `.opencode/harness.json`; `none` means skip.
+
+<!-- PC-PLATFORM-EVIDENCE-START -->
+<!-- PC-PLATFORM-EVIDENCE-END -->
+
+## Report
+
+One block: the `status` (passed/skipped/failed/blocked) and why; capturePlan written or why not. Never present a blocked capture as passed.

package/harness/.agents/skills/pc-plan-apply/SKILL.md

@@ -15,7 +15,7 @@ The caller provides (all optional):
 ## Modes
 
 - `interactive` (default): report progress to the user and surface failures for their decision.
-- `autonomous`: do not return control between waves; keep looping until every task is DONE or the progress guard / retry limit trips. On a stall or exhausted retry, stop the wave loop and report to the caller (whose failure policy governs). When all tasks are DONE, the APPLY stage is complete. Hand control back to the caller (the `/plan-goal` pipeline) so it continues with the next phase. Do not end the turn here; "report N/N tasks" is a stage boundary, not a finish line.
+- `autonomous`: there is no user to return to between waves. Loop until every task is DONE, or until the progress guard or the retry limit trips, then report to the caller, whose failure policy governs. APPLY completes by handing control back to `/plan-goal`, which has four phases left to run: `N/N tasks` is this stage's boundary, not the pipeline's.
 
 ## Plan source detection
 
@@ -25,9 +25,17 @@ The caller provides (all optional):
 
 ## OpenSpec mode: parallel subagent waves
 
-Load `@openspec-apply-change` skill and follow its instructions, replacing Step 6 (Implement) with the protocol below.
+Load `@openspec-apply-change` for change selection, status, and closing. Its
+own implement step does not apply here: annotated tasks are implemented only by
+spawning the annotated tier worker, and the lead never implements. Take that
+step from the protocol below instead.
 
-**Step 6: Implement via native subagent waves. Replace the default step 6 with this protocol.**
+Referring to it by number would break silently. `@openspec-apply-change` is
+installed by `openspec init --force` with no version pinned, so an inserted step
+upstream renumbers the one being replaced, and the sequential default would then
+run alongside these waves.
+
+**Implement via native subagent waves.**
 
 You are the lead. You orchestrate from this session only; you spawn workers with the native `task` tool. Workers are ephemeral (one batch, then they exit) and navigable (`ctrl+x` arrow down, left/right arrows). There is no board, no claiming, no merging, no external dashboard.
 
@@ -35,7 +43,7 @@ Core rule: push, don't pull. A worker is born with its work: every `task()` spaw
 
 **1. Branch.** Create `feature/{change-slug}` if not already on one. (Skip this step when the caller passed `start_from: load-plan`.)
 
-**2. Load the plan and workers.** Parse `tasks.md`. Each task carries `<!-- agent, depends_on, touches -->` (from `pc-plan-propose`). Inspect `.opencode/agents/` for each base engineer and its generated `.<tier>.md` variants. The tier-suffixed name in an annotation (for example, `backend-engineer.build`) is the worker to spawn: `pc-subagent-tiers` resolves its model at startup and registers it as `mode: subagent`. Read `.opencode/harness.json` -> `agents.maxConcurrent` (the wave cap, 1 to 5).
+**2. Load the plan and workers.** Parse `tasks.md`. Each task carries `<!-- agent, depends_on, touches -->` (from `pc-plan-propose`). Inspect `.opencode/agents/` for each base engineer and its generated `.<tier>.md` variants. The tier-suffixed name in an annotation (for example, `backend-engineer.build`) is the worker to spawn: `pc-subagent-tiers` resolves its model at startup and registers it as `mode: subagent`. Read `.opencode/harness.json` -> `agents.maxConcurrent` (the wave cap, 1 to 5, enforced by `pc-subagent-monitor`).
 
 Before hydrating the Todo board, resolve every task's annotated worker. If any task has a blank agent annotation, its base template is missing, or its tier variant is unavailable, stop the APPLY stage and report the task ID, expected worker, and missing file. Do not replace the worker with `fullstack-engineer`, `general`, or the lead session.
 
@@ -58,7 +66,8 @@ if eligible is empty but tasks remain  -> STALL: report blocked tasks + the fail
 groups   = pack eligible tasks that share a file (touches and gathered context)
             into ONE worker each, to run sequentially (the worker uses the task's `agent`)
 wave     = pick groups whose file-sets are pairwise DISJOINT, capped at maxConcurrentAgents
-            (you enforce the cap: opencode runs every task() you emit at once)
+            (opencode runs every task() you emit at once; a spawn past the cap
+             is denied, and a denied spawn is not a failed group: re-issue it)
 ```
 
 **6. Context per group.** For each group, gather the task text, relevant plan decisions, and source context needed to implement it.

package/harness/.agents/skills/pc-plan-apply/simple-mode.md

@@ -1,21 +1,21 @@
-# Simple mode: sequential in-session
-
-When the plan lives in the Todo pane (from `/plan-quick`) and no OpenSpec change exists:
-
-1. Read the task list from the Todo pane (the `pending` items created by `/plan-quick`).
-2. Create a feature branch if not already on one: `git switch -c feature/{slug}`. (Skip when the caller passed `start_from: load-plan`.)
-3. Work through tasks one at a time, in order, directly in this session:
-   - Read the task text from the Todo item.
-   - Mark it `in_progress` via `todowrite`.
-   - Implement it (edit files, run commands as needed).
-   - Mark it `completed` via `todowrite`.
-   - Commit the change: `git add <the paths this task wrote> && git commit -m "task {id}: {summary}"`. Never `-A` or `.`: a working tree is shared, and staging all of it commits somebody else's edits, possibly half-finished, under your message.
-4. After all tasks are done, run the project's typecheck/build check if one exists. Fix any errors.
-5. Report: tasks N/N completed, commits made, branch name.
-
-Rules:
-- Work in this session only. No subagent spawning.
-- No OpenSpec commands.
-- Keep each commit focused on one task.
-- Use `todowrite` to track progress: `pending` -> `in_progress` -> `completed`.
-- If a task is too complex or blocked, mark it `completed` with a note, and continue with the next.
+# Simple mode: sequential in-session
+
+When the plan lives in the Todo pane (from `/plan-quick`) and no OpenSpec change exists:
+
+1. Read the task list from the Todo pane (the `pending` items created by `/plan-quick`).
+2. Create a feature branch if not already on one: `git switch -c feature/{slug}`. (Skip when the caller passed `start_from: load-plan`.)
+3. Work through tasks one at a time, in order, directly in this session:
+   - Read the task text from the Todo item.
+   - Mark it `in_progress` via `todowrite`.
+   - Implement it (edit files, run commands as needed).
+   - Mark it `completed` via `todowrite`.
+   - Commit the change: `git add <the paths this task wrote> && git commit -m "task {id}: {summary}"`. Unscoped staging is denied (`pc-system-reminders`).
+4. After all tasks are done, run the project's typecheck/build check if one exists. Fix any errors.
+5. Report: tasks N/N completed, commits made, branch name.
+
+Rules:
+- Work in this session only. No subagent spawning.
+- No OpenSpec commands.
+- Keep each commit focused on one task.
+- Use `todowrite` to track progress: `pending` -> `in_progress` -> `completed`.
+- Never mark a task `completed` that you did not finish. Use `cancelled` with the reason and continue with the next; a false green is invisible to whoever reads the report.

package/harness/.agents/skills/pc-plan-archive/SKILL.md

@@ -1,66 +1,66 @@
----
-name: pc-plan-archive
-description: Archive a completed OpenSpec change and update documentation. Interactive mode finds the oldest merged unarchived change and opens an archive PR; autonomous mode archives a named change in place on the current branch. Invoked by the /plan-archive command (interactive) and the plan-goal pipeline (autonomous).
-license: MIT
----
-
-# Plan Archive
-
-<!-- PC-OPTIMIZATION-MEMORY-START -->
-<!-- PC-OPTIMIZATION-MEMORY-END -->
-
-## Input
-
-The caller provides (all optional):
-- A mode (see below). Default: `interactive`.
-- In autonomous mode: the change id to archive (required in that mode; the caller knows which change it just implemented).
-
-## Modes
-
-- interactive (default): full flow below. Find the oldest unarchived change with a completed PR, confirm with the user, archive it, update docs with approval, and open an archive PR. No input required.
-- autonomous: the caller names the change to archive. Skip the working-tree prep, the PR lookup, the confirmation prompt, and the archive-PR step. Instead, archive in place on the current branch:
-  1. Archive the change by its id. Prefer the `@openspec-archive-change` skill if it is available. If it is not available, run the CLI directly, and it must be non-interactive, because there is no user to answer prompts:
-
-     ```bash
-     openspec archive "<change-id>" -y
-     ```
-
-     `-y` skips the confirmation prompt (without it the command blocks forever in an unattended run). Add `--skip-specs` only for infra/tooling/doc-only changes that produced no spec deltas. If the command reports the change is already archived, treat that as success.
-  2. Verify the archive actually moved. The change folder must no longer exist at `openspec/changes/<change-id>/`, and a dated copy must now exist under `openspec/changes/archive/` (the CLI renames it to `archive/YYYY-MM-DD-<change-id>/`):
-
-     ```bash
-     REPO_ROOT="$(git rev-parse --show-toplevel)"
-     test ! -d "$REPO_ROOT/openspec/changes/<change-id>" \
-       && ls -d "$REPO_ROOT/openspec/changes/archive/"*"<change-id>" >/dev/null 2>&1 \
-       && echo ARCHIVED_OK || echo ARCHIVE_FAILED
-     ```
-
-      If this prints `ARCHIVE_FAILED`, run the archive once more and repeat the check. If it still fails, report it to the caller as a failure; do not pretend it succeeded.
-  3. Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`; apply any needed doc updates directly (no approval prompt).
-  4. If the change was a bug fix or new functionality with important impact, check if `@pc-guardrails-project` exists and update it.
-  5. Do not commit or push: the caller owns the git operations.
-   6. The ARCHIVE stage is complete. Hand control back to the caller (the `/plan-goal` pipeline) so it continues with evidence and output. Do not stop or end the turn here; archiving is not the end of the run.
-
----
-
-## Interactive flow
-
-Steps
-
-1. Prepare working tree
-
-   ```bash
-   REPO_ROOT="$(git rev-parse --show-toplevel)"
-   DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
-   [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
-   ```
-
-   1. If the tree has uncommitted changes: `git stash push -u -m "WIP before archive"` and tell the user their work is stashed (it is restored in step 6).
-   2. Sync the default branch (skip the pull if there is no `origin` remote):
-
-   ```bash
-   git switch "$DEFAULT_BRANCH" && git pull origin "$DEFAULT_BRANCH"
-   ```
-
-<!-- PC-PLATFORM-ARCHIVE-START -->
-<!-- PC-PLATFORM-ARCHIVE-END -->
+---
+name: pc-plan-archive
+description: Archive a completed OpenSpec change and update documentation. Interactive mode finds the oldest merged unarchived change and opens an archive PR; autonomous mode archives a named change in place on the current branch. Invoked by the /plan-archive command (interactive) and the plan-goal pipeline (autonomous).
+license: MIT
+---
+
+# Plan Archive
+
+<!-- PC-OPTIMIZATION-MEMORY-START -->
+<!-- PC-OPTIMIZATION-MEMORY-END -->
+
+## Input
+
+The caller provides (all optional):
+- A mode (see below). Default: `interactive`.
+- In autonomous mode: the change id to archive (required in that mode; the caller knows which change it just implemented).
+
+## Modes
+
+- interactive (default): full flow below. Find the oldest unarchived change with a completed PR, confirm with the user, archive it, update docs with approval, and open an archive PR. No input required.
+- autonomous: the caller names the change to archive. Skip the working-tree prep, the PR lookup, the confirmation prompt, and the archive-PR step. Instead, archive in place on the current branch:
+  1. Archive the change by its id. Prefer the `@openspec-archive-change` skill if it is available. If it is not available, run the CLI directly, and it must be non-interactive, because there is no user to answer prompts:
+
+     ```bash
+     openspec archive "<change-id>" -y
+     ```
+
+     `-y` skips the confirmation prompt (without it the command blocks forever in an unattended run). Add `--skip-specs` only for infra/tooling/doc-only changes that produced no spec deltas. If the command reports the change is already archived, treat that as success.
+  2. Verify the archive actually moved. The change folder must no longer exist at `openspec/changes/<change-id>/`, and a dated copy must now exist under `openspec/changes/archive/` (the CLI renames it to `archive/YYYY-MM-DD-<change-id>/`):
+
+     ```bash
+     REPO_ROOT="$(git rev-parse --show-toplevel)"
+     test ! -d "$REPO_ROOT/openspec/changes/<change-id>" \
+       && ls -d "$REPO_ROOT/openspec/changes/archive/"*"<change-id>" >/dev/null 2>&1 \
+       && echo ARCHIVED_OK || echo ARCHIVE_FAILED
+     ```
+
+      If this prints `ARCHIVE_FAILED`, run the archive once more and repeat the check. If it still fails, report it to the caller as a failure; do not pretend it succeeded.
+  3. Compare the archived change's specs against `ARCHITECTURE.md` and `DESIGN.md`; apply any needed doc updates directly (no approval prompt).
+  4. If the change was a bug fix or new functionality with important impact, check if `@pc-guardrails-project` exists and update it.
+  5. Do not commit or push: the caller owns the git operations.
+   6. The ARCHIVE stage is complete. Hand control back to the caller (the `/plan-goal` pipeline) so it continues with output. Do not stop or end the turn here; archiving is not the end of the run.
+
+---
+
+## Interactive flow
+
+Steps
+
+1. Prepare working tree
+
+   ```bash
+   REPO_ROOT="$(git rev-parse --show-toplevel)"
+   DEFAULT_BRANCH="$(git symbolic-ref --short refs/remotes/origin/HEAD 2>/dev/null | sed 's|^origin/||')"
+   [ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
+   ```
+
+   1. If the tree has uncommitted changes: `git stash push -u -m "WIP before archive"` and tell the user their work is stashed (it is restored in step 6).
+   2. Sync the default branch (skip the pull if there is no `origin` remote):
+
+   ```bash
+   git switch "$DEFAULT_BRANCH" && git pull origin "$DEFAULT_BRANCH"
+   ```
+
+<!-- PC-PLATFORM-ARCHIVE-START -->
+<!-- PC-PLATFORM-ARCHIVE-END -->

package/harness/.agents/skills/pc-plan-explore/SKILL.md

@@ -4,9 +4,26 @@ description: Explore an idea or requirement before planning. Invoked by the /pla
 license: MIT
 ---
 
-**READ-ONLY MODE.** From the moment this skill is loaded until the user explicitly invokes a different command (e.g. `/plan-apply`) or explicitly requests implementation, you MUST NOT write, edit, or create any file, including OpenSpec artifacts. You may only read, search, and discuss. If the conversation drifts toward implementation, remind the user that explore mode is active and suggest `/plan-apply` to start implementing. This overrides any permissive stance in `@openspec-explore` about creating OpenSpec artifacts being "fine."
+Explore, then hand back what you learned. `@openspec-explore` supplies the
+stance; this skill adds one prohibition and one handoff.
 
-Load `@openspec-explore` and follow every step defined in it.
+## Rules
+
+- Never write, edit, or create a file while this skill is loaded, OpenSpec
+  artifacts included. This overrides `@openspec-explore`, which says creating
+  them is "fine". Reading, searching, and discussing are the whole job.
+- If the conversation turns toward implementation, say explore mode is active
+  and point at `/plan-apply`.
+
+Load `@openspec-explore` for the approach.
+
+## Autonomous handoff
+
+When a caller loads this skill in autonomous mode, return `EXPLORATION_BRIEF`
+in memory rather than writing a file. It holds: the problem in one or two
+sentences, the affected paths, the approach chosen, the risks worth knowing,
+and anything deliberately out of scope. `pc-plan-goal` requires it before its
+propose phase.
 
 <!-- PC-OPTIMIZATION-MEMORY-START -->
 <!-- PC-OPTIMIZATION-MEMORY-END -->

package/harness/.agents/skills/pc-plan-goal/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pc-plan-goal
-description: Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering. Invoked by the /plan-goal command.
+description: "Autonomous pipeline: explore, propose, apply, archive, then merge/PR/push. For loop-engineering. Invoked by the /plan-goal command."
 license: MIT
 ---
 
@@ -14,7 +14,7 @@ Move forward only when a phase returns its required result. On a hard failure, f
 
 **Token efficiency rules:** Batch git operations within a phase (combine `git add <paths> && git commit` in one tool call). Do not run status checks between sequential operations in the same phase. Minimize model turns: if a phase requires 3 git commands, call them in one tool call, not 3.
 
-**Stage paths, never `git add -A` or `git add .`.** A working tree is shared: a person or another agent may have edits in it, and staging everything puts their work in your commit under your message. It is not hypothetical. A Teams tool and its tests were committed inside a commit named after a YAML input rename, and nothing in that message said so. Two things go wrong, and the second is worse: the history lies about what changed, and unreviewed or half-finished work reaches the default branch under a heading nobody would look twice at. Saving a model turn is not worth either.
+Stage the paths a phase wrote; unscoped staging is denied (`pc-system-reminders`). A shared tree once put a Teams tool and its tests inside a commit named after a YAML input rename, so unreviewed work reached the default branch under a heading nobody would look twice at.
 
 Input: `$ARGUMENTS`
 
@@ -30,7 +30,9 @@ Load the [output mode](output-mode.md) reference and resolve the mode from the f
 - Preserve title, description, work-item reference, and acceptance criteria as `{resolved_input}`.
 - Derive `{slug}` and classify scope as `focused`, `standard`, or `complex`.
 
-**Refined-issue detection:** After resolving input, check whether `{resolved_input}` already contains structured acceptance criteria (e.g. "## Acceptance criteria", "### Scenario:", Gherkin blocks), affected artifacts, and design decisions. If it does, set `{refined}` to `true` and skip Phases 2-3 (Explore and Propose). Go directly to Phase 4 (Apply). The issue content IS the proposal; create a minimal OpenSpec change (tasks.md only, `skip_specs: true` in `.openspec.yaml`) directly from the issue's acceptance criteria and affected artifacts.
+**Refined-issue detection:** set `{refined}` to `true` only when all three hold. The input came from a backlog work item, not free text. It contains at least one `Scenario:` with `Given` / `When` / `Then`. It names affected paths, and at least one of them exists in this repository. Anything less runs Phases 2 and 3 in full: `{refined}` skips a gate, so a near miss must fall back rather than guess.
+
+When it is `true`, the issue content is the proposal. Phase 2 is skipped and Phase 3 runs with `skip_specs: true`.
 
 ## Phase 1: Branch
 
@@ -46,10 +48,10 @@ Tick `explore` when `pc-plan-explore` returns its findings handoff.
 
 ## Phase 3: Propose
 
-**Skip if `{refined}` is `true`.** Instead, create a minimal OpenSpec change directly: run `openspec new change "{change-id}"`, write `tasks.md` from the issue's acceptance criteria (one task per criterion or artifact group), create `.openspec.yaml` with `skip_specs: true` (the issue already has the spec content), and commit: `git add openspec/changes/{change-id}/ && git commit -m "propose: {title} ({change-id})"`.
-
 Load `pc-plan-propose` in autonomous mode with `{resolved_input}`, `EXPLORATION_BRIEF`, and `scope_classification`.
 
+**When `{refined}` is `true`,** pass the work item as the proposal body and set `skip_specs: true` in `.openspec.yaml`: the issue already carries the spec content. Propose still runs, because it owns task enrichment. A hand-written `tasks.md` has no `<!-- agent, depends_on, touches -->` annotations, and Phase 4 stops on a task whose worker is unresolved.
+
 Confirm its change directory and actionable `tasks.md` exist. Rename `$BRANCH` when the canonical change slug differs from `{slug}`, then commit the proposal:
 
 ```bash

package/harness/.agents/skills/pc-plan-goal/output-mode.md

@@ -4,6 +4,7 @@ Determine the mode only from the first whitespace-delimited token of `$ARGUMENTS
 
 - `pr`: remove the token, push the feature branch, and create a PR.
 - `push`: remove the token and push the feature branch.
+- `branch`: remove the token, keep the feature branch, merge nothing and push nothing.
 - Any other first token: keep the full input and merge locally into the default branch.
 
 Words such as "push notifications" or "PR template" inside the feature description are feature data. They do not change output mode.