agentic-flow-kit 1.8.7 → 2.1.0

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.

package/locales/en/overrides/.agents/skills/verify-ui/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: verify-ui
+description: UI change verification (read-only verification, no dirty data left). First choice chrome-devtools MCP — take_snapshot to explore shape + single-step drive + screenshot evidence; harness .mjs scripts are only a fallback path for regression/unattended runs, and any fallback must record one line of reason in the verification report.
+---
+
+# verify-ui — UI verification guide
+
+## Division of labor
+- This file carries only the method (environment / selection points / evidence / cleanup); the execution contract (environment safety / no self-repair / HALT etiquette / deliverable shape) is single-sourced in `.agents/roles/ui-verifier.md`.
+- Delegated subagents follow the contract; the main agent verifying itself follows this file.
+
+## Trigger conditions
+- User requests: `verify` / `UI verification` / `browser verification`.
+
+## Tool path priority
+- Interactive UI verification defaults to chrome-devtools MCP: the browser instance is reused throughout; first `take_snapshot` to explore shape, then drive single-step, retry locally.
+- harness scripts are used only for: regression / anti-recurrence assets; batch assertion summary + exit-code gates (`makeRecorder`); unattended / pipeline batches.
+- Degradation ladder (established 2026-11-04, revised 2026-11-11): chrome-devtools MCP is the first choice; harness probes are only a fallback path. **Host has no chrome-devtools tools (MCP not installed / not connected)**: when attended, HALT and prompt the user to install / enable chrome-devtools MCP, do not auto-degrade (probes are too slow); only unattended / overnight batches degrade directly to harness headless probes. **MCP installed but not working** (browser cannot start and still fails after handling per runtime-env §6.4 / critical steps blocked by MCP errors): degrade to harness headless probes. Every degradation must record one line of "degradation reason" in the verification report — a probe verification without a degradation reason = path violation, the report is not accepted.
+- Script technical details single source = `scripts/verify/e2e/harness.mjs` (export list: `grep '^export' scripts/verify/e2e/harness.mjs`); when writing scripts import its exports, do not hand-write equivalent logic.
+
+### Capability mapping (harness ↔ MCP)
+
+| Goal | MCP | harness |
+|---|---|---|
+| Session seeding | API fetch token → `evaluate_script` write `auth_token` / `auth_user` → `navigate_page reload` | `getToken` + `seedSession` |
+| Navigation / waiting | `navigate_page` + `wait_for` | `goto` / `hardGoto` / `reload` |
+| Shape exploration | `take_snapshot` (a11y tree + uid) | `inventory` / one-off probe |
+| Driving | `click` / `fill` / `press_key` | `clickText` / `setInput` / `pressKey` |
+| Network capture | `list_network_requests` | `installNetCapture` + `apiCalls` |
+| Console capture | `list_console_messages` | `installConsoleCapture` + `consoleErrors` |
+| Metrics / screenshots | `evaluate_script` / `take_screenshot` | `ctx.evaluate` / `ctx.screenshot` |
+
+### Session and capture rules (same criteria for both paths)
+- Reach the FE origin before injection; same-document hash switches do not reload the document, after seeding a full-page reload is required.
+- Default identity = JWT claims of the seeded token; only when testing "an identity different from the token" manually seed `auth_user` (take the login response's `jobNo` / `displayName` / `dept`).
+- Synthetic JWT only applies to pages calling zero-authorization APIs: `exp = Math.floor(Date.now()/1000) + 1800`, never write far-future; after injection go through about:blank and then hard-navigate.
+- If the page issues token-bearing APIs and 401 clears the session back to `/login`: for real data dependencies use account-pool login (account pool single source `.agents/notes/runtime-env.md` §6.1a).
+- Exclude OPTIONS preflight from request counts; assertion counts use API responses, do not count DOM (virtual scrolling / virtual columns render only the visible window).
+- Before asserting "zero console errors", filter the application's own noise (AG Grid license banner, Network Error from API not started); filter by content features, do not use `^` line-start anchors.
+
+### MCP session differences
+- MCP uses a persistent profile (localStorage retained across rounds): clear localStorage before seeding, or pass `isolatedContext` to `new_page`.
+- On "The browser is already running for …chrome-profile" → kill residual processes whose command line contains `chrome-devtools-mcp` (handling recorded in runtime-env §6.4).
+- `take_screenshot`'s `filePath` is limited by the MCP workspace whitelist (some hosts reject both repo paths and session directories, empirically 2026-10-31): when writing is rejected do not retry paths repeatedly, switch to **inline screenshot without `filePath`** for archiving; evidence validity is based on the `.md` report's DOM/API assertions (spec acceptance criteria never recognize image paths anyway).
+- `upload_file` triggering `input[type=file]` may likewise be fully rejected by the whitelist for repo/session paths (empirically 2026-11-07): do not try paths, inject in-page instead — a temporary read-only HTTP server (e.g., `npx serve` on a random port) serves the fixture, `evaluate_script` fetches it into a File, puts it into `DataTransfer`, then `dispatchEvent(new Event('change', {bubbles:true}))` to the antd upload input; before injection record `modalCount` as 1 to prevent stale modal DOM misalignment (MTO modal residual after close previously caused PML injection misalignment; reload clears residue). Verify: the uploaded item tag/preview API receives file rows matching the fixture row count.
+
+## Workflow
+
+### 1. Environment preparation
+- Start API / frontend per `.agents/notes/runtime-env.md`; record all started processes.
+- Multiple worktrees in parallel: set `SHIPYARD_SLOT` so the three port groups API / frontend / CDP shift together (port literal single source `scripts/verify/e2e/ports.mjs`, port table in runtime-env §6.1b).
+- Only harness / fallback paths start their own browser: newer Chromium kernel headless (e.g., Edge `--headless=new`); on the MCP path the browser instance is managed by MCP, do not start another manually.
+- Start long-lived services as separate processes (e.g., PowerShell `Start-Process`); no pipe at the end of the start command.
+
+### 2. Execute verification
+- Select points from the feature map (`features/`); run at least one normal path and one failure/boundary path each (validation / empty state / permissions).
+- Navigation: hash mode uses `goto`; deep links (Query changes) use `hardGoto` (about:blank relay).
+- Data-condition assertions for paginated tables inside modals: click `.ant-pagination-item` page by page, scan all, then merge assertions; do not look only at the first screen.
+- For layout assertions first probe the real DOM (snapshot / probe reading `outerHTML` + `getComputedStyle`); do not infer expected values from CSS source; when unsure use invariants decoupled from spec numbers, downgrade spec reconciliation to a NOTE.
+- Evidence capture: screenshots, network payloads, console logs; record paths in the task document's "Acceptance criteria" item afterwards.
+
+### 3. Cleanup and wrap-up
+- Delete temporary data precisely by the ID returned in the POST response; fuzzy-match deletion forbidden.
+- Close all processes started by this flow.
+- Report by `page / step / expected vs actual / evidence`; append "feature map coverage M/N" (M = features covered this time, N = total `features/` entries) on the last line, listing uncovered items one by one.
+- Record defects only; do not directly fix code.
+- Write the UI verification report to `workflow/evidence/<YYYY-MM-DD>-<topic>.md`: header records environment / reproduction commands, assertion table each row carries a "corresponding acceptance An" column (shape reference `workflow/evidence/2026-10-24-purchase-contract-template-print-ui.md`). A report left in the session or `tmp/` = verification not closed out.
+
+## Feature map (features/)
+- `features/` holds one file per core feature; four sections, none may be missing when creating: reach path / drive / observable end state / Gotchas.
+- Verification and close-out spot checks take coverage from the map; current coverage follows the `features/` directory.
+- Create files synchronously when a new page or new main chain goes live; source waves from `frontend/src/router/index.ts` routes: route exists, map missing = to add; map exists, route missing = to delete or rewrite.
+- Coverage gaps / skeleton: `node .agents/skills/verify-ui/scripts/gen-verify-feature.mjs --check` (or `--json`) lists uncovered routes; `--route <path>` writes only the four H2 sections + TODO skeleton, inventing drive steps forbidden.
+- Monthly drift maintenance: ① take routes / component diffs of the recent month as source waves; ② run verification once only for touched features; ③ fix in at most one commit.
+- For each failure first decide "map drift" or "code defect": the former fixes the map, the latter enters an incident; mixing them is forbidden.
+- Missing prerequisites → record as a failure and write the reason into that feature's Gotchas; weakening the verification path to pass is forbidden.
+- If a page / behavior does not match the map → fix the map first, then conclude.
+- Run `check-regression-consistency.mjs` before close-out: `#/route` / `frontend/src/*` / `workflow/*.md` / `scripts/verify/*.mjs` referenced by the map dangling = red; dangling code symbols are only advisory.
+
+## Technical requirements and constraints
+
+### Shell and processes
+- Protocol prefers HTTP, avoid self-signed certificate interception.
+- "Partial changes take effect" → restart the dev server; single file not taking effect while others are normal → first touch that file.
+- Probes must hit this worktree's dev server: if the vite port is occupied it silently shifts — after starting the service confirm the actual port and run with `E2E_FE_URL=http://localhost:<actual port>`; login-page navigation uses the same `FE` (localStorage is isolated by origin).
+- Truncate output with `| tail -N`, never `| head -N` (SIGPIPE terminates the process before finally, leaving a residual browser occupying the CDP port).
+- Reset the Console / Log collector before every navigation; install the toast observer before navigation actions.
+- The three-piece verification script set is mandatory: `installNetCapture(ctx)`, `seedSession(token, { reload: true })`, `hardGoto(url)`.
+- Wrap the probe body in `try { … } finally { await ctx.close?.() }`; before script start, kill residual processes by `--remote-debugging-port=<port>` for self-healing.
+- Before using `harness.dbQuery`, confirm the database-explorer skill is available on this machine; prefer criteria that can be established without DB connection.
+
+### Assertion summary
+- Wrap the assertion body in try/catch: in catch append a failed assertion (with error message) and count it in the summary, with exit code 1 accordingly; "run halfway + print GREEN + exit code 0" is forbidden.
+
+### DOM location and interaction
+- Form location inside overlays / drawers / modals must always be scoped to the overlay root (e.g., `.pml-detail .ant-form-item`); global `querySelector` / `querySelectorAll` forbidden.
+- Locate input boxes by placeholder within the target container.
+- Normalize both sides of text comparisons with `.replace(/\s+/g,'')` (antd inserts spaces into two-character Chinese buttons).
+- Visibility criterion uses `getClientRects().length > 0` or `getBoundingClientRect().width > 0`; `offsetParent` forbidden (always null under a `position: fixed` ancestor).
+- The `a-select` clear icon renders only on hover: dispatch mouseenter / mouseover first, wait one tick, then click.
+- The antd pagination size-changer dropdown cannot be opened via synthetic events (focus + dispatched keydown Enter is also unstable): the real path = click the combobox uid with the click tool; measure with the invariant "each option `scrollWidth <= clientWidth+1` and dropdown width ≥ widest option scrollWidth"; if the dropdown animation has not finished, measuring yields 0 size, wait ≥600ms before measuring (2026-11-06 PML pagination verification).
+- Small controls inside modals (e.g., paginator) are squeezed out of the a11y snapshot by the large table behind (output over limit truncation makes the uid unavailable): temporarily `setAttribute('aria-hidden','e2e-hide')` on the background table container to shrink the tree, obtain the uid, perform the real click, then remove the attribute; be careful not to hide the modal's own table as well (2026-11-06 PML verification).
+- If an `a-select` cannot be selected via synthetic events → use real mouse + keyboard: CDP `Input.dispatchMouseEvent` opens it, `ArrowDown` + `Enter` selects; between multiple selects press `Escape` first to close the previous dropdown; query options limited to the last visible dropdown (`.ant-select-dropdown:not(.ant-select-dropdown-hidden)`).
+- Locate segmented / radio / tabs by rendered form (e.g., `.ant-radio-button-wrapper`), do not only look for `<button>`.
+- Table selection state: clear leftover checkmarks by deduplicating rows by `data-row-key` and clicking row by row, and execute in two ticks separately from subsequent selection; clicking the header select-all in indeterminate / none state is "select all", not "clear".
+- The first tbody row of an antd table with `:scroll={y}` is `.ant-table-measure-row` (height 0, no `ant-table-cell` class): skip it for row-height / cell measurements.
+- `ctx.evaluate` already returns an object, do not wrap it again in `JSON.parse`.
+- "Back"-type buttons on the detail overlay use `history.back()`: empirically clicking it goes back to the previous step or even `about:blank` (hit during 2026-11-03 purchase order detail verification) — to return to the list use refresh or direct re-navigation; never click "Back" as a close action.
+- Before asserting, confirm the overlay content has rendered (header button group appears): a document created in a parallel session may fail to load detail, leaving only the "Back" button in the overlay (empirically 2026-11-03) — switch to a known sample document, do not judge a feature defect from this.
+
+### AG Grid list page
+- Cell overhead is 32px (padding 15×2 + border 2), not 16 / 24.
+- Measure width with a hidden DOM span (copy `font` / `letter-spacing`), never canvas; fixed width `ceil10(max(header requirement, content p90 requirement) + 32 + 8)`, outliers delegated to `tooltipShowMode:'whenTruncated'`.
+- Judge truncation directly by comparing `.ag-cell`'s `scrollWidth > clientWidth`; measure horizontal overflow with `.ag-center-cols-viewport`, not `.ag-body-viewport`.
+- Under column virtualization columns outside the viewport are not in the DOM: `.ag-header-cell` count ≠ total column count.
+- Nulls rendered as the literal `-` via `valueFormatter`: cell emptiness checks must explicitly exclude `'-'`.

package/locales/en/overrides/.agents/skills/visual-parity/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: visual-parity
+description: Visual alignment playbook — for pixel-level alignment of two implementations (prototype / old page / design), fix viewport and data, change only styles, classify differences with evidence; for UI restoration tasks.
+---
+
+# visual-parity — Visual alignment
+
+## Trigger
+
+Prototype → implementation, old page → new page, design → page, requiring "looks consistent".
+
+## 0. Fix comparison conditions
+
+Same viewport (width/height + DPR), zoom 100%, same theme, same data (seed IDs fixed). Service online and auth per `.agents/skills/verify-ui/SKILL.md` §1; technical details single source `scripts/verify/e2e/harness.mjs`.
+
+## 1. Capture comparison
+
+Screenshot the same region on both sides (including boundary elements), named `tmp/e2e-evidence/parity-<topic>-{before,after}.png`. Before screenshotting reset scroll position, disable animations and tooltips.
+
+## 2. Diff classification (count item by item)
+
+Spacing / font size and weight / color / layering and shadows / border radius / wrapping and overflow / scrollbars. Rendering noise (font antialiasing, subpixel) listed separately, not counted as to-fix.
+
+## 3. Iterate
+
+Change only styles and layout, not data, not backend, do not import prototype fonts. Re-screenshot the same region each round; diff items only decrease, never increase.
+
+## 4. Criteria and evidence
+
+To-fix items = 0 counts as aligned; do not claim "consistent" before clearing. Evidence: both sides' screenshot paths + viewport + diff table (item / before / after / status).
+
+## Red lines
+
+- Do not weaken the verification path (`.agents/skills/verify-ui/SKILL.md` "weakening the verification path to pass is forbidden").
+- Do not substitute "it looks the same to the eye" for the diff table.

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

@@ -0,0 +1,56 @@
+---
+name: why
+description: Trace "why it looks like this" — search source history, process trail, domain docs, session records, issues/PRs, and external evidence in parallel, giving a pointer for each finding; use before changing code you do not understand.
+---
+
+# why — Why it looks like this
+
+## Triggers
+
+- "Why was it designed this way / why is this flag off / why was this option chosen".
+- You are about to change code you do not understand and first need to know why it exists.
+- During review you are uneasy about the intuition "this line cannot be deleted" and need evidence.
+
+## Core
+
+**No memory, no guessing.** Search in parallel by evidence category, and give every conclusion a pointer (`file:line` / commit / doc / issue / metric). Distinguish **measured / inferred / guess**; not finding anything is also an answer—write "no record", do not invent.
+
+## Evidence categories (search in parallel)
+
+| Category | Entry point in this repo |
+|---|---|
+| Source and history | `git log -S<term>` (pickaxe), `git log --follow -- <path>`, `git blame`, `xd://lsp` references |
+| Process trail | `workflow/{intents,specs,plans,incidents}`, `workflow/archive/`, `workflow/delegations.md`, `workflow/papercuts.md`, `workflow/regression-checklist.md` |
+| Domain knowledge | `wiki/`, `node .agents/scripts/kb-search.mjs <term>` |
+| Session records | `history://`, `archive` (eval global), `.agents/skills/session-resume/SKILL.md` |
+| Issue / PR | `issue://<N>`, `pr://<N>` (when a GitHub remote exists) |
+| External docs | `microsoft_docs_search`, `web_search`, `read <url>` |
+| Runtime / monitoring | available MCPs (chrome-devtools, context-mode, etc.), logs, `workflow/metrics.md` |
+
+## Steps
+
+1. **Break down the subject**: split the question into searchable terms—symbol names, file paths, feature names, decision keywords. If one term finds nothing, try synonyms/Chinese/English.
+2. **Local evidence**: run `node .agents/skills/why/scripts/why-evidence.mjs <term> [--path <file>]` to get pickaxe, path history, workflow/wiki hits, and kb-search summaries in one pass.
+3. **External evidence**: search issues/PRs, external docs, and monitoring in parallel via available MCPs; skip if unavailable—do not pretend you searched.
+4. **Synthesize**: give the conclusion first (why), then the evidence chain (each claim with a pointer), and finally unknowns/conflicts.
+5. **Mark certainty**: `measured` (ran it / read the original), `inferred` (derived from evidence), `guess` (no evidence). Predictions and unobserved causes are always `guess`.
+6. **Timeline** (optional): when a decision spans multiple commits/docs, order a chain by time and mark the turning points.
+
+## Output format
+
+- **Conclusion**: one sentence answering "why".
+- **Evidence chain**: each = claim + pointer (`file:line` / commit / doc / issue) + certainty.
+- **Unknowns / conflicts**: parts that cannot be found, evidence that contradicts itself, or that needs the owner to decide.
+- **Implications for the change**: whether this can be touched, and what must hold before touching it.
+
+## Where it lives in this repo
+
+- Takeover/continuation: after `session-resume` rebuilds the current state, use this skill to fill in "why".
+- Bug fixing: before `diagnosing-bugs` finds the root cause, confirm why this code exists.
+- Review: "Impact proof" in `review.md` uses `blast-radius`; this skill adds "historical intent".
+- Evidence collector: `.agents/skills/why/scripts/why-evidence.mjs` (collects only, does not conclude).
+
+## Boundaries
+
+- This skill answers "why it looks like this"; `blast-radius` answers "what it will break"; `how` answers "how it works". The three do not replace each other.
+- Do not write speculation as fact; without evidence, write "no record".