agentic-flow-kit 1.8.2 → 2.0.0

package/locales/en/overrides/wiki/INDEX.md

@@ -0,0 +1,33 @@
+# Wiki index
+
+> This directory is the project knowledge base, organized by topic. Board: `知识沉淀总览.html` (same directory, three-column mapping table).
+>
+> New installs start empty: place documents in the matching topic directory, then run `node .agents/scripts/gen-wiki-board.mjs`; this index and the board are regenerated automatically.
+
+## Topic directories at a glance
+
+| 主题 | 文件数 | 用途 |
+|---|---|---|
+| 产品需求 | 0 | New requirement prototype package (logic.md + app.html) |
+| 开发方案 | 0 | Data dictionary, API definitions, business module overview |
+| 数据维护 | 0 | Ledger of schema change / data repair / import / query / backup SQL |
+| 项目规范 | 0 | Development standards and hard constraints |
+| 用户功能 | 0 | Module feature docs, verification manuals, data-flow volumes |
+| 测试报告 | 0 | Archive of test and review reports |
+| drafts-archive | — | Original document backups (subdirectories by date-topic) |
+
+合计：**0 份**知识文档，**6 个主题**
+
+---
+
+## 文件 → 主题 → 归属目录 映射表
+
+(Generated by `node .agents/scripts/gen-wiki-board.mjs`, do not hand-edit.)
+
+---
+
+## 命名规则
+
+- Name new documents as `<日期>-<主题>/` or `<主题>-<名称>.md`.
+- Paired documents (html/md) must be maintained in sync.
+- Generated areas (overview table data rows, mapping table, board DATA) must not be hand-edited.

package/locales/en/overrides/wiki/drafts-archive/README.md

@@ -0,0 +1,6 @@
+# Drafts Archive
+
+This is the protocol directory for archived drafts. Decommissioned content is recorded here; **git history is the only trace** for deleted material.
+
+- Keep only the archive protocol/readme; do not add active documents.
+- New designs belong in `workflow/specs/` or `workflow/plans/`.

package/locales/en/overrides/wiki//346/225/260/346/215/256/347/273/264/346/212/244/README.md

@@ -0,0 +1,22 @@
+# Data Maintenance Ledger
+
+This directory records all project data-maintenance SQL and execution status, grouped by phase:
+
+| Directory | Purpose |
+|---|---|
+| `schema变更/` | Schema changes (DDL); one `date-topic/` subdirectory per batch |
+| `数据修复/` | Existing-data fixes (DML); state affected row counts and rollback |
+| `数据导入/` | External data import scripts and mapping notes |
+| `查询/` | Read-only diagnostic SQL |
+| `备份/` | Backup and restore scripts |
+
+## Hard Constraints
+
+- Every new SQL must record its execution status and authorization source.
+- Never run a full-table `DELETE` / `UPDATE` without a `WHERE` clause.
+- Executing production SQL is irreversible and requires explicit user authorization; follow the project data-maintenance ledger and DB verification rules.
+- Script and ledger examples live in `_TEMPLATE.md` (if present).
+
+## Generated Artifacts
+
+`README.md` follows this directory protocol; the batch inventory is the subdirectories plus git history.

package/locales/en/overrides/wiki//347/237/245/350/257/206/346/262/211/346/267/200/346/200/273/350/247/210.html

@@ -0,0 +1,230 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<title>Knowledge Overview · {{projectName}}</title>
+<style>
+  :root {
+    --bg: #f7f8fb;
+    --card: #ffffff;
+    --border: #e6e8ee;
+    --text: #1f2937;
+    --muted: #6b7280;
+    --accent: #2563eb;
+    --accent-soft: #eff4ff;
+    --warn: #d97706;
+    --shadow: 0 1px 2px rgba(0,0,0,.04), 0 4px 16px rgba(0,0,0,.04);
+  }
+  * { box-sizing: border-box; }
+  body {
+    margin: 0;
+    font-family: -apple-system, "Segoe UI", "PingFang SC", "Microsoft YaHei", sans-serif;
+    background: var(--bg);
+    color: var(--text);
+    line-height: 1.5;
+  }
+  header {
+    padding: 32px 40px 16px;
+    background: linear-gradient(135deg, #1e3a8a 0%, #2563eb 100%);
+    color: #fff;
+  }
+  header h1 { margin: 0 0 4px; font-size: 24px; font-weight: 600; }
+  header .meta { opacity: .85; font-size: 13px; }
+  main { max-width: 1400px; margin: 0 auto; padding: 24px 40px 64px; }
+  .summary {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(160px, 1fr));
+    gap: 12px;
+    margin-bottom: 24px;
+  }
+  .stat {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 10px;
+    padding: 14px 16px;
+    box-shadow: var(--shadow);
+  }
+  .stat .num { font-size: 22px; font-weight: 600; color: var(--accent); }
+  .stat .lbl { font-size: 12px; color: var(--muted); margin-top: 2px; }
+  .toolbar {
+    display: flex;
+    gap: 8px;
+    margin-bottom: 12px;
+    flex-wrap: wrap;
+    align-items: center;
+  }
+  .toolbar input {
+    flex: 1 1 280px;
+    max-width: 480px;
+    padding: 8px 12px;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    font-size: 13px;
+    background: var(--card);
+  }
+  .toolbar select {
+    padding: 8px 12px;
+    border: 1px solid var(--border);
+    border-radius: 8px;
+    font-size: 13px;
+    background: var(--card);
+  }
+  .topic-section {
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    margin-bottom: 16px;
+    overflow: hidden;
+    box-shadow: var(--shadow);
+  }
+  .topic-header {
+    padding: 12px 16px;
+    background: var(--accent-soft);
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    cursor: pointer;
+    user-select: none;
+  }
+  .topic-header:hover { background: #e0ebff; }
+  .topic-header .name { font-weight: 600; color: var(--accent); font-size: 15px; }
+  .topic-header .count {
+    background: var(--accent);
+    color: #fff;
+    border-radius: 12px;
+    padding: 2px 10px;
+    font-size: 12px;
+    font-weight: 500;
+  }
+  table {
+    width: 100%;
+    border-collapse: collapse;
+    font-size: 13px;
+  }
+  thead th {
+    text-align: left;
+    padding: 10px 16px;
+    background: #fafbfd;
+    border-bottom: 1px solid var(--border);
+    color: var(--muted);
+    font-weight: 500;
+    font-size: 12px;
+    text-transform: uppercase;
+    letter-spacing: .04em;
+  }
+  tbody td {
+    padding: 8px 16px;
+    border-bottom: 1px solid #f0f2f5;
+    vertical-align: top;
+  }
+  tbody tr:last-child td { border-bottom: none; }
+  tbody tr:hover { background: #fafbff; }
+  td.file { font-family: "SF Mono", Consolas, monospace; font-size: 12.5px; color: #111827; }
+  td.file a { color: var(--accent); text-decoration: none; }
+  td.file a:hover { text-decoration: underline; }
+  td.topic-cell { color: var(--muted); }
+  td.dir a {
+    color: var(--accent);
+    text-decoration: none;
+    font-family: "SF Mono", Consolas, monospace;
+    font-size: 12px;
+  }
+  td.dir a:hover { text-decoration: underline; }
+  footer { padding: 24px 40px; color: var(--muted); font-size: 12px; text-align: center; }
+</style>
+</head>
+<body>
+<header>
+  <h1>Knowledge Overview</h1>
+  <div class="meta">{{projectName}} · Project knowledge base</div>
+</header>
+
+<main>
+  <div class="summary" id="summary"></div>
+
+  <div class="toolbar">
+    <input type="text" id="search" placeholder="🔍 Search file name / topic / directory…" />
+    <select id="topicFilter">
+      <option value="">All topics</option>
+    </select>
+  </div>
+
+  <div id="topics"></div>
+</main>
+
+<footer>Board generated by the wiki skill · Raw data in wiki/INDEX.md</footer>
+
+<script>
+const DATA = {
+  "summary": { "total": 0, "topics": 0, "files": 0, "archive": 0 },
+  "topics": []
+};
+
+// 顶部统计卡片
+document.getElementById('summary').innerHTML = `
+  <div class="stat"><div class="num">${DATA.summary.topics}</div><div class="lbl">Topics</div></div>
+  <div class="stat"><div class="num">${DATA.summary.files}</div><div class="lbl">Knowledge documents</div></div>
+  <div class="stat"><div class="num">${DATA.summary.archive}</div><div class="lbl">Draft archive</div></div>
+  <div class="stat"><div class="num">${DATA.topics.reduce((s,t)=>s+t.files.length,0)}</div><div class="lbl">Total records</div></div>
+`;
+
+// 主题过滤器
+const sel = document.getElementById('topicFilter');
+DATA.topics.forEach(t => {
+  const o = document.createElement('option');
+  o.value = t.name; o.textContent = `${t.name} (${t.files.length})`;
+  sel.appendChild(o);
+});
+
+function escapeHtml(s){ return String(s).replace(/[&<>"]/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;'}[c])); }
+
+function render(filterText='', topicFilter='') {
+  const container = document.getElementById('topics');
+  container.innerHTML = '';
+  DATA.topics
+    .filter(t => !topicFilter || t.name === topicFilter)
+    .forEach(t => {
+      const rows = t.files.filter(f =>
+        !filterText ||
+        f.file.toLowerCase().includes(filterText.toLowerCase()) ||
+        f.topic.toLowerCase().includes(filterText.toLowerCase()) ||
+        f.dir.toLowerCase().includes(filterText.toLowerCase())
+      );
+      if (rows.length === 0) return;
+      const section = document.createElement('div');
+      section.className = 'topic-section';
+      section.innerHTML = `
+        <div class="topic-header">
+          <span class="name">📁 ${escapeHtml(t.name)}</span>
+          <span class="count">${rows.length}</span>
+        </div>
+        <table>
+          <thead><tr><th style="width:40%">File name</th><th style="width:20%">Topic</th><th>Directory</th></tr></thead>
+          <tbody>
+            ${rows.map(f => {
+              const base = f.file.split('/').pop();
+              const fileCell = /\.(html)$/i.test(f.file)
+                ? `<td class="file"><a href="${escapeHtml(f.dir + base)}" target="_blank" title="Open document">${escapeHtml(f.file)}</a></td>`
+                : `<td class="file">${escapeHtml(f.file)}</td>`;
+              return `
+              <tr>
+                ${fileCell}
+                <td class="topic-cell">${escapeHtml(f.topic)}</td>
+                <td class="dir"><a href="${escapeHtml(f.dir)}" title="Open directory">${escapeHtml(f.dir)}</a></td>
+              </tr>`;
+            }).join('')}
+          </tbody>
+        </table>`;
+      container.appendChild(section);
+    });
+  if (!container.innerHTML) {
+    container.innerHTML = '<div class="topic-section" style="padding:24px;text-align:center;color:var(--muted)">No matching records</div>';
+  }
+}
+
+document.getElementById('search').addEventListener('input', e => render(e.target.value, sel.value));
+sel.addEventListener('change', e => render(document.getElementById('search').value, e.target.value));
+render();
+</script>
+</body>
+</html>

package/locales/en/overrides/workflow/INDEX.md

@@ -0,0 +1,13 @@
+# workflow index (generated, do not hand-edit)
+
+> Regenerated by `node .agents/scripts/gen-workflow-index.mjs` from `workflow/{intents,specs,plans,incidents}/`.
+> This file is a placeholder for new installs; the active layer and archive table are populated after the first generation.
+
+## Active (0)
+
+| Type | Level | Status | Date | Module | Topic | Progress |
+|---|---|---|---|---|---|---|
+
+## Archive (read-only, no growth)
+
+(Historical terminal artifacts are listed by the generator after archiving.)

package/locales/en/overrides/workflow/README.md

@@ -0,0 +1,67 @@
+# workflow — AI-driven closed loop (single source of truth)
+
+This directory is the sole home of the AI workflow engine. L1 new requirements enter through a single plan; L2/L3 new requirements go intent → spec → plan; fixes go through an incident. At the micro-task layer, a "Task Owner + AI paired closed loop" model is used, with confirmation completed in one sentence in the conversation (TTY / delegated auto-record). At the macro trunk layer, multi-person collaboration is supported; merges to main are guarded by the TFS PR branch policy (Peer Review team review + Azure Pipelines CI gates sourced from the same scripts as local), and traceability relies on git (commit + PR records + release tags).
+
+> All new closed-loop records are written in this directory.
+
+## Directory structure
+
+| Directory | What goes here | Naming |
+|------|--------|------|
+| `intents/` | L2/L3 new requirement entry: background, goals/non-goals, acceptance criteria, level, red lines touched. Not created for L1 new requirements | `YYYY-MM-DD-<topic>.md` |
+| `specs/` | L2/L3 design spec: functional behavior, data flow, system changes, constraint-compliance mapping. Not created for L1 | Same name as intent / incident |
+| `plans/` | L1 new requirement entry (source / goals / red lines / change plan / constraints and risks / verification plan / acceptance criteria). L2/L3 and fixes still share the name of intent / incident | `YYYY-MM-DD-<topic>.md` |
+| `incidents/` | Incident retrospective: timeline, root cause, why it was not caught, retrospective triad | `YYYY-MM-DD-<topic>.md` |
+
+**Naming is always English kebab-case** (e.g. `2026-09-07-supplier-rating-field.md`), **Chinese file names are forbidden**—the original check-loop §9 non-ASCII filename warning retired with the 2026-10-28 engine slimming; the naming convention is unchanged. Document content (title/body) is not subject to this restriction.
+
+**Document protocol (structured 2026-09-13)**: the header of all four document types is YAML frontmatter (restricted subset, one `key: value` per line, the single source of check-loop machine fields)—`状态` (intent/spec/plan: draft/approved/done/superseded/cancelled; incident: open/fixed/closed, **strict enum**, notes go in the `备注:` key), `级别` (L1/L2/L3), `日期`/`发现` (YYYY-MM-DD), `模块` (**required for new documents since 2026-09-22**, values from the `.agents/config/workflow-modules.txt` vocabulary, a single value uses the dominant module; existing documents are not backfilled, AI fills them in when touching), L3 spec's `确认结果`/`确认时间`, backfilled documents `流程: legacy`. **`日期` fallback rule (fixed 2026-10-27)**: plans are generated by `fill-plan.mjs` and `plans/_TEMPLATE.md`; **frontmatter has written `日期` since 2026-10-27** (previously renderPlan accepted a date parameter but did not persist it)—for any gate whose precondition is frontmatter `日期` (delegation ledger presence gate; check 18 retired with the 2026-10-28 engine slimming), when the date is missing it still **falls back to the filename prefix** `YYYY-MM-DD` as a second safety net (following check 15's existing rule; check 19 retired); if neither frontmatter nor filename has a date → undecidable → skip. The old rule "no date means skip the whole section" silently disabled the delegation gate for most L2/L3 plans (after 52 anchors, L2/L3 terminal documents were never reconciled). **`状态` transitions must pass through `approved`** (the machine-visible state of confirmation; `done` appears only at close): for specs/plans created since 2026-09-23, if already done and git history never contains a line-start `状态: approved`, check-loop reports a "confirmation state missing" warning. check-loop scans only frontmatter for machine fields (`fm_get` field assertion); the body no longer writes "状态：/级别：" lines; narrative fields (independent review / retrospective triad / acceptance checks) remain in the body anchored by section. Protocol changes and backfill migration are in the 2026-09-13 `docs(workflow)` commit. **Explicit blocking of ambiguities (2026-10-16, NEEDS-CLARIFICATION marker)**: when drafting or revising a spec/plan and an ambiguity cannot be decided alone (multiple interpretations / missing standard / external fact dependency), **guessing is forbidden**—insert `[NEEDS CLARIFICATION]: <one-line question>` in place to ask the user; after clarification remove the marker and record the decision in the body; the marker must be cleared before advancing to approved (self-check discipline; grep the marker in active documents for the pending-clarification list. Automated cross-artifact gap checks are deferred—the conflict with the "defer new gates" trade-off is explicitly logged, to be revisited after D6 metrics). **Commitment-surface binding (new 2026-10-27)**: what the user approves at the moment of `approved` is the **commitment surface** (criteria text / red lines / goals / change plan / constraints and risks)—a commitment rewritten after confirmation without re-approval = the user did not approve what is delivered at close. Legal actions at close (ticking acceptance + evidence backfill, `确认结果`/`确认时间` backfill, review-line re-anchoring) **do not change the commitment surface** and are not false-flagged after normalization; if commitment criteria are rewritten, hard block (check 15) + rejection at close (confirm-doc commitment-surface binding gate). The **only way** to change a commitment = after the user re-approves, run `confirm-doc <doc> --reconfirm --delegated "<original words>"` to re-record the commitment-surface fingerprint (does not advance status; the status line is still written by confirm-doc, do not hand-edit frontmatter); existing records (pre-launch confirmations, ledger rows without a `commit` field) are not retroactive. **Editing a closed document body requires re-recording the fingerprint in the same commit (2026-11-10, incident 2026-10-26-workflow-confirmation-drift-hard-block)**: editing the body of a closed (done/superseded/closed/cancelled/fixed) document = must re-record the confirmation fingerprint in the same commit (`confirm-doc` / `--reconfirm`) or use a compensation row (`append-compensation.mjs`), otherwise check-loop flags "confirmation content drift"; at commit time `check-doc-body-drift.mjs` provides advisory visibility (not a gate).
+
+Each subdirectory's `_TEMPLATE.md` is a starter template; copy it and fill it in; do not edit the template itself.
+
+The root `regression-checklist.md` is a **living regression checklist**: the unified landing point for deploy must-pass items and incident anti-recurrence verification, extended as modules ship and appended as incidents occur.
+
+**The three append-only ledgers are sharded** (2026-10-13 ledger-shard-ledgers): data rows of `regression-checklist` / `delegations` / `papercuts` are stored monthly in `workflow/<ledger>.d/<YYYY-MM>.md`; the main ledger keeps only the description, table header and GENERATED area—eliminating the size and merge-conflict surface of "rewrite the whole file on every append". The single source for reads and writes = `.agents/scripts/ledger-shards.mjs` (the read side automatically merges the main ledger ∪ all shards; existing consumers need no change); append one row with `node .agents/scripts/ledger-shards.mjs --append <ledger> --row "<row>"`. (The fourth ledger `deploy-observations` was retired and deleted with the deploy ritual—2026-10-29 owner decision: actual releases do not use a tag/24h observation ritual; merge = PR create → review → regression → merge → archive, see `deploy.md` header note.) confirmations.d shards start in 2026-10; 2026-09 has no shard (that month's confirmations are traceable only via git; historical gaps are not backfilled); jsonl ledger schemas self-describe by field presence across generations (e.g. quoteGrounding since 2026-10-24), with no version field (2026-11-05 decision).
+
+**Gate judgment monthly shards** (2026-10-22 gate-metrics-shard): `workflow/gate-metrics.d/<YYYY-MM>.jsonl` holds one row per month (rule × WARN/BLOCK), generated by `node .agents/scripts/agg-judgments.mjs --emit-month` and committed with the change; pre-push monthly checks automatically backfill the previous month's shard. The retirement criterion (N consecutive months = 0) reads the union of local `.agents/judgments.jsonl` and the shards and takes the max—machine/worktree changes no longer reset it to zero; multi-machine union (`.gitattributes` reuses `jsonl-union`).
+
+## Usage
+
+- **Start a new task**: run `.agents/commands/new-task.md` (leveling + L0 minimal path / L1 fast path entrance); L2/L3 enter the four chapters of `.agents/commands/stages.md` (Plan → Design → Build → Test, 2026-11-08 tier 2-F four-in-one)
+- **Board (optional, not started by default)**: run `node .agents/scripts/ensure-board.mjs` manually when needed (idempotent: liveness probe / auto-restart stale code / launch browser on fresh start), live read-only at http://127.0.0.1:8933; **advisory layer, not a gate; alert semantics aligned with check-loop hard blocks**. "Stale code" = LastWriteTime of `board/index.html` or `workflow-board-server.mjs` later than the board process start by 2s (restart if either is updated); if the port is occupied, probe `/api/board` first—a response without `cards` means another process, so leave it alone, do not kill, and skip to the next port
+- **Search**: read `INDEX.md` for active workflow (generated; regenerate with `node .agents/scripts/gen-workflow-index.mjs`, drift check with `--check`); cross-corpus search with `node .agents/scripts/kb-search.mjs "<term>"` (workflow section-level location + wiki full text, filters `--type/--module/--status/-n`; `--status all` for an explicit full set)
+- **Archive**: archive on close (2026-10-13 archive-on-close)—after `confirm-doc.mjs` records the terminal state it automatically `git mv`s **the family involved in this confirmation** (same-name intent/spec/plan/incident) into `workflow/archive/<terminal-month>/{type}/`, so active directories no longer accumulate terminal artifacts. **Feature branches are not archived by default** (since 2026-10-15, to prevent CI lane gates from blocking legitimate merges)—after merge, main/develop close or sweep takes over; staying within the 21-day window is normal. For historical backlog run `node .agents/scripts/archive-sweep.mjs [--window 21] [--execute]` (dry-run by default) manually in batches; archived artifacts remain searchable by `kb-search` (`archive/<batch>/<type>` is covered), while check-loop pairing and content-binding gates scan only the four direct directories and do not trigger on archived items. When terminal artifacts pile up, run archive-sweep monthly (dry-run to inspect candidates, `--execute` to apply).
+- **spec lifecycle stance (2026-10-16 owner decision, Böckeler three-layer classification: spec-anchored + long-term maintenance)**: a spec is a **continuously referenced source of truth and does not expire after delivery**—when a code change touches behavior covered by a spec (including archived ones), compare against that spec: behavior drift either changes the code back to the spec or changes the spec in the same commit; disputes go to an incident for adjudication. **Archiving is capacity management, not invalidation**: archiving only removes terminal artifacts from active scan surfaces (INDEX active rows / check-loop four-directory scan / monthly regeneration); source-of-truth status and revision rights are unchanged—archived specs can be revised in place without changing the archive location. Size governance observes before setting limits: spec line count / acceptance item distribution is collected in the metrics.md observation column (advisory caps conflict with the "defer new gates" trade-off; explicitly postponed until D6 metrics are complete).
+- **Follow-up on the same feature (search before create, 2026-10-22)**: before starting work, search `workflow/specs/`, `workflow/archive/**/specs/`, `.agents/skills/verify-ui/features/`, `workflow/regression-checklist.md` by "module + feature keyword". If a hit covers the same behavior → revise the original (specs are revised in place per the item above; do not create new); create new only for a genuinely new feature. When creating task documents, include the feature key in the topic for later search.
+- **Verification**: `.agents/commands/stages.md` Test chapter (static gates + UI testing); DB-switch liveness and API anti-recurrence assertions run via `node scripts/verify/business/regression-smoke.mjs` (read-only by default; `--writes` creates and cleans its own probes, dev DB only)
+- **Review**: `.agents/commands/review.md` (P0 / P1 / P2 grading: machine baseline + AI self-check list, user decides classification and merge)
+- **PR panel review**: the panel has been retired to a **manual tool** (2026-11-09 automatic gate retired)—pre-push / CI / pr-create no longer enforce a review ledger; orchestrate manually per `.agents/commands/pr-review.md` when needed; create a PR via `node .agents/scripts/pr-create.mjs ...` (gate first, then call `tfs-pr create`)
+- **Deploy**: `.agents/commands/deploy.md` (must-run checklist before release)
+- **Quantification**: delegated/self-done results go in `delegations.md`, aggregate with `node .agents/scripts/agg-delegations.mjs` (**the concurrency expansion threshold is in that file—do not expand concurrency before the numbers qualify**); the **monthly snapshot** of corpus and resident-surface size runs `node .agents/scripts/gen-workflow-metrics.mjs` (one row per month in `metrics.md`, rerunning in the same month updates it; details on stdout)
+- **Traceability**: git is the audit trail. Two driving paths, choose one and never mix—manual stage routing (confirmed workflow documents folded into one `docs(workflow)` commit, code in a separate commit; ordinary L1 requirements have only a plan, fixes have incident+plan, L2/L3 have entry+spec+plan) or the `pipeline-run` state machine (per-stage `docsCommit` commits of the same shape; protocol single source `.agents/commands/pipeline-run.md`). Release does not use a tag/24h observation ritual (release tag and release observation ledger retired 2026-10-29). Local development relies on the Independent Reviewer for cognitive-isolation self-check; main merges get complete audit evidence through TFS PR team review and git history
+- **Levels**: L1 implementation-level (does not hit L2/L3; the entrance for new requirements is a plan) | L2 rules / contracts (coding authority / shared contracts / existing interface semantics / global cross-cutting rules, closed set of touch surfaces in `.agents/commands/new-task.md`) | L3 data and runtime structure (schema / migration SQL / DI chain / auth and middleware pipeline). Mixed changes take the higher level
+
+## Execution model
+
+- The default host main agent handles stage routing, user confirmation, key judgment and final acceptance; it is not registered as an extra role.
+- Stage commands delegate to `.agents/roles/implementer.md`, `.agents/roles/independent-reviewer.md`, `.agents/roles/ui-verifier.md` only when boundaries are explicit.
+- OpenCode, Trae and ZCode register roles through thin adapters under `.opencode/agents/`, `.trae/agents/`, `.zcode/agents/`; role behavior is maintained only in `.agents/roles/`.
+- PI registers 7 role shells through `.pi/agents/` (same contract as `.agents/roles/`); `.pi/extensions/` wires tool_call to the two gates under `.agents/hooks/`, with a single judgment source and no duplication. `.pi/` is a machine-private directory (`.gitignore`) and is not propagated by clones; stage commands follow the root `AGENTS.md` §4 routing table and are read directly by the main Agent from `.agents/commands/*.md` (pi has no wf-* command shells); the wiring reality is reconciled by `check-local-gates.mjs` advisory, mechanism in `runtime-env.md` §6.4.
+- Cline connects through `.cline/workflows/` (7 pointer shells → `.agents/commands/`) and `.cline/agents/` (7 role definitions, **YAML** → `.agents/roles/`); Cline natively reads `AGENTS.md` and `.agents/skills/`, so the rule and skill surfaces take effect with zero changes. `.cline/` is a machine-private directory (`.gitignore`) and is not propagated by clones; **the two gates are not wired** (the Cline hook protocol is incompatible with the repo's `.agents/hooks/*.cjs`; integration needs a protocol adapter), mechanism in `runtime-env.md` §6.4.
+- When the host does not support subagents, execute according to the command frontmatter `fallback`; but **independent review has no fallback**—the L2 / L3 `independent-reviewer` is always `required: true`; if the host does not support subagents, open a new session and never fall back to self-check by the original main agent.
+- Subagents must not cross user confirmation gates, nor commit, merge or deploy on their own; all results are reviewed by the main agent before user decision.
+
+## Closed-loop rules
+
+1. L1 new requirements start from an approved plan, with no separate intent. L2/L3 new requirements start from an approved intent. Fixes start from an approved incident; L1 fixes create a same-name L1 plan and use `.agents/commands/new-task.md` §L1 fast path (normally do not open `stages.md`)
+2. L2/L3 must first have a same-name spec approved (L2/L3 always force independent review, see `stages.md` Design §3) before drafting a plan. L1 plans are drafted and confirmed in `new-task.md` §L1 fast path (`stages.md` covers only L2/L3); the sections are entry / change plan / constraints and risks / verification plan / acceptance criteria
+3. Implementation artifacts must pass static gates (architecture red lines + build + test)
+4. Production / live-test defects fall back to `incidents/`; the retrospective triad (new intent, anti-recurrence verification, standards entry) is mandatory; **when the root cause is "gate missing / standard not implemented / systemic problem", a new intent must be filed even if the structural fix is complete**, to track systemic improvement; do not bypass the intent loop on the grounds that "the fix is already done"
+5. Close in test, regardless of whether it has reached prod. L1 ticks the plan's "Acceptance criteria" and adds evidence, then plan → done. L2/L3 tick the intent's "Acceptance criteria", then intent → done and the same-name plan becomes done. Fix incidents go open → fixed → closed and the same-name plan becomes done. If done still has unchecked items, check-loop blocks (hard-block for documents created since 2026-09-12; existing documents are only warned, not backfilled). Going to prod follows deploy separately (PR merge checklist, no tag/24h ritual)
+6. Abandonment records: approved but not done → `superseded`; cancelled before completion → `cancelled`. Both are confirmed terminal states, and check-loop does not block on "status unconfirmed"; L3 abandoned documents are exempt from "confirmation result must be approved"
+7. Subsequent regression checklists and weekly checklists are also archived in this directory
+8. **Check 17 (release draft gate) was retired and its code deleted on 2026-10-21**: this repo root `package.json` has no `version` field, so the version anchor condition never holds (2026-10-06 audit); releases do not use the tag ritual (see "Traceability"). That hard gate no longer exists; do not interpret it as "always skipped"
+
+## Historical archive (read-only, no growth)
+
+- New requirement design documents always go in `workflow/specs/` or `workflow/plans/`; critical paths are distilled into `workflow/regression-checklist.md`.

package/locales/en/overrides/workflow/archive/README.md

@@ -0,0 +1,3 @@
+# Historical archive
+
+> Terminal artifacts are archived here by year-month, read-only and never appended. Archive protocol in `workflow/README.md`.

package/locales/en/overrides/workflow/delegations.md

@@ -0,0 +1,4 @@
+# Delegation ledger monthly snapshot (generated, do not hand-edit)
+
+> Regenerated by `node .agents/scripts/agg-delegations.mjs --write`.
+> Placeholder for new installs; populated after the first generation.

package/locales/en/overrides/workflow/effective-policy.md

@@ -0,0 +1,4 @@
+# Effective policy snapshot (generated, do not hand-edit)
+
+> Regenerated by `node .agents/scripts/gen-effective-policy.mjs`.
+> Placeholder for new installs; the anchor table and effective policies are populated after the first generation.

package/locales/en/overrides/workflow/gate-cost.md

@@ -0,0 +1,4 @@
+# Gate cost recent-window snapshot (generated, do not hand-edit)
+
+> Regenerated by `node .agents/scripts/gen-workflow-metrics.mjs --gate-cost-only`.
+> Placeholder for new installs; recent-window gate timings are populated after the first generation.

package/locales/en/overrides/workflow/incidents/_TEMPLATE.md

@@ -0,0 +1,49 @@
+---
+状态: open
+级别: L1
+发现: YYYY-MM-DD
+来源: <self | user | test | monitor — who found it; see .agents/config/workflow-enums.txt incident.source.all>
+影响环境: <dev | staging | prod | none — environment the defect reached; none = did not reach a runtime environment>
+模块: <one of the vocabulary entries; see .agents/config/workflow-modules.txt>
+---
+# INCIDENT — <date topic>
+<!-- Copy to YYYY-MM-DD-<topic>.md; record every functional defect found in production or during verification, and historical bugs may be backfilled -->
+<!-- frontmatter restricted subset (2026-09-13): status ∈ open/fixed/closed (strict enum; put annotations in the note key); level ∈ L1/L2/L3; backfilled items from before the closed-loop engine was enabled add one line `流程: legacy` (exempt from level/pairing checks); do not repeat status/level/discovery lines in the body -->
+<!-- attribution keys (mandatory for new items since incident-attribution 2026-10-11; check-loop check 24): legacy items before the anchor are not backfilled; "source" is the defect finder (enables machine recomputation of the source × environment cross-tab instead of per-item manual reading), and "impacted environment" records the environment actually reached (write none if none) -->
+
+## 时间线
+- <discovery → localization → mitigation → recovery, with timestamps>
+- 用户确认：draft reviewed and passed (<date>)
+<!-- The line above is a **machine prerequisite for drafting an L2/L3 spec** (validated by fill-spec / confirm-doc): it must be a line-start item inside the "时间线" section;
+     accepted forms are `- 用户确认：…` / `- **用户确认**：…` / `- <date> 用户确认：…` (bold before/after the word and a date prefix are all fine);
+     narrative prose in the body (e.g. "the user confirmed the plan") does not count as a trace. The form list lives inside this comment so the sample line does not contain descriptive text. -->
+
+## 影响面
+- <pages / APIs / data scope>
+
+## 根因
+<One sentence; put the deeper cause on a separate line>
+
+## 为什么之前没拦住
+<Check gates / tests / conventions one by one: which layer could have caught it>
+
+## 复盘三件套（缺一不可）
+
+> Purpose: make the incident genuinely feed back into Plan, so "prevent recurrence" commitments do not remain only in documents. Modules are rolling out gradually, so incidents may come from any of dev / staging / prod.
+
+1. 结构性修复
+   - Fix commit: <SHA + list of changed files>
+   - Impacted environments: dev / staging / prod (for live modules affecting prod, include affected user count / duration / whether rolled back)
+   - New intent needed:
+     - Yes → ../intents/YYYY-MM-DD-<topic>.md (mandatory when the root cause is "missing gate / convention not implemented / systemic problem", even if the structural fix is already complete)
+     - No → Reason: <the root cause is an implementation bug, the point fix is complete, and an existing convention entry covers it>
+
+2. 防复发验证（必须落到自动化用例或回归清单条目，禁止只写「已人工验证」）
+   - Automated test: tests/<test file> (<case name / count>)
+   - Or test step: .agents/commands/stages.md Test chapter + <specific operation>
+   - Or regression-checklist entry: workflow/regression-checklist.md (append one line under the recurrence-prevention verification section)
+
+3. 规范条目（必须有可追溯的落点）
+   - Landing point (multiple allowed): AGENTS.md <section> / .agents/hooks/<script> / .agents/skills/<skill> / .agents/commands/<cmd> / regression checklist §<section>
+   - Reference: commit <SHA> / 文件:<path>#L<line>
+   - If no new entry, reason: <covered by an existing entry; state its location>

package/locales/en/overrides/workflow/intents/_TEMPLATE.md

@@ -0,0 +1,43 @@
+---
+状态: draft
+级别: L1
+日期: YYYY-MM-DD
+模块: <one of the vocabulary entries; see .agents/config/workflow-modules.txt>
+备注: <optional free-text note; check-loop does not parse>
+---
+# INTENT — <topic>
+<!-- Copy this template to YYYY-MM-DD-<topic>.md and fill it in; a same-named file under plans/ pairs with this file -->
+<!-- frontmatter restricted subset (2026-09-13): one `key: value` per line; status ∈ draft/approved/done/superseded/cancelled (strict enum; put annotations in the note key); level ∈ L1/L2/L3; check-loop scans only frontmatter for machine fields, so do not repeat status/level lines in the body -->
+
+## 背景与问题
+<Why do this; state the requirement source (ticket / communication record / to-do item)>
+
+## 目标
+- <Verifiable goal>
+
+## 非目标（L1 微改动无实质内容可删本节，不硬填）
+- <What is explicitly out of scope, to prevent scope creep>
+
+## 约束（L1 微改动无实质内容可删本节，不硬填）
+- <What to reuse; what must not be touched>
+
+## 影响面
+- 模块：shared / material (Domain / Application / Infrastructure / API)
+- 数据库：none / <table name> (schema changes → L3; runtime / pipeline structural surfaces without schema are also L3; for criteria see `.agents/commands/new-task.md` §level determination)
+- 前端页面：<route or component; delete this line if none>
+
+## 触达红线（对照 AGENTS.md，勾选仅标记触及范围；具体如何满足在同名 spec 中说明）
+- [ ] Application must not reference Infrastructure / DbContext (exemption only for native LINQ in the category tree)
+- [ ] Code-generation logic (FormulaEngine / CategoryPrefix) → level at least L2
+- [ ] Cross-caller contract changes (shared-layer base classes / DTO shape / interface signatures / existing parameter semantics / global response and pagination validation semantics) → level at least L2
+- [ ] schema / migration SQL / DI chain → level L3
+- [ ] Frontend: always Drawer / no a-select for large datasets / unified styles in style.css
+
+> Touching any red line makes it L2 / L3. You must create ../specs/YYYY-MM-DD-<topic>.md explaining how it is satisfied before drafting a plan.
+
+## 验收标准（可测试）
+<!-- Give each item a stable ID A1..An (anchor coverageSince 2026-10-22; the spec confirmation gate checks coverage by ID); add/remove using new numbers, never reuse old ones. -->
+- [ ] A1 <Each item must be testable; if you cannot write a testable criterion, it is not thought through yet>
+
+> **Closed-loop reconciliation**: closeout happens in the test stage (not dependent on deploy). Before setting intent to done, check and verify each item, and append evidence after each checked item — `- [x] <criterion>（证据：<commit SHA / test case name / smoke script output>）`.
+> A done intent with unchecked items is blocked by check-loop (new intents are hard-block since 2026-09-12; legacy intents only get a warning); checked items without "证据：" produce a warning.

package/locales/en/overrides/workflow/metrics.md

@@ -0,0 +1,4 @@
+# workflow metrics (generated, do not hand-edit)
+
+> Regenerated by `node .agents/scripts/gen-workflow-metrics.mjs` from ledgers and the document tree.
+> Placeholder for new installs; monthly metrics are populated after the first generation.

package/locales/en/overrides/workflow/papercuts.md

@@ -0,0 +1,3 @@
+# Papercuts list
+
+> Manually maintained: record high-frequency minor pain points and their disposition status. Format and item protocol in `workflow/README.md`.

package/locales/en/overrides/workflow/plans/_TEMPLATE.md

@@ -0,0 +1,47 @@
+---
+状态: draft
+级别: L1
+日期: <YYYY-MM-DD creation date>
+模块: <one of the vocabulary entries; see .agents/config/workflow-modules.txt>
+---
+# PLAN — <same topic as the entry document>
+<!-- Pairs with the same-named entry document under intents/ or incidents/; L2/L3 must first have a confirmed ../specs/ spec with the same name; AI drafts it, and work starts after the user confirms in the conversation -->
+<!-- frontmatter restricted subset (2026-09-13): status ∈ draft/approved/done/superseded/cancelled (strict enum; put annotations in the note key); level ∈ L1/L2/L3; do not repeat status/level lines in the body -->
+<!-- L1 (2026-10-10): for new tickets use fill-plan.mjs --level L1; this file is the entry document and no separate intent is created. Sections: entry / change plan / constraints and risks / verification plan / acceptance criteria. The "change surface / verification method" sections retained below are the legacy minimal form; do not copy these two section titles for new tickets. -->
+<!-- ambiguity discipline (2026-10-16): when drafting/revising, do not guess at ambiguities you cannot decide yourself (multiple interpretations / missing semantics / dependence on external facts) — insert [NEEDS CLARIFICATION]: <one-sentence question> in place in the relevant section and keep the document in draft while asking the user; after clarification, delete the marker and record the decision as body text. Markers must be cleared before approval (see workflow/README.md document protocol "explicit ambiguity blocking"). -->
+
+对应入口：L1 = this plan. For fixes, also keep ../incidents/YYYY-MM-DD-<topic>.md. L2/L3 = ../intents/YYYY-MM-DD-<topic>.md
+对应 spec：../specs/YYYY-MM-DD-<topic>.md (L2/L3 only)
+
+## 改动面（L1 极简形态主节；L2/L3 可作任务拆解的汇总或删本节）
+- <file/component>: <what to do; put criterion details directly in the item, e.g. "L771 message.success changed to 'Update succeeded'">
+<!-- Backfill this section to disk after the change list in stages.md Build §2 is confirmed (conversation traces apply only to that session) — change surface + task checkbox state + git status = the three session-reentry anchors (2026-10-11 session-context) -->
+
+## 任务拆解（L2/L3 必填；L1 仅多文件多步骤时用，单任务微改动删本节）
+<!-- Tasks are checkbox state (2026-10-11 session-context): check off each item immediately when done and backfill the trace; when resuming after compaction / in a new session, first read this table's checkbox state + git status to rebuild progress; never backfill checkmarks from memory -->
+<!-- Dependency rows (blocking edges, isomorphic to matt to-tickets): once blocking relations are declared explicitly, work may start as soon as "the tasks named in the dependency row are checked" — the task set with no unresolved blockers = frontier, which can be dispatched in parallel (multiple worktrees / delegate "new session + merge scope"); a purely sequential chain degrades the dependency row to "task N-1" at zero extra cost -->
+- [ ] 1. <Task>
+   - 判据：<what counts as done; preferably corresponds to one test or a reproducible operation>
+   - 依赖：none (can start immediately) / blocked by task <N>
+   - 风险：low / medium / high (<reason>)
+   - 留痕：(backfill commit SHA / test name / measured output when checking off)
+- [ ] 2. <Task>
+   - 判据：…
+   - 依赖：…
+   - 风险：…
+   - 留痕：…
+
+## 执行顺序（L2/L3 必填；L1 单文件微改动删本节）
+<1 → 2 → 3; when dependencies are already explicit in the "依赖" rows above, write only "see the task-breakdown dependency rows; frontier = tasks with no unresolved blockers"; for a purely sequential chain write 1 → N>
+
+## 验证方式
+- Build: <project build command> (+ <test command>)
+- Frontend: cd frontend && npm run build (vue-tsc)
+- UI: .agents/commands/stages.md Test chapter (required when page changes are involved; verify with headless Chrome)
+- L2 additional: <contract / rule-surface comparison: coding-result sampling / API contract assertions / semantics reconciliation>
+- L3 additional: <schema changes: execute after backup + rollback SQL are ready; runtime / pipeline only: fall back to the previous release tag + configuration-switch contingency>
+
+## 确认与复核
+> Confirmation = the user approves in one sentence in the conversation; after confirmation this plan moves `draft → approved` and this section is backfilled (the machine-visible state of the confirmation step); `done` appears only at closeout — jumping directly from `draft` to `done` is forbidden (2026-09-22 papercut).
+- Confirmation result: approved (YYYY-MM-DD confirmed in the user conversation); done (YYYY-MM-DD closeout, set together with the entry document's terminal state)
+- Confirmation-gate record: full plan draft reviewed + change list confirmed (`stages.md` Build two gates, one at a time, not merged)

package/locales/en/overrides/workflow/regression-checklist.md

@@ -0,0 +1,3 @@
+# Regression checklist
+
+> Manually maintained: critical paths and anti-recurrence verification items. New entries must link to an incident or plan.