Prospec Upgrade

---
name: prospec-upgrade
description: "Prospec Version Upgrade Finisher - after `prospec upgrade` records the version, syncs agents, and reports gaps, work through the report's docs inventory: update init-created files whose format drifted and create missing ones (asking consent per file), then localize triggers for newly-added skills and re-sync. Triggers: upgrade prospec, prospec upgrade, migrate prospec version, 升級 prospec, prospec 升級, 遷移 prospec 版本"
---
<!-- Generated by `prospec agent sync`. Do not edit — this file is regenerated on every sync. -->

# Prospec Upgrade Skill

## Activation

When triggered, briefly describe:
- That `prospec upgrade` has recorded the new prospec version in `.prospec.yaml` and re-synced agents, and you'll finish the judgment steps it cannot do deterministically
- You'll work through the report's docs inventory (every file `prospec init` creates): `prospec upgrade` has already back-filled any that were missing, so you offer to update any whose format has drifted from the latest templates and to enrich the docs it just created that need more than a baseline (e.g. the index's real module table) — asking before each change — plus, as a safety net, create any still marked missing; offer to set an artifact language if the project never chose one (a project from a pre-feature CLI); and localize triggers for skills that have none
- This is a periodic upgrade flow — re-runnable and self-terminating

## Language Policy

Write each generated document in the language the Constitution's Language Policy rule assigns to **its path** — change artifacts and their archived summaries in the project's artifact language, the trust zone (Knowledge base, Feature Specs, index) in English. One skill run may write both. Keep code, identifiers, technical terms, and git commit messages in English.
## CLI Prerequisite (required)

> The prospec CLI is a required file for this skill — its deterministic steps call `prospec`
> commands. Probe BEFORE any other step; there is no manual fallback.

1. Run `prospec --version` (Bash).
2. **Command not found / not executable** → STOP. Ask the user to install the prospec standalone
   executable — the one-click installer script from the project README (macOS/Linux `install.sh`,
   Windows `install.ps1`) or a release binary from GitHub Releases; prospec is NOT published to
   npm. Then re-run this skill.
3. **Version older than 2.0.0** → STOP. Report the installed vs required version
   and ask the user to upgrade, then re-run this skill.

Hand-executing a CLI-owned mutation is NEVER the fallback — that re-introduces the
nondeterministic serialization this contract exists to remove.

## Startup Loading

1. [DYNAMIC] Read `.prospec.yaml` — `version`, `artifact_language`, and `skill_triggers` drive the steps below

## Core Workflow

> This skill shells out to the `prospec` CLI (Bash) throughout. The CLI probe is the shared
> CLI Prerequisite above — a missing or outdated CLI is a STOP, never a graceful degrade.

### Step 1: Run the deterministic upgrade

Run `prospec upgrade --no-interactive` (Bash) and read its stdout. The `--no-interactive` flag is
required: without it `prospec upgrade` prompts to fill nudges on a terminal, which would block this
Bash call — you drive those choices in-conversation (Steps 3–4) instead. It has already (a) recorded
the running prospec version in `.prospec.yaml` `version` (comment-preserving in-place merge), and
(b) re-run `agent sync`. Parse the **Upgrade report**:
- `version <from> → <to>` — the prospec version delta
- `no artifact_language set …` — the project predates the artifact-language feature and never chose a
  language (Step 3).
- `skills missing triggers: …` — newly-added skills with no localized triggers (Step 4)
- `Docs inventory:` — one line per init-created doc, `✓ <path> (template: <hbs>)` when present or
  `✗ <path> — MISSING (template: <hbs>)` when absent. `[canonical]` identifies a whole-file canonical
  document; `[preserves-user-content]` additionally identifies a canonical generated/static format with
  a preserved authored user block. The lines are reported AFTER `prospec upgrade` back-filled the missing
  ones (so most read present), then a `created N missing doc(s): …` line names what it just wrote. This
  section is Step 2's authoritative scan scope. A line still marked MISSING means its back-fill failed —
  Step 2's safety net.
- `stale Language Policy wording: …` — the seeded Language Policy rule in `prospec/CONSTITUTION.md` still
  carries the pre-path-scoped wording, which contradicts the entry config (Step 2.5). It is immediately
  followed by a `Current Language Policy rule:` block holding the replacement wording — **carry that
  block forward verbatim**; Step 2.5 has no other source for it.

If `prospec upgrade` fails with `ConfigNotFound`, the project is not initialized — STOP and tell the
user to run `prospec init` first.

### Step 2: Refresh init-created docs (inventory → enrich/diff → consent)

`prospec upgrade` now BACK-FILLS any missing init doc (deterministic render, skip-if-exists) but never
touches an EXISTING one — updating a present doc's format, or enriching a freshly-created doc beyond its
baseline, requires consent. Do that here:

1. **Retrieve the latest templates** shipped with the installed prospec version by running the CLI
   command `prospec print-template <template_path>` (Bash).
   For example, to get the template for `init/constitution.md.hbs`, run `prospec print-template init/constitution.md.hbs`.
   If the template cannot be retrieved, say so and SKIP this step (do not guess the latest format).
2. **Take the scan scope from Step 1's `Docs inventory:` section** — every line names an init-created
   doc, its present/MISSING status, and its source template path. That list is the ONLY scan scope:
   do not keep, reconstruct, or fall back to a file list written into this skill. If the report has
   no `Docs inventory:` section, the installed CLI predates it (CLI/skill version mismatch) — STOP
   this step and tell the user to re-run `prospec upgrade` (which re-syncs this skill to match the
   CLI), then re-run `prospec-upgrade`.
3. **Index enrichment**: `prospec upgrade` back-fills `prospec/index.md` as a BASELINE — its
   module table is empty. Offer to populate that table from the current modules, preserving any
   user notes in the `<!-- prospec:user-start -->` block. A later `prospec knowledge update` run is
   safe: it backfills curated content columns from index.md into `module-map.yaml` no-clobber before
   regenerating the auto block.
4. **Back-fill safety net** — `prospec upgrade` already created every doc it could (the report's
   `created …` line), so the inventory should show them present. For any doc the inventory **still
   marks MISSING** (its back-fill failed), offer to create it by rendering its listed template.
   Creating a file risks no authored content, but still **ask before each creation** and show what
   will be written; leave declined files uncreated.
5. **For each doc the inventory marks present**, compare it to its listed template:
   - **If the line has both `[canonical] [preserves-user-content]` markers**, compare only its
     **generated/static format** (CRLF normalized). On consent, refresh only that generated/static
     format and preserve the registry user block byte-for-byte. If the existing document is a
     **marker-less legacy** document (it lacks a usable auto/user boundary), never whole-file replace
     it: show a **no-clobber migration diff** that makes the preserved boundary explicit, and proceed
     only after consent. If that diff cannot preserve the registry user block, leave the document
     unchanged and report the migration as blocked.
   - **If the line has `[canonical]` but lacks `[preserves-user-content]`**, it has no authored wording.
     Compare the **full content** (CRLF normalized). If it has drifted, **show a diff and ask the user
     whether to overwrite it** with the template content.
   - **If the line lacks the marker** (user-managed), compare the **format/structure** (severity tags, section markers) only, never the user's authored wording. If the format has drifted, **show a diff and ask the user whether to update it** — migrate the FORMAT only, preserving authored content.
   Apply only the files the user approves; leave the rest unchanged.

### Step 2.5: Migrate the seeded Language Policy wording (only when flagged)

Run this ONLY when Step 1's report carries the `stale Language Policy wording:` line. It is the one
authored-wording change this skill may propose, because that wording is a **seed** `prospec init` wrote,
not something the owner authored.

1. Take the replacement wording from the report's `Current Language Policy rule:` block — the CLI renders
   it from THIS project's resolved paths and language, so it is ready to paste. Do NOT try
   `prospec print-template init/constitution.md.hbs`: that template only loops over the rules injected into
   it and carries no rule text of its own (the body is generated in code), so retrieval yields nothing. If
   the report has no such block, the installed CLI predates it — say so and SKIP.
2. **Show a diff of the Language Policy section only** and ask whether to rewrite it.
3. On consent, replace **only that principle's `Description` / `Rationale` / `Verify` body** — leave its
   heading, severity tag, every other principle, the Constraints/Quality-Standards checklists, and all
   user-authored text byte-unchanged. Re-read the file afterwards to confirm the section structure still
   parses (heading + `---` separators intact).
4. If the user declines, leave the file untouched and record it as declined; the next upgrade offers again.

### Step 3: Offer to set an artifact language (only when unset)

Run this step ONLY when Step 1's report shows `no artifact_language set` (a project scaffolded by a
pre-feature CLI — `prospec init` always writes the field). Skip it entirely otherwise; never re-ask a
project that already chose a language, including an explicit `English`.

1. Tell the user their project has no `artifact_language`, so change artifacts currently default
   to **English**, and ask which language they want for them (default: English; the trust zone stays
   English either way).
2. **If they choose a non-English language**: capture `.prospec.yaml` verbatim as a snapshot, add the
   `artifact_language` key by a **minimal in-place edit** (insert the single key; never re-serialize or
   reorder), then read the file back to confirm it still parses — restore the snapshot if not. Every
   skill is now unlocalized, so Step 4 will localize them all.
3. **If they keep English**: add `artifact_language: English` by the same minimal in-place edit (so this
   prompt is self-terminating on the next upgrade), then skip Step 4 — English uses the baseline
   triggers and needs no `skill_triggers`.

### Step 4: Localize triggers for skills missing them (fill-missing) + re-sync

Re-read `.prospec.yaml` (Step 3 may have just set the language). When `artifact_language` is non-English,
localize every skill that still has **no `skill_triggers` entry** — that is Step 1's "skills missing
triggers" list, plus, when Step 3 just set the language, all skills. Skip entirely when the language is
English or every skill already has an entry.

1. Run `prospec agent triggers` (Bash) to get a ready-to-translate `skill_triggers` scaffold — the skills
   still missing an entry, each with its English baseline sourced from the CLI (authoritative; never grep
   a deployed SKILL.md, whose frontmatter already merges custom words)
2. Translate each scaffold value into `artifact_language` (this skill's judgment step)
3. **Show the proposed translations and wait for confirmation** before writing anything
4. On confirmation, save the translated scaffold to a temp file and run
   `prospec agent triggers --write <file>` (Bash) — the CLI inserts only the missing keys
   (comment- and order-preserving), validates BEFORE writing, and never overwrites an existing entry
5. If anything changed in Step 2, Step 3, or Step 4, run `prospec agent sync` (Bash) so the language,
   localized triggers, and refreshed docs land in each SKILL.md frontmatter and the entry config

## Output Contract

> After running, self-assess and emit a concise Output Summary. Every Success Criterion must be objectively checkable (file existence / grep / test result / count) — no subjective adjectives.

### Success Criteria
- [ ] `prospec upgrade` ran and `.prospec.yaml` `version` equals the installed prospec version
- [ ] every doc in the report's `Docs inventory:` was handled — present docs diffed against their listed template and updated only on consent, the docs `prospec upgrade` back-filled were enriched where needed (including the index module table) on consent, and any still-MISSING doc was offered for creation as a safety net (or templates were unavailable / the inventory section was absent, and the step was skipped with a note)
- [ ] when the report flagged `stale Language Policy wording`, a diff of that section alone was shown and it was rewritten only on consent (or declined / the report carried no `Current Language Policy rule:` block and the step was skipped with a note)
- [ ] when the report flagged `no artifact_language set`, the user was asked which language to use and `artifact_language` was written to their choice (or they declined)
- [ ] every skill in the report's "missing triggers" list (and all skills, when Step 3 just set a non-English language) is localized (or the user declined)
- [ ] `prospec agent sync` ran when Step 2, Step 3, or Step 4 changed anything

### Failure Conditions
- updated an init-created file without showing a diff and getting confirmation
- rewrote the Language Policy section without a diff and confirmation, or touched anything beyond that one principle's body
- created a doc the inventory marked MISSING without asking first
- scanned from a file list hardcoded in this skill instead of the report's `Docs inventory:`
- set `artifact_language` (or wrote `skill_triggers`) without user confirmation
- wrote malformed `artifact_language` or `skill_triggers` to `.prospec.yaml`
- proceeded silently when the `prospec` CLI or its templates were unavailable

### Output Summary
Emit one line: `Met N/M | Unmet: <items> | Overall: PASS|WARN|FAIL | Next: <one-line>`

## NEVER

- **NEVER** update an init-created file without a diff preview AND explicit user confirmation — `prospec upgrade` never touches these, and the skill does so only with consent
- **NEVER** create a doc the inventory marks MISSING without showing what will be written AND asking first
- **NEVER** scan from a file list maintained inside this skill — the report's `Docs inventory:` (derived from init's own registry) is the only scan scope; a parallel list here drifts and re-opens the coverage gap
- **NEVER** rewrite a doc's authored content/intent — migrate only its format/structure to the latest template; the single exception is Step 2.5's seeded Language Policy body, and only after a diff and consent
- **NEVER** whole-file replace a `[preserves-user-content]` document or a marker-less legacy document — use a consented no-clobber migration diff and preserve the registry user block
- **NEVER** run Step 2.5 unprompted — it fires only on the report's `stale Language Policy wording` line, so a rule the owner already reworded is never touched
- **NEVER** set or change `artifact_language` for a project that already has one — Step 3 runs only when the report flags it unset
- **NEVER** set `artifact_language` without first asking the user which language they want
- **NEVER** re-translate or overwrite an existing `skill_triggers` entry — localize only the skills with no entry yet
- **NEVER** write `artifact_language` or `skill_triggers` without reading `.prospec.yaml` back to confirm it still parses
- **NEVER** proceed silently when the `prospec` CLI or its templates are unavailable — stop or skip with a note, then let the user decide

## Error Handling

| Scenario | Action |
|----------|--------|
| `prospec` CLI unavailable | Stop; tell the user to install/rebuild prospec, then re-run — do not proceed silently |
| `prospec agent sync` reports no configured agent | Stop and instruct the user to re-run `prospec init` or add an agent to `.prospec.yaml` |
| `.prospec.yaml` fails to parse after writing `artifact_language` | Restore the captured pre-write snapshot verbatim, then report the malformed write (triggers go through `prospec agent triggers --write`, which validates before writing) |