agentic-flow-kit 1.8.7 → 2.0.0

package/locales/en/overrides/.agents/skills/papercut-fix/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: papercut-fix
+description: Fix a designated un-escalated papercut entry in workflow/papercuts.md (the loop executor that drives outstanding debt to 0). Locate the symptom by the line number given in the instruction/ledger, change the authoritative file per the "Planned fix" column, write back to the ledger, and run the verification gates; also used for mining recurring error classes and choosing an enforcement layer when the same mistake keeps recurring.
+---
+
+# papercut-fix — Single-papercut escalation executor
+
+## Goal
+Update the status of one designated papercut entry in `workflow/papercuts.md` to "debt cleared".
+
+## Triggers
+- User command: `跑一轮 papercut 回路` / `清 papercut 存量` / `修第 N 条 papercut`.
+- User command: `跑一轮错题回路` / `同一类错又犯了` / `把这类错固化` → go through §0 first, then §1–§4 one entry at a time.
+
+## 0. Recurring-error loop (batch mode, mutually exclusive with single-item mode)
+
+Only treats mistakes that the **engine face** repeatedly makes (business-code debt follows the incident flow and does not enter this loop). Four sources, default window the last 3 calendar months:
+
+| Source | How to read |
+|---|---|
+| `.agents/judgments.jsonl` | `node .agents/scripts/agg-judgments.mjs --retire-candidates` (per-rule counts and candidates) |
+| `workflow/delegations.md` | rework-reason enum distribution + monthly aggregate snapshot |
+| `workflow/reviews.d/<YYYY-MM>.md` | per-comment accepted/rejected/false-positive, merged by root-cause direction |
+| `workflow/incidents/` | root-cause enum (engine-face entries only) |
+
+**Clustering threshold**: establish a rule only when the same error class occurs ≥3 times; for a single occurrence record only a papercut (if actionable) and do not establish a rule—avoid overfitting a single instance.
+
+> Data-plane note: `judgments.jsonl` / `verifications.jsonl` are gitignored local runtime state; a fresh clone / new worktree may have only scattered rows. When a source is missing, use `delegations.md`, `reviews.d/`, `incidents/` as the basis; **do not fabricate an error class because a source is missing**; if there are fewer than 3 occurrences in the window, write "insufficient data" and do not establish a rule.
+
+**Enforcement ladder** (choose the highest feasible layer; any downgrade must state why the higher layer is infeasible):
+
+| Layer | Means | Infeasibility signal |
+|---|---|---|
+| 1 | Types / compile time (types, schema, enums, contracts) | Cannot express the constraint |
+| 2 | Gate script or hook (check-loop segment, commit-check, verify gate) | False positives cannot be suppressed, or trigger frequency cannot sustain it |
+| 3 | Automated test (dotnet test / vitest / engine `*.test.mjs`) | Environment unreachable, non-deterministic |
+| 4 | Smoke script (`regression-smoke.mjs` script group) | Cannot assert (purely visual/interactive) |
+| 5 | Command / skill / role text (prompt-only) | None (last resort) |
+
+- Landing at layer 5: prefix the **symptom column** of the new row in `workflow/papercuts.d/` with `[prompt-only]`, carrying the debt until a later escalation.
+- Landing at layer 2 with a new gate: must also register in `mechanism-registry.md` (including the retirement threshold) and obey the `rule-budgets.txt` one-in-one-out rule.
+- Relation to existing conventions: rules 5/7 in `workflow/regression-checklist.md` are this ladder specialized for regression entries (layer 3–5 order + enforcer column); do not establish a second system.
+
+**Output** (table first, then act): `error class | count | evidence location | current enforcer | gap | chosen layer | files to change`. After confirmation, enter §1–§4 one entry at a time; each round still handles only one.
+
+## Constraints and red lines
+- **Single target**: each execution handles only one target; do not opportunistically fix adjacent entries or bundle other changes.
+- **Scope limit**: changes are limited to the documentation surface (`.agents/commands/`, `.agents/roles/`, `.agents/skills/`, `.githooks/`, `.agents/scripts/`, `workflow/`).
+- **Absolute no-go**: do not modify `backend/`, `frontend/`, `tests/`, `wiki/`, and do not connect to a database. Stop and report to the user when out of scope.
+- **Verify before acting**: do not guess the current state from the ledger description. Read the authoritative file first to verify that the symptom holds.
+- **Edit convention**: modify `workflow/` documents with `node .agents/scripts/rewrite-file.mjs <file> --find <literal string> --replace <literal string>` (same as `stages.md` Build §4).
+- **Debt-clearing criterion**: branch A (fix) and branch B (deferred/obsolete) **both** satisfy the `debt -1` invariant (debt = number of pending-fix
+  rows in the ledger, manually counted: the touched row carries a terminal marker and no new pending row is added; the scheduled-debt sensor was retired 2026-11-08).
+
+## Workflow
+
+### 1. Locate and pre-check
+- Extract from the given instruction: `line number` (Lxx), `location` (path), `symptom`, `planned fix`.
+- Use the Read tool to read that line and its context.
+
+### 2. Verify the current state
+- Read the authoritative file specified in the "Location" column.
+- **Verdict**:
+    - **Defect still present** $\rightarrow$ enter branch A.
+    - **Already obsolete** (fixed by another change / file deleted) $\rightarrow$ enter branch B.
+    - **Opposite direction / description wrong** $\rightarrow$ re-characterize before executing.
+
+### 3. Execute the fix
+- **Branch A (defect still present)**:
+    1. Apply a minimal fix to the authoritative file.
+    2. Append to the end of that row in `workflow/papercuts.md`: `✅ 已升级修复(YYYY-MM-DD): <改动描述> <commit>`.
+    3. If the original "Planned fix" description no longer applies, state the actual fix in the appended record.
+- **Branch B (already obsolete)**:
+    1. Append to the end of that row in `workflow/papercuts.md`: `⏸ 暂缓(YYYY-MM-DD): <失效理由>`. The reason must be explicit.
+    2. **Verification discipline**:
+        - Check user-level paths (`~/.workbuddy/skills/` etc.) to confirm whether the file was only migrated rather than deleted.
+        - Distinguish "environment constraint" from "code defect".
+        - For "cross-environment" symptoms, use `git worktree` to build a real checkout and run an experiment to falsify.
+        - For "already landed" symptoms, use `git log -S` to trace the date of the introducing commit.
+- **Branch C (out of bounds)**: stop execution, report the reason, and request authorization.
+
+### 4. Verify and wrap up
+- **Backup**: before modifying the ledger, force `cp workflow/papercuts.md tmp/papercuts.wip-backup.md`.
+- **Run checks**:
+    - The touched row already carries a terminal marker (`✅ 已升级修复` / `⏸ 暂缓`), and this round added no new pending row (`debt -1`, manually counted).
+    - Check `workflow/papercuts.md` for total line count, column-count distribution, and any overly long rows (a line-compression signal).
+- **Size check**: if `.agents/commands/` or the root `AGENTS.md` was modified, run `node .agents/scripts/rule-budget.mjs --all` and use its exit code as authoritative.
+
+## Reporting requirements
+- Output per `references/response-template.md`.
+- Include: line number, location, branch verdict (A/B/C), changed files, verification result (touched-row terminal marker / manually counted debt before and after), items awaiting decision.
+- **Prohibition**: do not auto commit or push.

package/locales/en/overrides/.agents/skills/pause-safely/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: pause-safely
+description: Leave a resumable trail before a long run is interrupted or you step away — write a resume brief (state/next step/open items/evidence pointers), stop processes you started, do not commit or delete; use before pausing, going offline, context compression, or a session restart.
+---
+
+# pause-safely — Pausing with a trail
+
+## Triggers
+
+- The user says "stop for now / I'm leaving / continue tomorrow".
+- Context is about to be compressed, or the session is about to restart.
+- A long run (`autonomous-run` / `pipeline-run`) needs to be suspended.
+
+## Steps
+
+1. **Write a resume brief** to `tmp/pause-<slug>.md` (do not commit):
+   - **State**: branch, HEAD short SHA, worktree path, summary of `git status --porcelain -uall`.
+   - **Where you got to**: completed units + corresponding green evidence `headShort` / decision-trail rows.
+   - **Next step**: the first unfinished action, concrete down to file/command.
+   - **Open**: forks awaiting the user's decision, known risks, blocked items.
+   - **Evidence pointers**: checkbox state of `workflow/plans/...`, `decisions.tsv`, `tmp/verify-*.log`, screenshot paths.
+   - **Processes**: services/ports/PIDs you started (record only your own).
+2. **Do not commit, push, or delete**: leave uncommitted changes as-is; ask the user first if a commit is needed.
+3. **Stop processes**: stop only processes started by this session; do not kill by process name, kill by PID/port.
+4. **Resume**: in the new session, rebuild first per `.agents/skills/session-resume/SKILL.md`, then read the resume brief; do not rely on memory.
+
+## Boundaries
+
+- Do not clean worktrees, delete temp files, or `git reset`—pausing is not wrap-up.
+- Do not write the resume brief as a running diary; keep only the facts that let "the next person continue".
+- Do not commit half-finished work; do not use `--no-verify`.

package/locales/en/overrides/.agents/skills/perf/SKILL.md

@@ -0,0 +1,42 @@
+---
+name: perf
+description: Performance investigation playbook — baseline first, then single variable; accept only when retests exceed the noise band; for "slow / laggy / long load / API latency" tasks.
+---
+
+# perf — Performance investigation
+
+## Trigger
+
+- User reports "slow / laggy / long load / API takes N seconds".
+- The approach involves performance tradeoffs that need measurement to decide.
+
+## 0. Define a measurable target first
+
+Metric (LCP / API p95 / list first screen / build time) + scenario (page / API / data volume) + pass line. Cannot articulate the metric → measure first before optimizing; changing based on feeling is forbidden.
+
+## 1. Baseline (same machine / same data / same concurrency)
+
+- Rerun $\ge 3$ times, take median and slowest; record machine load and data volume.
+- Evidence lands in `tmp/perf/<topic>-baseline.json` (or stdout archive).
+
+## 2. Locate
+
+- Frontend: Performance trace / LCP / long tasks; backend: slow queries, N+1, unbounded fetches (performance three see `.agents/skills/review-method/SKILL.md`).
+- Validate one hypothesis at a time; when a hypothesis is falsified, write down the conclusion then switch.
+
+## 3. Single-variable change
+
+Change one place at a time; do not change criteria, do not swap data, do not adjust the machine. For gate-timing changes distinguish "gate got faster" from "quality improved".
+
+## 4. Retest and accept
+
+- Rerun the same scenario $\ge 3$ times; improvement must exceed the noise band (number credibility single source `.agents/skills/number-vetting/SKILL.md`).
+- Not past the noise band → roll back or record "unproven", do not put it in conclusions.
+
+## 5. Record
+
+Table: baseline / change / retest / conclusion + evidence path. For environment jitter (shared DB locks, machine load), isolate and retest first; attribute per `review-method/golden-set.md` #21 criteria, do not falsely report regression.
+
+## Red lines
+
+- Do not change two variables at once; do not use a single run; do not optimize what was not measured.

package/locales/en/overrides/.agents/skills/review-method/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: review-method
+description: Code review walkthrough method (Standards×Spec dual axis + bad-smell checklist + merge bar). Used by independent-reviewer or the main agent when reviewing a diff; it is the method-layer single source for the .agents/commands/review.md execution flow and does not depend on host global skills.
+---
+
+# review-method — Review walkthrough method
+
+## Positioning and division of labor
+The three review layers each have their own single source; this file only handles "how to walk through":
+
+| Layer | Single source |
+|---|---|
+| What to block (invariants) | `.agents/commands/review.md` P0/P1 table |
+| In what capacity to check (evidence discipline) | `.agents/roles/independent-reviewer.md` Constraints |
+| How to walk through (this file) | dual-axis framework + bad-smell checklist + merge bar |
+
+When the host has global `code-review` / `review-verification-protocol` skills they may be layered on; otherwise this file is the fallback.
+
+## Calibration set (golden-set.md)
+The `golden-set.md` in the same directory is a known-answer sample library for independent review quality (positive = defect should be reported, negative = should pass; each with this repo's context points). Before reviewers/new sessions go on duty they may blind-evaluate samples then compare answers to self-check calibration difference; monthly reconciliation sampling (registered in mechanism-registry) uses it as a comparison baseline, must run **both arms** (A = with this skill loaded / B = clean session given only inline sample context; Δ is the effect of context injection) and run **variance reruns** for suspicious judgments (flippers count as question ambiguity, not calibration difference). When hit difference exceeds 20% for two consecutive months, register calibration debt in papercuts; samples' answers are finalized when the anchor loop closes; later code evolution does not change answers.
+
+## Dual-axis framework (report by axis; merged sorting forbidden)
+| Axis | Question asked | Basis |
+|---|---|---|
+| **Standards** | Does it comply with this repo's written standards | Root/directory-level `AGENTS.md` + review.md P0/P1 table |
+| **Spec** | Does it faithfully implement the entry document's commitments | intent/plan "acceptance criteria" + spec §test cases |
+
+The two axes stand independently: compliant but doing the wrong thing (Standards pass, Spec fail) and doing the right thing but breaking standards (Spec pass, Standards fail) both exist — report separately to prevent one axis masking the other. The Spec axis reports three finding classes: missing/partially landed commitments, scope creep, implementation distortion.
+
+### Pre-dispatch self-check and axis isolation
+- **Baseline self-check first**: before dispatching review (or self-review) `git rev-parse <baseline>` resolves + `git diff <baseline>...HEAD` non-empty — bad refs/empty diff fail before dispatch, not midway through the two-axis walkthrough.
+- **Spec source discovery order**: workflow reference in commit message → path given by user → same-named family of entry document (intent/spec/plan) → if none ask the user; when not found the Spec axis explicitly reports "no spec available", silently skipping the whole axis is forbidden.
+- **Dual-axis dispatchable isolation**: when the host supports subagents, dispatch the two axes to two read-only subagents in parallel (context isolation prevents mutual contamination), and present each axis as-is when aggregating — the cross-axis reordering prohibition is not relaxed.
+
+## Bad-smell walkthrough checklist (Standards axis supplement)
+Judgment items outside the P0/P1 table. Constraints: repo written standards prevail (written acceptance suppresses this checklist); always judgment items, not hard violations; skip what gates/tooling already catch. Each entry = what it is $\rightarrow$ how to fix:
+
+| Bad smell | What it is $\rightarrow$ how to fix |
+|---|---|
+| Mysterious Name | Name does not reveal purpose $\rightarrow$ rename; if you cannot find an honest name = design is murky |
+| Duplicated Code | Same-shaped logic appears in multiple places $\rightarrow$ extract shared implementation, call from both |
+| Feature Envy | Method uses another's data more than its own $\rightarrow$ move the method onto the data it envies |
+| Data Clumps | Several fields/parameters always travel together $\rightarrow$ bundle into one type and pass it |
+| Primitive Obsession | Raw value replaces a domain concept $\rightarrow$ build a dedicated small type for the concept |
+| Repeated Switches | switch/cascading if on the same type recurs $\rightarrow$ polymorphism or shared mapping |
+| Shotgun Surgery | One logic change forces scattered edits across files $\rightarrow$ gather into the same module |
+| Divergent Change | One module changed for multiple unrelated reasons $\rightarrow$ split by single reason to change |
+| Speculative Generality | Adding abstraction/parameters/hooks for requirements not in spec $\rightarrow$ delete and inline, wait for the real requirement |
+| Message Chains | Long `a.b().c().d()` navigation $\rightarrow$ hide one method on the first object |
+| Middle Man | Class/function almost only forwards $\rightarrow$ delete, call the real target directly |
+| Refused Bequest | Subclass ignores/overrides most inherited members $\rightarrow$ drop inheritance for composition |
+
+Performance three (beyond the P1 pagination clause): N+1 queries, unbounded fetches/loops, large objects on hot paths.
+
+### Storage host selection (added 2026-10-23, source incident 2026-10-23-pml-pbs-relation-host)
+
+During the new/old system coexistence period, **host table selection for business relation tables (A↔B many-to-many) must answer "does the old system already have a synonym table"**:
+
+- The old system already has it → **reuse**, and fix that table's column semantics in the spec (which table the FK points to, type-code criteria, which columns are not persisted and need read-time back-inquiry).
+- Truly new → the spec states **why not reuse**.
+- When reusing a shared table, **structure must not change** (no added column/index/constraint); dedup and constraints are handled by the server side.
+
+Review action: for every new table or new mapping in the spec/diff, check the old system source or DB metadata once for an existing synonym table.
+
+**Why a human/review agent must actively check**: `SchemaLedgerDriftTests` only validates "whether declared table structures match the real DB" — correct structure = green, cannot discover "this table should never have been created"; static gates are also blind to "two table sets for the same business relation". On 2026-09-28 "associated PBS single-value to multi-value" thus a private table `MM_PML_ProductionPMLPBS` was created by default, coexisting with the old system's existing table `BOM_PalletPBS_Relation` for a long time, until the 2026-10-23 user instruction changed it back to reuse.
+
+### Whether persisted column semantics are rewritten by display demands (added 2026-10-23, source incident 2026-10-23-pml-quota-substitute-identity-overwrite)
+
+When the requirement says "this field should display as X", first distinguish **display projection** from **storage identity rewrite**:
+
+- **Display projection**: only change the read side/frontend mapping, underlying column semantics unchanged → preferred.
+- **Storage identity rewrite**: writing "what should be displayed" as an override of an existing column → only when that column's semantics should genuinely change, and must answer three questions: after override **where does the original value go** (trace column / restorable?), **can it roll back**, **do all downstream consumers of that column use the same criteria**.
+
+Review action: for every sentence in the spec like "rewrite column X" "column X updated to Y", first ask "what did column X originally represent? **should** this semantics change?" — do not only check "it is self-consistent after the change".
+
+**Why a human/review agent must actively check**: static gates only see structure and compilability, cannot read column semantics; if tests and implementation share the same source, wrong criteria get **frozen into expectations** (this case's 20 cases all asserted the old criteria and were all green before the change), making the wrong criteria itself undiscoverable; once a spec is written as the "source of truth" it also keeps reinforcing itself. In this case spec `2026-10-13-pml-quota-substitute-rewrite` item two implemented "whose identity the quota row displays after substitution" as "rewriting the quota row's material identity (code/name/spec/stock-unit/unit/TAG)", and **passed item-by-item independent review**, until the 2026-10-23 user instruction reversed it.
+
+### Spec half-landing verification (added 2026-11-02, source batch three)
+
+Before reviewing a spec/plan `done` declaration, check each "observable criterion": can each criterion be pointed to code, a test, or an executable script? If not pointable = half-landing; half-landing must not be marked `done`; add tests or downgrade to a registered item and leave a pointer in incident/notes.
+
+**Why a human/review agent must actively check**: static gates can only prove compilation/structure, not that "the promised behavior actually landed"; when implementation and tests share a source, half-landing can still be all green.
+
+## Structured fix actions
+When reporting structural problems give named actions, do not just say "this is complex" and let the author guess: remove condition chains by building a type/dispatcher, fold duplicate branches, separate orchestration from business, move feature logic back to its owning layer, reuse authoritative helpers instead of near-copies, explicit type boundaries to remove downstream branches, delete pass-through wrappers with no clarification value, extract helpers or split large files.
+
+## Merge bar (prevent P2 entanglement)
+When it clearly improves overall code health, recommend merging; do not block because "I wouldn't write it that way" — perfection does not exist, continuous improvement is the goal. Style preferences and hypothetical risks must not be reported (evidence discipline see role contract Constraints).
+
+## Provenance
+- Dual-axis framework and bad-smell checklist: distilled from the host global `code-review` skill (Fowler, Refactoring ch.3 baseline).
+- Structured fix actions and merge bar: borrowed from [addyosmani/agent-skills](https://github.com/addyosmani/agent-skills) (MIT).

package/locales/en/overrides/.agents/skills/session-resume/SKILL.md

@@ -0,0 +1,69 @@
+---
+name: session-resume
+description: Session re-entry and interruption handoff — when taking over, switching worktrees, or continuing after compression/new session, rebuild the current state from machine facts before acting; for use by the main agent before starting work at any level.
+---
+
+# session-resume — Session re-entry and interruption handoff
+
+## Triggers
+
+- New session / continuing an existing task after context compression; taking over someone else's branch or worktree.
+- The user asks "where did we get to / what is still uncommitted".
+- Before acting you find the working tree dirty but cannot tell who owns the changes.
+
+## 1. Rebuild (machine facts first, not memory)
+
+Run in order, all read-only:
+
+| Question | Command | What to read |
+|---|---|---|
+| Where am I | `node .agents/skills/session-resume/scripts/worktree-audit.mjs` (classification + cleanup suggestions, read-only) | main / active / cleanable / stale, all at once |
+| What is unsaved | `git status --porcelain -uall` + `git stash list` | untracked files and stashes (easiest to miss) |
+| What is in flight | active states in `workflow/{plans,specs,intents,incidents}` + the last run in `.agents/cache/pipeline-runs/*.json` | task-list checkbox state, stage progress of orchestration runs |
+| Where was the last green | last row of `.agents/verifications.jsonl` (pinned `headShort` + 24h window) | whether the current HEAD already has green evidence |
+
+> The single source for L2/L3 plan checkbox alignment = "Session re-entry" in the Build chapter of `.agents/commands/stages.md`; this skill does not copy it, only supplements the L1 and cross-worktree cases.
+
+### 1.5 Dream report loading (if present)
+
+If `tmp/dream-report-*.md` or `tmp/dream-judge-brief-*.md` exists (gitignored runtime state; if deleted it can be rebuilt from git + the ledger), load it per `.agents/skills/dream/SKILL.md`:
+
+1. Read the latest report and AI Judge brief;
+2. Delegate independent-reviewer to verify the AI Judge samples;
+3. Write verification conclusions back to papercuts / correction notes (no auto commit / push).
+
+## 2. Align (stop first on mismatch)
+
+- Checked but uncommitted / committed but unchecked / changes of unknown origin in the worktree → confirm ownership before continuing; do not overwrite.
+- Across worktrees: uncommitted changes **do not** follow automatically. Compare the two trees with `git diff | sha1sum` to confirm whether they are the same set of changes, avoiding a double commit.
+- Two branches pointing at the same commit but each with its own changes = two independent worktrees, not sharing.
+
+## 3. Output (4-line brief, conclusion first)
+
+```
+Location: <worktree> @ <branch> (<headShort>), ahead/behind
+Unsaved: <N modified / M deleted / K untracked / stash count>
+Next: <next unchecked item in the active plan, or next stage of the run>
+Blocked: <the single item requiring a user decision; write "none" if none>
+```
+
+## 4. Interruption handoff (pause)
+
+Write `.agents/cache/handoff.md` (gitignored, local runtime state, disposable; git is the truth):
+
+```
+Date / branch / worktree / HEAD
+In-flight task: <workflow file>
+Completed: <checked items>
+Next: <first item>
+Uncommitted: <file list + ownership>
+Blocked: <none / item>
+```
+
+On resume, read it first, then verify per §1; on mismatch, git wins, and write the handoff back.
+
+## Red lines
+
+- Do not continue from memory; do not overwrite uncommitted changes of unknown origin.
+- Do not auto commit / push WIP; saving to disk is not committing and requires an explicit user request.
+- Do not treat `.agents/cache/` as authoritative: after deletion it must be rebuildable from git + the ledger.

package/locales/en/overrides/.agents/skills/shipyard-workflow-closeout/SKILL.md

@@ -0,0 +1,109 @@
+---
+name: shipyard-workflow-closeout
+description: Shipyard.Material close-out sequence — verify --scope, acceptance checklist, closeout.mjs writing terminal state/index/commit, machine gates and failure recovery. Used to bring workflow documents to done/closed.
+---
+
+# Shipyard.Material close-out confirmation gate operation sequence
+
+## Goal
+Bring approved workflow documents to terminal state and leave auditable verification evidence, confirmation shards, and an index.
+
+## Trigger conditions
+- `workflow/{intents,specs,plans,incidents}` documents are to enter `done` or `closed`.
+
+## Prerequisites
+`approved` (incident `fixed`) is already in the current branch's git history. If still `draft` or `open`, first `confirm-doc` to `approved` / `fixed` and commit separately, then run the close-out below.
+
+**L1 single-commit exception (from 2026-11-08 batch 2-D, `new-task.md` fast lane step 6)**: after L1's two consecutive approved→done hops, plan(done) + code + confirmation shard + verify evidence **go into the repository in the same commit** — approved need not be committed separately first, and this skill and closeout.mjs are **not used** (its candidate path list does not include product code, and the foreign-path guard rejects it); commit directly with git. Two hops for the same document may use the same release utterance; reuse across documents is forbidden. This skill remains only for "plan independent close-out" (code already committed in a previous commit) and L2/L3 / incident scenarios.
+
+The status line is changed only by `confirm-doc.mjs`. Proxy recording uses the user's original utterance in the conversation. Commits do not use `--no-verify`. Self-done L1 does not write result lines into `workflow/delegations.md`; delegated tasks and self-done L2/L3 still leave traces per `stages.md` Test §5. **Way out when the commitment surface is rewritten**: `confirm-doc.mjs <doc> --reconfirm --delegated "<user's original utterance>"` — re-records the fingerprint and commitment-surface fingerprint, status remains approved (the status line is still written by the script, do not hand-edit frontmatter).
+
+## Execution sequence
+
+### 0. Close-out self-check (former check-loop §1/§3x hard responsibilities pushed down, 2026-10-21 gate minimization batch 2)
+Check four items against the document family to close; if any is missing → fill it first before closing, never write done with gaps. Items 1 (L2/L3), 2, 3 (L2/L3 intent) have been moved earlier to machine enforcement at the `confirm-doc.mjs` close-out action (2026-11-08 closeout-skill-hardening) — humans only fill legacy stock and out-of-specialty cases; when the script rejects, fill per the error:
+
+1. **Pairing self-check**: sibling documents of the same family present — L2/L3 intent must have same-named spec and plan (confirm-doc's `specConfirmed` / `planConfirmedFor` hard gates); intent (including legacy L1) must have a same-named plan; incident must have a same-named plan (L2/L3 additionally must have a same-named spec). L1 pairing remains a self-check: 2026-10-21 gate minimization downgraded the pairing hard gate to WARN, not re-hardened here.
+2. **incident trio** (when closing an incident): `## 复盘三件套` section contains `1. 结构性修复 / 2. 防复发验证 / 3. 规范条目` all three + "whether a new intent is needed" line; if "yes" → the referenced intent path exists. Criterion single source `stage-gates.mjs / incidentTrioGate`, hard-blocked by confirm-doc for →fixed/→closed; legacy documents before the 2026-11-09 first-anchor addition and documents declaring `流程: legacy` / `存量确认态豁免（` remain manual self-check (same criteria).
+3. **L2/L3 review context required**: persisted line format `- 独立复核：…（复核上下文：<session/subagent id>）`, starting with `- 独立复核：` and containing "复核上下文："; L2/L3 intent→done hard-blocked by confirm-doc's `reviewLineFor`, spec/plan and L1 remain self-check. If missing → **HALT**: go back to `.agents/commands/stages.md` Test §4 to add the independent review, persist that line, then close.
+4. **Commitment surface not rewritten (new 2026-10-27)**: if the **commitment surface** (criteria text / red lines / goal / change plan) was changed after approval, the user must **nod again** before close-out — run `node .agents/scripts/confirm-doc.mjs <doc> --reconfirm --delegated "<user's original utterance>"` to re-record the commitment-surface fingerprint (does not advance status). **Checking acceptance + evidence backfill / `确认结果` / review-line anchor changes do not count as commitment changes** (normalized; normal close-out unaffected).
+
+Completion criteria: four items pass; machine gates per confirm-doc rejection messages, human self-check items verified one by one.
+
+### 1. Verification
+Run `node .agents/scripts/verify.mjs --scope`. If just run in fast lane step 5 it can be reused; criteria no longer rely on memory: when the all-green line is persisted record `dirty` (snapshot of dirty paths under `backend/` `frontend/` at that time); at close-out confirm-doc compares current business dirty paths — business changes appearing after verify are judged stale evidence (24h window as before). Legacy green lines (without a dirty field) keep the original criteria.
+
+Completion criteria: one exit code 0, and not judged "evidence stale" at close-out (if judged, rerun verify to refresh the snapshot). When scope judgment needs full coverage the script falls back itself; do not hand-edit `workflow/verify-evidence.md`. Ordering: the verify green line must be produced **before** the done transition (the dirty snapshot records current business dirty paths; code from the same-batch L1 single commit is already in the working tree at verify time, a path the green line has seen, so it is not judged stale).
+
+Scope reconciliation (advisory, 2026-11-11 dev-tour wiring): run `node .agents/scripts/gen-dev-tour.mjs workflow/plans/<name>.md --scope-report` — when "actual changes outside the document" is non-empty, explain or backfill the plan before closing (same criteria as dev-tour trigger conditions; complements the `check-scope.mjs` out-of-scope hard gate, here only prompts and never blocks, always exit 0).
+
+### 2. Check acceptance
+In the document check each acceptance item and write evidence, fixed format: `- [x] acceptance item` with "证据：<command output / path / verification record>" on the same line or immediately following continuation line. Criterion single source `stage-gates.mjs / acceptanceEvidenceGate` (close-out format gate): unchecked items, checked items missing the "证据：" annotation, and L2/L3 specs without a "验收判据" data row are all rejected at confirm-doc. L1 checks the plan. L2/L3 new requirements check the intent. Fixes check the incident, path is `open` → `fixed` → `closed`.
+
+Completion criteria: every acceptance item points to evidence (command output, path, or verification record); for the L1 single commit, checking and evidence backfill must be completed **before commit** (checks go into the same commit's plan(done) blob).
+
+**Check semantics (criteria declaration, 2026-11-10)**: document checks fall into three classes; done is unrelated to total check count — ① task-breakdown checks = process trace / session re-entry anchor (e.g., `stages.md` §1 shortcut check reads check state to align progress); not all checked ≠ not complete, not a reason to withhold close-out; ② entry red-line questionnaires are negative declarations; L1 all unchecked is the correct "not touched" state; ③ the only check criterion for done = acceptance criteria section each `[x]` cleared + evidence line (this section's acceptanceEvidenceGate). Fabricating backfilled checks for "tidiness" is forbidden.
+
+### 3. Proxy-record terminal state
+First choice is one call `node .agents/scripts/closeout.mjs <doc> --delegated "<user's original utterance>"` (chains §3–§5; usage and failure recovery see §5.1); the three steps below are the manual equivalent path.
+
+Manual proxy record: `node .agents/scripts/confirm-doc.mjs <doc> --delegated "<user's original utterance>"`.
+
+Incident from `fixed` to `closed` run once more. When spec is marked `done`, step 1's all-green evidence already exists.
+
+Completion criteria: target document status is `done` or `closed`, body remains unchanged after this proxy record.
+
+### 4. Index
+Run `node .agents/scripts/gen-workflow-index.mjs`.
+
+Completion criteria: `workflow/INDEX.md` regenerated from disk.
+
+### 5. Commit
+`git add` these paths: `.agents/confirmations.d/<document basename>.jsonl`, `workflow/INDEX.md`, `workflow/verify-evidence.md`, and the closed documents. Add `.agents/confirmations.jsonl` only if this diff touched it.
+
+Before commit inspect that shard's `git diff`, keep only this session's confirmation lines. `closeout.mjs` has automatically added per this list and checks that the staging area contains only candidate paths (any other in-flight change = reject); commits do not use `--no-verify`.
+
+Commit message: `docs(workflow): <batch> close-out`.
+
+Completion criteria: above paths committed, hooks pass.
+
+### 5.1 Single call and failure recovery (re-entry)
+
+`node .agents/scripts/closeout.mjs <doc> --delegated "<user's original utterance>" [--msg "<commit subject>"] [--dry-run]`
+
+Chain order: confirm-doc writes terminal state → gen-workflow-index regenerates → git add fixed path list → git commit. Incident's two hops run once each (`fixed` and `closed`). `--dry-run` reports only current status / next hop / candidate path changes; no state, no write, no commit.
+
+On any step failure stop, fix the cause then **rerun the same command** (idempotent: terminal state skips proxy record, index generation idempotent, no staged changes skips commit):
+
+- confirm-doc rejects: that document not recorded, not written; fill per the error (pairing / trio / review line / acceptance evidence / delegation ledger) then rerun.
+- Evidence stale: rerun `verify.mjs --scope` to refresh the dirty snapshot then rerun.
+- Commitment-surface fingerprint mismatch: first `confirm-doc.mjs <doc> --reconfirm --delegated "<user's original utterance>"` to re-nod, then close out.
+- Staging area contains foreign paths: the script rejects the commit and lists them; commit or revert these paths separately then rerun (proxy record and index already done; rerun only commits).
+- Hook rejects the commit: fix the hook cause then rerun, do not use `--no-verify`.
+
+> L1 single commit does not use this entry (see "Prerequisites" exception) — that path has only one git commit and no separate close-out commit.
+
+### 6. Backfill feature docs
+
+Write this behavior change into the corresponding living doc, and leave a pointer in plan / incident; keep only one doc per feature:
+
+| Change type | Backfill target |
+|---|---|
+| User-visible interaction / path | `.agents/skills/verify-ui/features/<feature>.md` |
+| Contract / rule / data criteria | Amend the original spec in place (`workflow/README.md` spec lifecycle) |
+| Anti-recurrence assertion | Corresponding module section of `workflow/regression-checklist.md` |
+| Architecture / approach | `wiki/开发方案/` |
+
+Append only change facts and evidence pointers, do not copy the whole doc; backfill goes with the close-out commit. If no corresponding doc exists, create one with the feature key in the topic.
+
+### 7. Recipe recovery (long tasks / detours, not incidents)
+
+Criteria (any): the same action repeated $\ge 2$ times in this session; the same spot reworked $\ge 2$ times; $\ge 2$ rounds probing to locate an entry or environment.
+
+Action: write the recipe back to one authoritative file — prefer editing existing command / skill / role text, do not create a new skill. Placement level per `.agents/skills/papercut-fix/SKILL.md` §0 ladder; this loop usually lands at level 5 (text).
+
+Wording: one trigger condition + one action step + one identifiable verification; cite this session's blocker, generic advice forbidden.
+
+Do not: one-off environment failures (go to `.agents/notes/runtime-env.local.md` or papercuts `[env]`); incidents follow `.agents/commands/maintain.md` trio.
+
+Commit: `docs(engine)` separate commit, no business code.

package/locales/en/overrides/.agents/skills/show-me-your-work/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: show-me-your-work
+description: Decision trail for long/unattended runs — append-only TSV, one row per decision (what/why/evidence/result), evidence is pointers not paragraphs; use for overnight, multi-stage, or post-departure review.
+---
+
+# show-me-your-work — Decision trail
+
+## Triggers
+
+- Unattended / overnight / multi-stage long runs (`autonomous-run`, `pipeline-run`).
+- The user says "I'm leaving / I'll trust it when I'm back / show me when it's done".
+- Changes span multiple units and afterwards need a reviewable decision chain.
+
+## Format
+
+A single TSV, one row per decision. Keep cells single-line; evidence is a pointer, not a paragraph.
+
+```
+ts	phase	decision	why	evidence	result
+```
+
+- **ts**: ISO8601.
+- **phase**: phase or workflow.
+- **decision**: what was chosen/done, one line.
+- **why**: the reason, in plain language; if it is principle-driven, say so plainly, do not pile on jargon.
+- **evidence**: a provable pointer—commit SHA, PR number, `file:line`, artifact/trace/screenshot path. Paragraphs forbidden.
+- **result**: the outcome or predicate state—`tests green` / `reverted` / `pixel-diff 0` / `INCONCLUSIVE` / `open`.
+
+Template: `.agents/skills/show-me-your-work/references/decision-log-template.tsv`.
+
+## Recording rules
+
+- **append-only**: do not delete bad rows; append a supersede row; never edit/delete history.
+- Record only decision points and checkpoints: which fork was chosen, unit completion and its verification result, pivot/revert and its trigger, exposed blockers, gates fixed. Do not record trivial actions.
+- Loop runs: one row per round.
+- One run = one agent session (including follow-up rounds). Takeover / switching sessions / a new chat = a new run; the first row's phase of a new run is `start`, and name this run in evidence (e.g., agent id).
+- Prefer evidence produced by **committed scripts** over hand-rolled one-off commands ("raise the ladder before writing prose").
+
+## Storage
+
+- By default this is a work product, not committed: `decisions.tsv` or `.audit/<task-slug>.tsv`, kept outside git.
+- Commit only when "the reviewer needs this trail to trust the result" (large changes / unattended / spanning multiple PRs).
+
+## Wrap-up audit
+
+Before handing back, reconcile against this run's transcript: does each row correspond to a real decision/action; can the evidence be resolved and does it prove that row; forks/pivots that affected work but were not recorded are gaps—add them. The audit does not change the story—supersede bad rows with a new row.
+
+## Cross-model review
+
+Before handing back, have a subagent on a **different model tier** read the trail + transcript and flag what the user should notice: weak/missing evidence, verification skipped or only verbal, decisions that look risky in hindsight, gaps a casual scan would miss. End the reply with an `Attention` section whose first line is `reviewed by <model>`; `No flags` is a legal value.
+
+## Where it lives in this repo
+
+- `autonomous-run`: add a "decision trail" clause when establishing the contract.
+- `pipeline-run`: record one row per work-order sign-off.
+- `workflow/delegations.md`: delegation results still go in the ledger; this TSV is the per-run decision chain and does not replace the ledger.
+- Append a row: `node .agents/skills/show-me-your-work/scripts/decision-log.mjs <logfile> <phase> <decision> <why> <evidence> <result>` (auto ts, header on first use, sanitize tabs/newlines, escape a leading `=+-@`).

package/locales/en/overrides/.agents/skills/tfs-pr/SKILL.md

@@ -0,0 +1,95 @@
+---
+name: tfs-pr
+description: Internal self-hosted TFS / Azure DevOps Server PR skill, project-agnostic — auto-detects the git repository and remote to derive collection/project/repo, guides creation and saves an env var when PAT is missing; query PR / create PR (context pulls diff to distill title and description) / update PR description / conflict pre-check and worktree-isolated resolution, via REST API + PAT (the az devops extension rejects http organization URLs, so az is unavailable). Command entry .agents/skills/tfs-pr/scripts/tfs-pr.mjs.
+---
+
+# tfs-pr — Internal TFS / Azure DevOps Server PR (project-agnostic)
+
+Zero project assumptions: if the remote is in TFS / Azure DevOps form (path contains `_git`), or a collection URL can be provided, it is usable. The skill directory is self-contained. Host side holds only pointer shells (this repo only `.codebuddy`; the `.trae` shell was removed 2026-11-08); main-copy changes carry no synchronization obligation. Below, `tfs-pr` refers to `node .agents/skills/tfs-pr/scripts/tfs-pr.mjs`.
+
+## Trigger / do not trigger
+- Trigger: internal TFS transactions such as "check PR / any conflicts", "add / update PR description", "resolve PR conflicts"; `az devops login` reporting "Refusing to attach credentials to an invalid Azure DevOps organization URL" → switch to this skill, do not retry az.
+- Trigger (PR creation class): when the host has a unique PR entry convention (e.g., Shipyard.Material's `pr-create.mjs`), "create PR / push and create PR" **does not directly trigger this skill** — PR creation only goes through the host's unique entry `node .agents/scripts/pr-create.mjs` (which internally calls `tfs-pr create`); agents are forbidden to bypass the host entry and call `tfs-pr create` directly. Hosts without this convention may keep direct triggering. (This repo's former review pre-step was retired to a manual tool on 2026-11-09: panel review runs manually on demand, see `.agents/commands/pr-review.md`.)
+- Do not trigger: GitHub / GitLab and other public hosted PRs; ordinary code review, commit messages.
+
+## 0. Prerequisite probing
+```bash
+git rev-parse --is-inside-work-tree   # non-zero → not a git repository, stop and inform
+tfs-pr target                          # base/project/repo/tokenUrl/prPage, zero requests, no PAT needed
+```
+- `target` errors carry remediation: ask the user for a collection URL (form `http://<host>:<port>/tfs/<collection>`), place per `--base` (single run) / `TFS_BASE` (env var) / `git config tfs-pr.base` (repo level); override project / repo with `--project` / `--repo`; non-origin remotes use `--remote` / `TFS_REMOTE`.
+- Recognized remote forms: `ssh://host:22/tfs/COLL/PROJ/_git/R`, `git@host:tfs/...` (scp style), `https://host/tfs/COLL/PROJ/_git/R`, root mount (no /tfs), short form (project==collection), `dev.azure.com` / `*.visualstudio.com`.
+- ssh remote web base defaults to `http://<host>:8080`, overridden by `TFS_WEB_SCHEME` / `TFS_WEB_PORT`; old TFS set `TFS_API_VERSION=4.1` (default 6.0); target branch can be fixed with `git config tfs-pr.target <branch>`.
+
+## 1. PAT: read → guide → use
+Store only in environment variables (never in argv / conversation / prints): single server uses global `TFS_PAT`; multiple servers store per base hostname `TFS_PAT_<HOST>` (non-alphanumerics become `_` uppercase, e.g., `TFS_PAT_10_0_0_1`, matched preferentially).
+- Probe and guide in one command: `tfs-pr setup` — prints process/user-level status of the two variables, dynamic portal `<base>/_usersSettings/tokens` (hardcoding site IP forbidden), setx command, whoami self-check. Not configured → give the user the three steps printed by setup: portal generation (scopes check Code Read&Write + Pull Request Read&Write + **Work Items Read** — required for verifying linked work items after creation; without this scope the verification step gets 401) → `setx <variable> "<PAT>"` (effective in a new terminal) → `tfs-pr whoami` real verification (non-empty length ≠ valid PAT).
+- After setx the current process does not inherit: read from registry and feed the script, the value must not appear on the command line: `TFS_PAT="$(powershell -NoProfile -Command "[Environment]::GetEnvironmentVariable('TFS_PAT','User')")" tfs-pr …` (same for split variables).
+- Fallback `--pat-file` only when the user explicitly does not use env vars; clean up with `rm -f`; if PAT leaks into conversation/logs/history → at wrap-up must remind to revoke and recreate in the portal.
+
+## 2. Commands
+| Action | Command | Description |
+|---|---|---|
+| Identify target | `tfs-pr target` | base/project/repo/tokenUrl/prPage |
+| PAT guidance | `tfs-pr setup` | portal address + persistence + self-check commands |
+| Verify PAT | `tfs-pr whoami` | current identity + base/project/repo + PR page |
+| List PRs | `tfs-pr list [--source <b>] [--target <b>] [--status active\|all] [--json]` | `#12 [active/succeeded] feat/x → develop <title>` |
+| Get one | `tfs-pr get <id> [--json]` | status/mergeStatus + PR page URL; JSON contains the full description |
+| Pre-create context | `tfs-pr context [--source <b>] [--target <b>] [--no-fetch] [--patch] [--json]` | commits/files/stat/overlap/conflicts/push/dirty in one shot |
+| Create PR | `tfs-pr create [--source <b>] [--target <b>] --title <t> --body-file <f\|-> [--dry-run] [--json]` | `CREATED #id …` or idempotent `EXISTING #id` |
+| Update description | `tfs-pr desc <id> --body-file <f\|-> [--dry-run] [--json]` | `UPDATED #id …` (already read back and compared) |
+| Conflict pre-check | `tfs-pr conflicts <id> [--no-fetch] [--json]` | fetch conflicts/overlap/mergeBase by PR branch |
+| Local conflict pre-check | `tfs-pr conflicts --source <b> --target <b> [--no-fetch] [--json]` | no PAT, no PR id needed |
+
+- source defaults to current branch (detached HEAD requires `--source`); target defaults to `--target` / `TFS_TARGET` / `git config tfs-pr.target` / remote HEAD; branch names need no `refs/heads/` prefix.
+- `--body-file -` reads body from stdin, no temp file; body UTF-8 (BOM auto-stripped), Chinese and line breaks as-is.
+- `--dry-run` zero requests and no PAT needed; exit code 0 success (including EXISTING) / 1 HTTP·API·network error / 2 usage·configuration error.
+
+## 3. Create PR: distill title and description from the diff
+1. `tfs-pr context --target <target branch> --json` (auto-fetch by default; `--no-fetch` only offline or fresh refs). Output: commits, files, stat/shortstat, overlap (both sides changed), conflicts (merge-tree; `conflictsSupported=false` means git does not support pre-check, do not treat as no conflict), push (unpushed/no remote branch), dirty (uncommitted changes).
+2. Pre-create checks: `push.unpushed` or no remote branch → normal `git push` first (if blocked by gates fix the root cause; `--no-verify` / force push forbidden); `dirty` → confirm whether uncommitted changes enter the PR, do not silently ignore; `conflicts.files` non-empty → resolve per §5 first; `overlap` non-empty but no textual conflict → manually review both changes for semantic confirmation.
+3. To see specific changes, read key files or `git diff origin/<target branch>...HEAD` (`--patch` may attach the full diff).
+4. **Title**: Conventional Commits Chinese `feat(scope): summary` (compound topics joined with `+`, about 70 characters, empty title / PR number forbidden); scope takes the main module/directory, the subject is distilled from the diff's main changes + commits, not a restatement of commit messages.
+   - **`#number` prohibition (empirically 2026-10-26)**: in commit messages / PR titles / PR descriptions, **references to PR numbers must always be written "PR 720", never `#720`** — `#N` is work-item linking syntax; pushing automatically links work item N to the commit and PR; PR numbers and work item IDs share the same numeric space, so unrelated work items will definitely collide (PR #719 was once wrongly linked this way). `#N` is used only when genuinely linking a work item. **In PR descriptions, reference other PRs with markdown links** (`[PR 720](<prPage>/<id>)`, `prPage` see `target` output, single-page URL is `pullrequest/<id>`); linking at the first occurrence of a PR number suffices, the rest plain text.
+5. **Description** (`create` / `desc` both replace the whole segment, must give the complete body; the template is a **default value** — when the host repo already has its own PR body convention, the host convention prevails; check the host's review/merge docs, this template is only a fallback):
+   ```markdown
+   ## Summary
+   - Why the change, what changed (1-4 items, pointing at key modules/files; must come from the actual diff)
+
+   ## Evidence
+   - Tests/builds/manual verification actually run; if not run, explicitly write "not run" and the reason, fabrication forbidden
+
+   ## Merge Danger
+   - Door: impact surface (API / DB / config / permissions / compatibility); write "none" if no risk, omission forbidden
+   - Blast Radius: local / module / global
+   - Rollback: rollback method and risk
+   ```
+   Large diff, non-empty overlap, or irreversible change → append `## Tradeoffs`: cite the real shortstat scale + why this is still done.
+6. `--dry-run` first to verify URL and body, then create officially; `mergeStatus=queued` poll with `get`, `conflicts` go to §5; return the PR page URL to the user.
+
+## 4. Update PR description
+`get <id> --json` read existing → decide replace or supplement (supplement = merge new content into existing, keep useful three sections) → `desc <id> --body-file -` (stdin) or file. **desc replaces the whole segment, it is not an append**; incremental fragments overwriting the original are forbidden. If the source branch has new commits → rerun context before updating the description, to prevent Summary drifting from the actual diff.
+
+## 5. Resolve PR conflicts
+Locate: `tfs-pr conflicts <id> --json` (take branch from PR → fetch → merge-tree + overlap + mergeBase). Server-side conflicts but empty locally → refs stale/server not refreshed, fetch again then `get` confirm, **directly asserting no conflict is forbidden**.
+
+Resolve (worktree isolation; do not touch the user's current working area; do not stash/reset the user's uncommitted changes):
+```bash
+git fetch <remote> <src> <tgt>
+git worktree add <tmp>/pr-<id> -b tfs-pr/<id>-resolve refs/remotes/<remote>/<src>
+cd <tmp>/pr-<id> && git merge refs/remotes/<remote>/<tgt>
+# resolve file by file, preserve both intents; blind --ours/--theirs forbidden; even auto-merged overlaps must pass semantic review (callers/config/migrations/contracts)
+# run project tests/build; stage only resolved files; commit message states which conflicts were resolved — PR numbers must not be written #N (same §3 step 4 prohibition: #N wrongly links unrelated work items, write "PR 720")
+git push <remote> HEAD:<src>
+```
+- No force push (including `--force-with-lease`, unless the user explicitly confirms); a blocked push = gate enforcement, fix the root cause, `--no-verify` forbidden; if branch policy forbids direct push → stop and report options, do not bypass.
+- fork source branch local fetch failure → ask the user for the source repo or resolve in the source repo, do not guess; PR already completed/abandoned → do not resolve conflicts, report status.
+- Wrap-up delete only worktrees/branches created by this skill: `git worktree remove <tmp>/pr-<id> && git branch -D tfs-pr/<id>-resolve`, touch no user branch/worktree.
+- Recheck: `get <id>` → mergeStatus leaves conflicts (poll queued until converged) before considering complete.
+
+## 6. Error interpretation
+- **Three response judgments** (built into the script; manual troubleshooting in the same order): first judge `status` → then judge `content-type` (`401 + text/html` = missing/wrong credentials, common `TF400813`; direct `JSON.parse` only yields misleading `Unexpected token '<'`, hard parse forbidden) → confirm JSON then parse.
+- `401 JSON` = PAT invalid/expired/insufficient scope (rebuild in portal); `404 JSON` = base points to wrong site/port (e.g., API on 8080 but base points to 80) or project/repo misspelled (check `target`); `EXISTING` = an active PR already exists from the same source→target (switch to `desc` or abandon first); network/TLS errors check VPN/proxy/certificate (`--verbose` prints only URLs, not PAT).
+
+## 7. Wrap-up criteria
+After query/create/update, status/mergeStatus match expectations (desc already read back and compared); **linked work items verified** (`curl -s -u ":$TFS_PAT" "<base>/<project>/_apis/git/repositories/<repo>/pullrequests/<id>/workitems?api-version=6.0"` lists them, verify each against expected work items — this repo defaults to no work-item link, non-empty must be explained; wrong links must be removed in the portal and rechecked as empty; when the PAT lacks the Work Items Read scope this step returns 401 and requires manual portal verification); PR page URL returned to the user; after conflict resolution push succeeds and conflicts no longer appear; temporary body/credential files deleted; PAT not in repository/logs/conversation, leaks reminded to revoke; report PR number, URL, status/mergeStatus, and verification actually performed; if tests were not run, say so explicitly.