@namewta/speculo 0.1.14 → 0.1.16

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Speculo — specification-driven development framework assets, with a CLI to install and update them across AI coding tools.",
   "type": "module",
   "bin": {

package/template/vendor/officecli/SKILL.md

@@ -0,0 +1,415 @@
+---
+name: officecli
+description: Create, analyze, proofread, and modify Office documents (.docx, .xlsx, .pptx) using the officecli CLI tool. Use when the user wants to create, inspect, check formatting, find issues, add charts, or modify Office documents.
+---
+
+# officecli
+
+AI-friendly CLI for .docx, .xlsx, .pptx. Single binary, no dependencies, no Office installation needed.
+
+## Install
+
+If `officecli` is not installed:
+
+```bash
+# macOS / Linux
+curl -fsSL https://d.officecli.ai/install.sh | bash
+
+# Windows (PowerShell)
+irm https://d.officecli.ai/install.ps1 | iex
+```
+
+Verify with `officecli --version`. If still not found after install, open a new terminal.
+
+---
+
+## Strategy
+
+**L1 (read) → L2 (DOM edit) → L3 (raw XML)**. Always prefer higher layers. Add `--json` for structured output.
+
+**Before doc work, check Specialized Skills** (bottom of this file). Fundraising decks, academic papers, financial models, dashboards, and Morph animations need their own skill loaded first — `load_skill` once, then proceed.
+
+---
+
+## Help System (IMPORTANT)
+
+**When unsure about property names, value formats, or command syntax, ALWAYS run help instead of guessing.** One help query beats guess-fail-retry loops.
+
+`officecli help` ≡ `officecli --help`, and `officecli <cmd> --help` ≡ `officecli help <cmd>` — same content.
+
+```bash
+officecli help                                  # All commands + global options + schema entry points
+officecli help docx                             # List all docx elements
+officecli help docx paragraph                   # Full schema: properties, aliases, examples, readbacks
+officecli help docx set paragraph               # Verb-filtered: only props usable with `set`
+officecli help docx paragraph --json            # Structured schema (machine-readable)
+```
+
+Format aliases: `word`→`docx`, `excel`→`xlsx`, `ppt`/`powerpoint`→`pptx`. Verbs: `add`, `set`, `get`, `query`, `remove`. MCP exposes the same schema via `{"command":"help","format":"docx","type":"paragraph"}`.
+
+---
+
+## Performance: Resident Mode
+
+**Every command auto-starts a resident on first access** (60s idle timeout) — file-lock conflicts are automatically avoided. Explicit `open`/`close` is still recommended for longer sessions (12min idle):
+```bash
+officecli open report.docx       # explicitly keep in memory
+officecli set report.docx ...    # no file I/O overhead
+officecli close report.docx      # save and release
+```
+
+Opt out of auto-start: `OFFICECLI_NO_AUTO_RESIDENT=1`.
+
+---
+
+## Quick Start
+
+**PPT:**
+```bash
+officecli create slides.pptx
+officecli add slides.pptx / --type slide --prop title="Q4 Report" --prop background=1A1A2E
+officecli add slides.pptx '/slide[1]' --type shape --prop text="Revenue grew 25%" --prop x=2cm --prop y=5cm --prop font=Arial --prop size=24 --prop color=FFFFFF
+```
+
+**Word:**
+```bash
+officecli create report.docx
+officecli add report.docx /body --type paragraph --prop text="Executive Summary" --prop style=Heading1
+officecli add report.docx /body --type paragraph --prop text="Revenue increased by 25% year-over-year."
+```
+
+**Excel:**
+```bash
+officecli create data.xlsx
+officecli set data.xlsx /Sheet1/A1 --prop value="Name" --prop bold=true
+officecli set data.xlsx /Sheet1/A2 --prop value="Alice"
+```
+
+---
+
+## L1: Create, Read & Inspect
+
+```bash
+officecli create <file>               # Create blank .docx/.xlsx/.pptx (type from extension)
+officecli view <file> <mode>          # outline | stats | issues | text | annotated | html
+officecli get <file> <path> --depth N # Get a node and its children [--json]
+officecli query <file> <selector>     # CSS-like query
+officecli validate <file>             # Validate against OpenXML schema
+```
+
+### view modes
+
+| Mode | Description | Useful flags |
+|------|-------------|-------------|
+| `outline` | Document structure | |
+| `stats` | Statistics (pages, words, shapes) | |
+| `issues` | Formatting/content/structure problems | `--type format\|content\|structure`, `--limit N` |
+| `text` | Plain text extraction | `--start N --end N`, `--max-lines N` |
+| `annotated` | Text with formatting annotations | |
+| `html` | Static HTML snapshot — same renderer as `watch`, no server needed | `--browser`, `--page N` (docx), `--start N --end N` (pptx) |
+| `screenshot` / `svg` / `pdf` / `forms` | PNG via headless browser / SVG (pptx slide) / PDF via exporter plugin / form-fields JSON via format-handler plugin | `-o`, `--screenshot-width/-height`, pptx `--grid N` |
+
+Use `view html` for one-shot snapshots (CI artifacts, archival, diffing); use `watch` when you need live refresh or browser-side click-to-select.
+
+### get
+
+Any XML path via element localName. Use `--depth N` to expand children. Add `--json` for structured output. Default text output is grep-friendly: `path (type) "text" key=val key=val ...`
+
+```bash
+officecli get report.docx '/body/p[3]' --depth 2 --json
+officecli get slides.pptx '/slide[1]' --depth 1          # list all shapes on slide 1
+officecli get data.xlsx '/Sheet1/B2' --json
+```
+
+### Stable ID Addressing
+
+Elements with stable IDs return `@attr=value` paths instead of positional indices. Prefer these in multi-step workflows — positional indices shift on insert/delete, stable IDs do not.
+
+```
+/slide[1]/shape[@id=550950021]                    # PPT shape
+/slide[1]/table[@id=1388430425]/tr[1]/tc[2]       # PPT table
+/body/p[@paraId=1A2B3C4D]                         # Word paragraph
+/comments/comment[@commentId=1]                    # Word comment
+```
+
+PPT also accepts `@name=` (e.g. `shape[@name=Title 1]`), with morph `!!` prefix awareness. Elements without stable IDs (slide, run, tr/tc, row) fall back to positional indices.
+
+### query
+
+CSS-like selectors: `[attr=value]`, `[attr!=value]`, `[attr~=text]`, `[attr>=value]`, `[attr<=value]`, `:contains("text")`, `:empty`, `:has(formula)`, `:no-alt`. Boolean `and`/`or` supported across `query`/`set`/`remove`: `cell[value>5000 or value<100]`, `cell[(type=Number or type=Date) and value>0]`. Excel row-by-column-name: `Sheet1!row[Salary>5000]`. `set` accepts selectors and Excel-native paths (parity with `get`/`query`). Bare unscoped selectors rejected on `set`/`remove`.
+
+```bash
+officecli query report.docx 'paragraph[style=Normal] > run[font!=Arial]'
+officecli query slides.pptx 'shape[fill=FF0000]'
+```
+
+---
+
+## Watch & Interactive Selection
+
+Live HTML preview that auto-refreshes on every file change. Browsers can click / shift-click / box-drag to select shapes; the CLI can read the current browser selection and act on it.
+
+```bash
+officecli watch <file> [--port N]      # Start preview server (default port 26315)
+officecli unwatch <file>               # Stop
+officecli goto <file> <path>           # Scroll watching browser(s) to element (docx: p / table / tr / tc)
+```
+
+Open the printed `http://localhost:N` URL. Click to select; shift/cmd/ctrl+click to multi-select; drag from empty space to box-select. PPT/Word use blue outline; Excel uses native-style green selection (double-click cell to edit inline; drag a chart to reposition).
+
+### `get <file> selected` — read what the user clicked
+
+```bash
+officecli get <file> selected [--json]
+```
+
+Returns DocumentNodes for whatever is currently selected. Empty result if nothing selected. Exit code != 0 if no watch is running.
+
+```bash
+# User clicks shapes in the browser, then asks "make these red"
+PATHS=$(officecli get deck.pptx selected --json | jq -r '.data.Results[].path')
+for p in $PATHS; do officecli set deck.pptx "$p" --prop fill=FF0000; done
+```
+
+### Key properties
+
+- **Selection survives file edits.** Paths use stable `@id=` form.
+- **All connected browsers share one selection.** Last-write-wins.
+- **Same-file single-watch.** A given file can have only one watch process at a time.
+- **Group shapes select as a whole.** Drilling into individual children of a group is not supported in v1.
+- **Coverage:** `.pptx` shapes/pictures/tables/charts/connectors/groups; `.docx` top-level paragraphs and tables. Inherited layout/master decorations and Word nested elements (table cells, run-level) are not addressable. **`.xlsx` does not emit `data-path`** — `mark`/`selection` on xlsx always resolve `stale=true` (v2 candidate).
+
+### Marks — edit proposals waiting for review
+
+Use `mark` when changes need human review BEFORE they hit the file. Marks live in the watch process only; a separate `set` pipeline applies accepted ones. For one-shot changes use `set` directly; for permanent file annotations use `add --type comment` (Word native).
+
+```bash
+officecli mark <file> <path> [--prop find=... color=... note=... tofix=... regex=true] [--json]
+officecli unmark <file> [--path <p> | --all] [--json]
+officecli get-marks <file> [--json]
+```
+
+Props: `find` (literal or regex when `regex=true`; raw form `find='r"[abc]"'`), `color` (hex / `rgb(...)` / 22 named whitelist), `note`, `tofix` (drives apply pipeline). **Path** must be `data-path` format from watch HTML — see subskills for full pipeline.
+
+---
+
+## L2: DOM Operations
+
+### set — modify properties
+
+```bash
+officecli set <file> <path> --prop key=value [--prop ...]
+```
+
+**Any XML attribute is settable** via element path (found via `get --depth N`) — even attributes not currently present. Without `find=`, `set` applies format to the entire element.
+
+**Value formats:**
+
+| Type | Format | Examples |
+|------|--------|---------|
+| Colors | Hex (with/without `#`), named, RGB, theme | `FF0000`, `#FF0000`, `red`, `rgb(255,0,0)`, `accent1`..`accent6` |
+| Spacing | Unit-qualified | `12pt`, `0.5cm`, `1.5x`, `150%` |
+| Dimensions | EMU or suffixed | `914400`, `2.54cm`, `1in`, `72pt`, `96px` |
+
+**Dotted-attr aliases** — `font.<attr>` forms accepted on shape/run/paragraph/table/row/cell/section/styles, e.g. `--prop font.color=red --prop font.bold=true --prop font.size=14pt`. Run `officecli help <fmt> <element>` for the full list.
+
+### find — format or replace matched text
+
+Use top-level `--find` / `--replace` on `set` (and `--find` on `query`). Legacy `--prop find=X` still works but emits a hint.
+
+```bash
+# Format matched text (auto-splits runs)
+officecli set doc.docx '/body/p[1]' --find weather --prop bold=true --prop color=red
+
+# Regex matching (regex= still a prop flag)
+officecli set doc.docx '/body/p[1]' --find '\d+%' --prop regex=true --prop color=red
+
+# Replace text (use `/` for whole-document scope)
+officecli set doc.docx / --find draft --replace final
+
+# docx: tracked Find&Replace
+officecli set doc.docx / --find draft --replace final --prop revision.author=Alice
+
+# PPT — same syntax, different paths
+officecli set slides.pptx / --find draft --replace final
+```
+
+**Path controls search scope:** `/` = whole document, `/body/p[1]` or `/slide[N]/shape[M]` = specific element, `/header[1]` / `/footer[1]` = headers/footers.
+
+**Notes:**
+- Case-sensitive by default. Case-insensitive: `--prop 'find=(?i)error' --prop regex=true`
+- Matches work across run boundaries
+- No match = silent success. `--json` includes `"matched": N`
+- **Excel:** only `find` + `replace` supported (no find + format props)
+
+### add — add elements or clone
+
+```bash
+officecli add <file> <parent> --type <type> [--prop ...]
+officecli add <file> <parent> --type <type> --after <path> [--prop ...]   # insert after anchor
+officecli add <file> <parent> --type <type> --before <path> [--prop ...]  # insert before anchor
+officecli add <file> <parent> --type <type> --index N [--prop ...]        # 0-based position (legacy)
+officecli add <file> <parent> --from <path>                               # clone existing element
+```
+
+`--after`, `--before`, `--index` are mutually exclusive. No position flag = append to end.
+
+**Element types (with aliases):**
+
+| Format | Types |
+|--------|-------|
+| **pptx** | slide (incl. hidden), shape (font.latin/ea/cs, direction=rtl, underline.color, highlight=COLOR (Add/Set/Get/HTML preview), effective.X+effective.X.src; arrow alias for rightArrow; slideMaster/slideLayout typed add/set/remove), picture (SVG, brightness/contrast/glow/shadow, rotation, link, tooltip), chart (direction=rtl, pieOfPie, barOfPie, axisLine/gridline per-attr setters, animation+chartBuild=byCategory|bySeries, line dropLines/hiLowLines/upDownBars, anchor=x,y,w,h shorthand), table (cell direction=rtl, fill/background, built-in PowerPoint style catalogue, /col[C] get + swap/copyFrom, row/col Move/CopyFrom), row (tr), connector (from/to accept @name=, startshape/endshape SetByPath), group (link, tooltip, deep walk by get/query/add/remove), video/audio (loop, autoStart alias), equation, notes (direction=rtl, lang), comment (legacy + modern p188 threaded round-trip), animation (15 emphasis + 16 exit presets, multi-effect chains, motion-path presets, repeat/restart/autoReverse, chart animations), transition (12 p15 presets + morph/p14), paragraph (para), run, zoom, ole (preview=, full dump round-trip via add-part+raw-set), placeholder (phType=...), model3d (rotation=ax,ay,az; full dump round-trip), smartart (dump round-trip via add-part). |
+| **docx** | paragraph (direction/font.latin/ea/cs, bold.cs/italic.cs/size.cs, lang.latin/ea/cs, wordWrap, framePr.\*, tabs shorthand), run (lang slots, direction, underline.color, position half-pts, **revision.type=ins\|del\|format\|moveFrom\|moveTo + revision.action=accept\|reject** with .author/.date — `/revision[@author=X]` selector for filtered accept/reject), table (direction=rtl, hMerge, **virtual column ops**: add/remove/move/copyfrom on /body/tbl[N]/col), row (tr), cell (td), image, header/footer (direction), section (pageNumFmt full enum, direction=rtl, rtlGutter, pgBorders=box), bookmark, comment, footnote, endnote, formfield, sdt, chart, equation, field (28 types), hyperlink, style (direction, indents, pbdr, lineSpacing on Add/Set), toc, watermark, break, ole, **num/abstractNum/lvl**, **tab**, **textbox/shape** (full Add+Get; geometry, fill, line, wrap, alt, anchor, **rotation, verticalText (eaVert/vert/vert270/wordArt\*), gradient, shadow, opacity**), embedded **OLE round-trip on dump→batch**. docDefaults.rtl, autoHyphenation, `get /` exposes locale + /comments /footnotes /endnotes. `create --minimal` for raw OOXML scaffolding. |
+| **xlsx** | sheet (visible/hidden/veryHidden, print margins, printTitleRows/Cols, rightToLeft sheetView, cascade-aware rename), row (c{N}= cell-content shorthand; add accepts --from /Sheet/col[L]; formula-ref rewrite on insert), col (formula-ref rewrite, named-range follow on move), cell (type=richtext+runs, merge=range/sweep, direction=rtl, phonetic; **--shift left\|up on remove, shift=right\|down on add** — Excel UI dialog parity; formula auto-detect; OFFSET/INDIRECT in calc), chart (per-axis RTL/title, anchor=x,y,w,h, pareto), image (SVG), comment (direction=rtl), table (listobject), namedrange (definedname, volatile, `[@name=X]`; formula-body inlined at parse), pivottable (cache CoW + cross-pivot sharing, labelFilter, topN, fillDownLabels, calculatedField), sparkline, validation, autofilter, shape, textbox, CF (databar/colorscale/iconset/formulacf/cellIs/topN/aboveAverage), ole, csv. Query supports `merge`/`mergedrange`. Workbook: password. Shape selector enumerates leaves inside grpSp. |
+
+### Pivot tables (xlsx)
+
+```bash
+officecli add data.xlsx /Sheet1 --type pivottable \
+  --prop source="Sheet1!A1:E100" --prop rows=Region,Category \
+  --prop cols=Year --prop values="Sales:sum,Qty:count" \
+  --prop grandTotals=rows --prop subtotals=off --prop sort=asc
+```
+
+Key props: `rows`, `cols`, `values` (Field:func[:showDataAs]), `filters`, `source`, `position`, `layout` (compact/outline/tabular), `repeatLabels`, `blankRows`, `aggregate`, `showDataAs` (percent_of_total/row/col, running_total), `grandTotals`, `subtotals`, `sort`. Aggregators: sum, count, average, max, min, product, stdDev, stdDevp, var, varp, countNums. Date columns auto-group. Run `officecli help xlsx pivottable` for full schema.
+
+### Document-level properties (all formats)
+
+```bash
+officecli set doc.docx / --prop docDefaults.font=Arial --prop docDefaults.fontSize=11pt
+officecli set doc.docx / --prop protection=forms --prop evenAndOddHeaders=true
+officecli set data.xlsx / --prop calc.mode=manual --prop calc.refMode=r1c1
+officecli set slides.pptx / --prop defaultFont=Arial --prop show.loop=true --prop print.what=handouts
+```
+
+Run `officecli help <format> /` for all document-level properties (docDefaults, docGrid, CJK spacing, calc, print, show, theme, extended).
+
+### Sort (xlsx)
+
+```bash
+officecli set data.xlsx /Sheet1 --prop sort="C desc" --prop sortHeader=true
+officecli set data.xlsx '/Sheet1/A1:D100' --prop sort="A asc" --prop sortHeader=true
+```
+
+Format: `COL DIR[, COL DIR ...]`. Rejects ranges with merged cells or formulas. Sidecar metadata (hyperlinks, comments, conditional formatting, drawings) follows rows automatically.
+
+### Text-anchored insert (`--after find:X` / `--before find:X`)
+
+Locate an insertion point by text match within a paragraph. Inline types (run, picture, hyperlink) insert within the paragraph; block types (table, paragraph) auto-split it. PPT only supports inline.
+
+```bash
+# Word: inline run after matched text
+officecli add doc.docx '/body/p[1]' --type run --after find:weather --prop text=" (sunny)"
+
+# Word: block table after matched text (auto-splits paragraph)
+officecli add doc.docx '/body/p[1]' --type table --after "find:First sentence." --prop rows=2 --prop cols=2
+```
+
+### Clone
+
+`officecli add <file> / --from '/slide[1]'` — copies with all cross-part relationships.
+
+### move, swap, remove
+
+```bash
+officecli move <file> <path> [--to <parent>] [--index N] [--after <path>] [--before <path>]
+officecli swap <file> <path1> <path2>
+officecli remove <file> '/body/p[4]'
+```
+
+When using `--after` or `--before`, `--to` can be omitted — the target container is inferred from the anchor.
+
+### batch — multiple operations in one save cycle
+
+Continues on error by default (returns exit 1 if any item fails). Use `--stop-on-error` to abort on the first failure. `--force` is the docx-protection bypass.
+
+`officecli dump <file> [<path>]` emits a replayable batch JSON for round-trip — `.docx` (full coverage) and `.pptx` (text/tables/pictures/charts/notes/theme + OLE/3D/video/audio/SmartArt/morph/p15 transitions via raw-set passthrough). Path defaults to `/` (whole document); pass a subtree path (`/body`, `/body/p[N]`, `/body/tbl[N]`, `/theme`, `/settings`, `/numbering`, `/styles`) to scope the dump. `officecli refresh <file.docx>` recalculates TOC page numbers / PAGE / cross-references after replay (Word backend on Windows; headless-HTML fallback elsewhere). `officecli plugins list` extends support to `.doc`, `.hwpx`, `.pdf` export.
+
+```bash
+echo '[
+  {"command":"set","path":"/Sheet1/A1","props":{"value":"Name","bold":"true"}},
+  {"command":"set","path":"/Sheet1/B1","props":{"value":"Score","bold":"true"}}
+]' | officecli batch data.xlsx --json
+
+officecli batch data.xlsx --commands '[{"op":"set","path":"/Sheet1/A1","props":{"value":"Done"}}]' --json
+officecli batch data.xlsx --input updates.json --force --json
+```
+
+Supports: `add`, `set`, `get`, `query`, `remove`, `move`, `swap`, `view`, `raw`, `raw-set`, `validate`. Fields: `command` (or `op`), `path`, `parent`, `type`, `from`, `to`, `index`, `after`, `before`, `props`, `selector`, `mode`, `depth`, `part`, `xpath`, `action`, `xml`.
+
+---
+
+## L3: Raw XML
+
+Use when L2 cannot express what you need. No xmlns declarations needed — prefixes auto-registered.
+
+```bash
+officecli raw <file> <part>                          # view raw XML
+officecli raw-set <file> <part> --xpath "..." --action replace --xml '<w:p>...</w:p>'
+officecli add-part <file> <parent>                   # create new document part (returns rId)
+```
+
+`raw-set` actions: `append`, `prepend`, `insertbefore`, `insertafter`, `replace`, `remove`, `setattr`. Run `officecli help <format> raw` for available parts.
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Correct Approach |
+|---------|-----------------|
+| `--name "foo"` | Use `--prop name="foo"` — all attributes go through `--prop` |
+| Unquoted `[N]` paths in zsh/bash | Always quote: `'/slide[1]'` or `"/slide[1]"` (shell glob-expands brackets) |
+| PPT `shape[1]` for content | `shape[1]` is typically the title placeholder. Use `shape[2]+` for content shapes |
+| `/shape[myname]` | Name indexing not supported. Use numeric index or `@name=` (PPT only) |
+| Guessing property names | Run `officecli help <format> <element>` to see exact names |
+| Modifying an open file | Close the file in PowerPoint/WPS first |
+| `\n` in shell strings | Use `\\n` for newlines in `--prop text="..."` |
+| `$` in shell text | `--prop text="$15M"` strips `$15`. Use single quotes: `--prop text='$15M'`, or heredoc batch |
+
+---
+
+## Specialized Skills
+
+`officecli load_skill <name>` — output is a SKILL.md, follow its rules.
+
+**Loading rule**:
+- Pick the most specific match in "When to use"; if none fits, load the format default (`word` / `pptx` / `excel`).
+- Scenes already contain the format default's rules — load **one** skill per artifact, never stack.
+- Loaded rules persist across turns; don't re-load each reply.
+- Two distinct artifacts → two separate loads.
+
+### Word (.docx)
+
+| Name | When to use |
+|------|-------------|
+| `word` | Reports, letters, memos, proposals, generic documents |
+| `academic-paper` | Journal / conference / thesis: APA / Chicago / IEEE / MLA citations, equations, SEQ + PAGEREF cross-refs, multi-column journal layout, bibliography. NOT for business reports or letters (route those to `word`) |
+
+### PowerPoint (.pptx)
+
+| Name | When to use |
+|------|-------------|
+| `pptx` | Generic decks: board reviews, sales decks, all-hands, product launches |
+| `pitch-deck` | **Fundraising only** — seed / Series A-C / SAFE / convertible / strategic raise. NOT for sales / product / board decks (route those to `pptx`) |
+| `morph-ppt` | Cinematic Morph-animated presentations. NOT for static decks (route those to `pptx`) |
+| `morph-ppt-3d` | 3D Morph: GLB models, camera moves, depth. NOT for 2D-only Morph (route those to `morph-ppt`) |
+
+### Excel (.xlsx)
+
+| Name | When to use |
+|------|-------------|
+| `excel` | Generic workbooks, formulas, pivots, trackers |
+| `financial-model` | Financial models, scenarios, projections. NOT for general data analysis (route those to `excel`) |
+| `data-dashboard` | CSV/tabular data → KPI / analytics / executive dashboards with charts and sparklines. NOT for raw data tracking (route those to `excel`) |
+
+Example: a fundraising deck task → `officecli load_skill pitch-deck` → use the printed rules.
+
+---
+
+## Notes
+
+- Paths are **1-based** (XPath convention): `'/body/p[3]'` = third paragraph
+- `--index` is **0-based** (array convention): `--index 0` = first position
+- **Excel exception**: for `add --type row` and `add --type col`, `--index N` is **1-based** (matches OOXML RowIndex / column letter index). `--index 5` inserts at row 5 / column 5.
+- After modifications, verify with `validate` and/or `view issues`
+- **When unsure**, run `officecli help <format> <element>` instead of guessing

package/template/workflows/dev/I-to-issues/I-to-issues.md

@@ -14,6 +14,21 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 
 使用垂直切片（示踪弹）将计划、规格或 PRD 分解为可独立接手的 issue。
 
+### 铁律
+
+```
+没有精确到文件路径的改动清单，不算垂直切片
+```
+
+每个切片必须指名要读哪些文件、要改哪些文件、改动什么内容。笼统描述（"改一下登录"）不是切片。
+
+### 内置文档
+
+本工作流入口自带以下配套文档，在对应阶段读取：
+
+- `issues-slices.md` — 进行实际切片分解时读取；含有完整结构规范（8 段 slices.md）、独立进入时的深度搜索协议（三轮自采集）、存疑时的提问协议（决策树）
+- `../_templates/issues-slices-template.md` — 写 `slices.md` 时作为骨架填写；头部 blockquote 标注了服务工作流与产物文件名，每个 `[TODO:]` 对应结构规范中的一段
+
 ### 输入
 
 - PRD、计划、设计记录、bug 诊断结论或当前对话上下文
@@ -40,14 +55,18 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 
 ### 切片计划质量准则
 
-`slices.md` 不是清单，而是一份可被下游直接接手的**切片计划**。借鉴高质量 plan 的纪律：
+`slices.md` 不是清单，而是一份可被下游直接接手的**切片计划**。借鉴高质量 plan 的纪律（参考 TASK plan 的六段结构：当前现状 → 需读文件 → 需改文件 → 数据库表 → 实现要点 → 关键决策）：
 
-- **Context 先行**：先写清*为什么*、**已确认决策**（范围拍板，防下游重新扯皮）与**关键核实结论**（探索得到的事实），再展开切片。
+- **Context 先行**：先写清*为什么*、**已确认决策**（范围拍板，防下游重新扯皮）、**当前现状**（现有实现与需求的差距，精确到文件路径+行号）与**关键核实结论**（探索得到的事实），再展开切片。——映射 slices.md §0
+- **文件级精准**：每个切片须指名**需阅读的文件**（\| 文件 \| 目的 \|）和**需修改的文件**（\| 文件 \| 改动内容 \|，新增标 **新增**，重构标 **重度重构**），杜绝笼统描述。——映射 slices.md §3 切片条目
+- **数据库变更可追溯**：涉及 schema 变更时，用「涉及的数据库表」表记录每张表的变更（新建/新增字段/语义调整），DDL 注明 sql 文件和追加位置。——映射 slices.md §2.5
+- **实现要点前置**：每个切片列出关键实现要点（算法细节、并发控制、兜底策略），让执行者拿到切片就知道怎么下手。——映射 slices.md §3 切片条目
 - **存疑即问**：方案有未决分支时，按本工作流「存疑时的提问协议」用 `AskUserQuestion` 一次一问、带推荐、逐步锁定，不臆测。
 - **行号现场核对**：引用的行号/路径均为*近似*，实施时以现场代码为准；在计划内写明这一点，避免下游照搬过期行号。
 - **保留/不动同等重要**：每个切片既写「改什么」，也写「**保留/不动什么**」——告诉执行者哪些不能碰。
-- **验证分层**：删除型切片的验收须含残留扫描（grep 0 命中）；change 级验证总览走真实运行的冒烟与（如涉及）迁移测试。
+- **验证分层**：删除型切片的验收须含残留扫描（grep 0 命中）；change 级验证总览走真实运行的冒烟与（如涉及）迁移测试。——映射 slices.md §8
 - **复用优先于新造**：能复用就不新建，在切片「复用」字段与 §1 REUSE 列显式记录。
+- **关键决策收口**：跨切片的技术选型与取舍汇总到「关键决策」段，防止下游对同一问题反复争论。——映射 slices.md §5.5
 - **重型小节按需**：风险登记、退役清单、架构上下文是条件段——复杂 change 铺开，单文件小改可省。
 
 ### 独立使用
@@ -56,19 +75,9 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 
 **独立进入流程：**
 
-1. **change 目录**：若用户未指定 `<change>` 目录，按 `YYYY-MM-DD-<kebab-name>` 格式创建（如 `2026-06-17-refactor-auth`），初始化 `.status.json` 并更新 `dev-status.json`。
-2. **信息自采集**：若同 change 目录下无上游产物（PRD、decision-log、diagnosis 等），**自行通过代码库探索采集切片所需上下文**，不要求用户先执行其他工作流：
-   - 探索项目目录结构，建立模块心智模型（`src/`、`core/`、`tests/` 等）
-   - 读取 `AGENTS.md`、`README.md`、`CONTRIBUTING.md` 了解项目规范与架构约定
-   - `git log --oneline -30` 了解近期变更趋势和相关模块
-   - 搜索相关代码区域的注释、TODO、FIXME 和现有 issue 引用
-   - 读取 `speculo/.speculo/.config/RULES.md` 和 `speculo/.speculo/.config/adr/` 了解项目决策
-3. **深度搜索**：信息仍不足时，执行以下顺序的深度探寻：
-   - 搜索项目中与用户意图关键词匹配的代码、注释和文档
-   - 追溯相关模块的 git history（`git log -p -- <path>`）
-   - 搜索 `speculo/.speculo/doc/` 和 `speculo/.speculo/archive/` 中已有的领域文档
-   - 检查现有测试文件了解模块契约和边界行为
-4. **存疑即问**：仅在代码库探索无法确定的决策分支上，按「存疑时的提问协议」使用 `AskUserQuestion` 一次一问、带推荐、逐步锁定。
+1. **change 目录**：若用户未指定 `<change>` 目录，按「缺少 change 目录时的自初始化」创建。
+2. **信息自采集**：若同 change 目录下无上游产物（PRD、decision-log、diagnosis 等），按 `issues-slices.md` 的「独立进入时的深度搜索协议」（三轮：全景扫描 → 领域上下文采集 → 锁定未决分支）自行采集切片所需上下文，不要求用户先执行其他工作流。
+3. **存疑即问**：仅在代码库探索无法确定的决策分支上，按「存疑时的提问协议」使用 `AskUserQuestion` 一次一问、带推荐、逐步锁定。
 
 ### 缺少 change 目录时的自初始化
 
@@ -99,9 +108,11 @@ keywords: [issues, slices, vertical, AFK, HITL, 切片]
 - 模板：`../_templates/issues-slices-template.md`
 - 产物：`slices.md`
 - 完成准则：
-  - §0 战略与背景含**已确认决策**与**关键核实结论**（独立进入时自采集，有上游则继承）
-  - 每个切片都有标题、类型、依赖、覆盖来源、验收切片；删除型切片标注**保留/不动**
+  - §0 战略与背景含**已确认决策**、**当前现状**与**关键核实结论**（独立进入时自采集，有上游则继承）
+  - 每个切片都有标题、类型、依赖、覆盖来源、**需阅读/需修改文件表**、**实现要点**、验收切片；删除型切片标注**保留/不动**
   - 已确认粒度、依赖和 HITL/AFK 标记
+  - 涉及 schema 变更时 §2.5 数据库表已填写
+  - §5.5 关键决策已汇总跨切片技术选型
   - §8 验证总览存在（静态 → 残留扫描 → 冒烟，按适用项）
   - `slices.md` 无残留 `[TODO:]`
 

package/template/workflows/dev/I-to-issues/issues-slices.md

@@ -49,14 +49,15 @@
 ## `slices.md` 结构规范
 
 `issues-slices-template.md` 提供模板骨架；AI 填写时按下述结构展开。`[必填]` 段每份都要，`[条件]` 段有则填、单文件小改可省。
-> 最小形态（单文件小改）：§0(简) + §1 + §3(单切片) + §5 + §8。复杂 change：全段铺开。
+> 最小形态（单文件小改）：§0(简) + §1 + §3(单切片) + §5 + §8。复杂 change：全段铺开（含 §2.5 数据库表、§5.5 关键决策、切片内文件表和实现要点）。
 
 ### 0. 战略与背景（Context）—— [必填]
 
-本段是整份切片计划的决策锚点，含四块：
+本段是整份切片计划的决策锚点，含五块：
 
 - **一句话战略**：单句概括「做什么 + 为什么 + 怎么做到（以现有系统为基底 / 新建 / 复用）」。
 - **已确认决策**：逐条列出与用户拍板的范围/取舍决策，防止下游重新扯皮。**有 `decision-log.md` 则继承其「已确认决策」段；独立进入（无上游）时在此自采集**。
+- **当前现状**：逐条列出与需求不符的现有实现、缺失的能力或待修复的问题。每条含：`文件路径:行号范围` + 当前值/行为 + 为什么不满足需求。独立进入时从代码库探索采集；有上游 PRD 或 diagnosis 则继承其发现。格式示例：`RegexConstants.PASSWORD` 为正则 `^(?=.*[a-z])...`（要求四类全含）——与需求「至少三类」不符。
 - **关键核实结论**：探索阶段确认的事实（依赖关系、唯一调用点、可删/须留边界等）。**必须显式写明「行号为近似、实施时以现场代码为准」**，避免下游照搬过期行号。
 - **预期产出**：1–2 句描述本 change 完成后的可观察结果。
 
@@ -79,6 +80,21 @@
 
 单文件修复或热点 patch 可省略本节。
 
+### 2.5. 涉及的数据库表 —— [条件]
+
+若 change 涉及数据库 schema 变更（新建表、新增字段、字段语义调整），用三列表格记录：
+
+| 表 | 变更 |
+|----|------|
+
+变更描述规则：
+- **新建**表：列出全部字段名 + 类型 + PRIMARY KEY + UNIQUE KEY + INDEX，注明建表 DDL 追加到哪个 sql 文件末尾
+- **新增**字段：`字段名 类型 DEFAULT 默认值 COMMENT '注释'`，注明 ALTER TABLE 追加到哪个 sql 文件末尾
+- **字段语义调整**：`旧字段名 → 新语义`（不变更数据库结构，仅改代码层注释/映射）
+- **无结构变更**：纯逻辑变更（如增加唯一性校验）不产生 DDL，在此注明即可
+
+> SQL 追加原则：所有 DDL 变更追加到对应 sql 文件末尾，遵循只追加不修改原则。
+
 ### 3. 切片（slices）—— [必填]
 
 每个切片是**一个从数据到 UI 的端到端闭环**（窄而完整）。切片按依赖顺序排列；每个切片包含：
@@ -90,9 +106,12 @@
 - **类型：** `AFK` | `HITL`
 - **阻塞于：** 切片 M（或「无」）
 - **覆盖：** PRD 章节 / US 编号 / 用户故事简述
+- **需阅读的文件：** 实现本切片前需理解的现有代码（| 文件 | 目的 | 表）；单文件小改可省略
 - **交付物：** 该切片产出的具体文件/模块/功能清单
+- **需修改的文件：** 本切片要改动的文件（| 文件 | 改动内容 | 表）；新增文件标 **新增**，重度重构标 **重度重构**
 - **保留/不动：** 本切片**不能碰**的代码/契约/数据（如冻结常量、共享依赖、邻近功能）；无则写「无」
 - **复用：** 复用哪些现有能力（模块/文件/命令）
+- **实现要点：** 关键技术决策、算法细节、并发控制、兜底策略（编号列表）；单文件小改可省略
 - **验收切片：** 一个可独立执行的验证命令或手动检查步骤，证明本切片完成；**删除型切片须含残留扫描**（如 `grep -rn "<符号>" <范围>` 应 0 命中）
 - **对齐：** PRD FR-xxx 或 issue 引用
 - **ADR 引用：** （可选）关联的工程层 ADR 编号
@@ -100,7 +119,8 @@
 
 - `<phase id="...">` 是稳定的阶段标识（如 `phase0-node-base`、`phase1-templates`），供 `dev/03` TDD 工作流引用。单阶段 change 用 `phase0-<slug>`。
 - `status` 枚举：`未开始`（切片创建时） → `已实现`（TDD finish 置入） → `已验证`（finalize 置入）。状态只前进不回退。
-- 切片改动面较宽时，可在「交付物」下用 `| 文件 | 改动 |` 表逐文件列出（新增/修改/删除/**保留**），提升信息密度。
+- **需阅读/需修改的文件表**：借鉴高质量 plan 的双表模式——读文件表让执行者知道上下文边界，改文件表让执行者知道改动面和操作类型（新增/修改/重构）。单文件小改的切片可省略读文件表。
+- **实现要点**：每个切片列出 3-7 条关键技术点，让执行者拿到切片就知道怎么下手。包含算法细节、并发控制、兼容/兜底策略等。
 
 ### 4. 横切关注点与铁律（贯穿所有切片）—— [必填]
 
@@ -155,15 +175,17 @@ change 级验证 roll-up，补足每切片「验收切片」的整体闭环（
 ## 填写引导
 
 1. 遵循 `I-to-issues.md` 的内置切片指引与「切片计划质量准则」，以及本文件的结构规范。
-2. **写 Context（§0）**：提炼一句话战略；**采集或继承已确认决策**（有 `decision-log.md` 则继承）与**关键核实结论**（写明行号为近似、现场核对）；点明预期产出。未决分支按「存疑时的提问协议」逐一锁定。
+2. **写 Context（§0）**：提炼一句话战略；**采集或继承已确认决策**（有 `decision-log.md` 则继承）；**梳理当前现状**（逐条记录与需求不符的现有实现，精确到文件路径+行号）；**记录关键核实结论**（写明行号为近似、现场核对）；点明预期产出。未决分支按「存疑时的提问协议」逐一锁定。
 3. **采集范围**：从 PRD / decision-log / diagnosis / 用户指令中提取 IN/REUSE/OUT 三列、架构上下文和 ADR 引用；不确定的标记 `[待确认]`。
-4. **切分垂直切片**：优先窄而完整、优先 AFK；每个切片必须有用户可独立验证的「验收切片」，并标注**保留/不动**；删除型切片在验收里配残留扫描。
-5. **标注 phase id**：为每个切片生成稳定的 `<phase id="...">` 标识（kebab-case），供 TDD 阶段直接引用。
-6. **填条件段**：涉及删除 / 迁移 / 外部副作用时补 §6 风险与回滚、§7 退役清单；多模块时补 §2 架构上下文。
-7. **收口验证（§8）**：列出静态 / 测试 / 残留扫描 / E2E / 迁移的整体验证项。
-8. 用编号列表向用户确认粒度、依赖、HITL/AFK 标记、phase id 和是否需要发布外部 issue。
-9. 按依赖顺序记录切片；发布外部 issue 时也按依赖顺序发布。
-10. 迭代直到用户批准分解；未批准前不发布外部 issue。
+4. **记录数据库变更（§2.5）**：涉及 schema 变更时，用「涉及的数据库表」表记录每张表的变更（新建/新增字段/语义调整），DDL 注明 sql 文件和追加位置。
+5. **切分垂直切片（§3）**：优先窄而完整、优先 AFK；每个切片必须写明**需阅读的文件**（\| 文件 \| 目的 \|）、**需修改的文件**（\| 文件 \| 改动内容 \|，新增标 **新增**，重构标 **重度重构**）、**实现要点**（编号列表）、用户可独立验证的「验收切片」，并标注**保留/不动**；删除型切片在验收里配残留扫描。
+6. **标注 phase id**：为每个切片生成稳定的 `<phase id="...">` 标识（kebab-case），供 TDD 阶段直接引用。
+7. **填条件段**：涉及删除 / 迁移 / 外部副作用时补 §6 风险与回滚、§7 退役清单；多模块时补 §2 架构上下文。
+8. **汇总关键决策（§5.5）**：将跨切片的技术选型与取舍写入「关键决策」段（方案选择、字段复用/新建决策、SQL 追加规则等），防止下游反复争论。
+9. **收口验证（§8）**：列出静态 / 测试 / 残留扫描 / E2E / 迁移的整体验证项。
+10. 用编号列表向用户确认粒度、依赖、HITL/AFK 标记、phase id 和是否需要发布外部 issue。
+11. 按依赖顺序记录切片；发布外部 issue 时也按依赖顺序发布。
+12. 迭代直到用户批准分解；未批准前不发布外部 issue。
 
 ## 边界
 
@@ -176,10 +198,12 @@ change 级验证 roll-up，补足每切片「验收切片」的整体闭环（
 ## 完成准则
 
 - `slices.md` 无残留 `[TODO:]`
-- §0 战略与背景含已确认决策与关键核实结论（独立进入时自采集，有上游则继承）
+- §0 战略与背景含已确认决策、**当前现状**与关键核实结论（独立进入时自采集，有上游则继承）
 - 存疑点已按「存疑时的提问协议」逐一与用户锁定，或显式标记 `[待确认]`
-- 每个切片都有 `<phase id="...">` 标识、类型、依赖、覆盖来源、验收切片；删除型切片标注保留/不动且验收含残留扫描
+- 每个切片都有 `<phase id="...">` 标识、类型、依赖、覆盖来源、**需阅读/需修改文件表**、**实现要点**、验收切片；删除型切片标注保留/不动且验收含残留扫描
 - IN/REUSE/OUT 表格完整（无法确定时标 `[待确认]` 并已获用户补充）
+- 涉及 schema 变更时 §2.5 数据库表已填写（表名、变更类型、DDL 位置）
+- §5.5 关键决策已汇总跨切片技术选型与取舍
 - §8 验证总览存在（静态 / 残留扫描 / 冒烟按适用项填）
-- 适用时已填条件段（§2 架构 / §6 风险 / §7 退役）
+- 适用时已填条件段（§2 架构 / §2.5 数据库表 / §5.5 关键决策 / §6 风险 / §7 退役）
 - `.status.json` 已记录 `slice_count`、`hitl_slice_count` 和 `issue_tracker_mode`

package/template/workflows/dev/_templates/issues-slices-template.md

@@ -1,11 +1,12 @@
 > **服务工作流：** `../I-to-issues/I-to-issues.md`
 > **产物文件名：** `slices.md`
 > **父目录规则：** 本模板产物写入 `YYYY-MM-DD-<kebab-name>/` change 目录内
+> **填写纪律：** 本模板遵循六段高质量 plan 纪律——当前现状 → 需读文件 → 需改文件 → 数据库表 → 实现要点 → 关键决策；标「条件段」的小节按需填写，单文件小改的最小形态为 §0(简) + §1 + §3(单切片) + §5 + §8。
 
 # 切片计划（Vertical Slices）
 
-> 本文件是一份可被下游直接接手的切片计划：以厚 Context（已确认决策 + 关键核实结论）开篇，
-> 按依赖排序的切片展开，每切片标注保留/不动，并以分层验证收口。
+> 本文件是一份可被下游直接接手的切片计划：以厚 Context（已确认决策 + 当前现状 + 关键核实结论）开篇，
+> 按依赖排序的切片展开，每切片标注需读/需改文件、实现要点与保留/不动，并以分层验证收口。
 > 每个切片有 `<phase id="...">` 标识，供 TDD 工作流直接引用。
 > 标「条件段」的小节按需填写；单文件小改的最小形态为 §0(简) + §1 + §3(单切片) + §5 + §8。
 
@@ -13,6 +14,7 @@
 
 - **一句话战略：** [TODO: 做什么 + 为什么 + 怎么做到（新建 / 复用 / 以现有系统为基底）。]
 - **已确认决策：** [TODO: 逐条列出与用户拍板的范围/取舍决策；有 decision-log.md 则继承其「已确认决策」段。]
+- **当前现状：** [TODO: 逐条列出与需求不符的现有实现——文件路径:行号 + 当前值/行为 + 为什么不满足需求；独立进入时从代码库探索采集。]
 - **关键核实结论：** [TODO: 探索确认的事实（依赖 / 唯一调用点 / 可删须留边界）。注明：行号为近似，实施时以现场代码为准。]
 - **预期产出：** [TODO: 1–2 句，本 change 完成后的可观察结果。]
 
@@ -26,6 +28,13 @@
 ## 2. 架构上下文
 [TODO: 条件段——涉及的模块与职责分工、新增模块定位、不可逾越约束；可附 ASCII 分层图与依赖方向。单文件修复可删除本节。]
 
+## 2.5. 涉及的数据库表
+[TODO: 条件段——若涉及 schema 变更，用 | 表 | 变更 | 表记录：
+- 新建表：列出全部字段 + PK + UK + INDEX，注明 DDL 追加到哪个 sql 文件末尾
+- 新增字段：字段名 类型 DEFAULT 默认值 COMMENT '注释'，注明 ALTER TABLE 追加位置
+- 字段语义调整：旧字段名 → 新语义（不变更结构）
+- 无 schema 变更则删除本节]
+
 ## 3. 切片
 
 ### 切片 1 · [切片名称]
@@ -34,9 +43,12 @@
 - **类型：** AFK | HITL
 - **阻塞于：** 无
 - **覆盖：** [TODO: PRD 章节 / US 编号 / 用户故事]
+- **需阅读的文件：** [TODO: | 文件 | 目的 |；单文件小改可省略]
 - **交付物：** [TODO: 具体文件/模块/功能；改动面宽时可用 | 文件 | 改动 | 表逐文件列出]
+- **需修改的文件：** [TODO: | 文件 | 改动内容 |；新增文件标 **新增**，重度重构标 **重度重构**]
 - **保留/不动：** [TODO: 本切片不能碰的代码/契约/数据；无则写「无」]
 - **复用：** [TODO: 复用哪些现有能力]
+- **实现要点：** [TODO: 关键技术决策、算法细节、并发控制、兜底策略（编号列表）；单文件小改可省略]
 - **验收切片：** [TODO: 可独立执行的验证命令或步骤；删除型须含残留扫描 grep 0 命中]
 - **对齐：** [TODO: PRD FR-xxx 或 issue 引用]
 - **ADR 引用：** [TODO: 关联的 ADR 编号，可选]
@@ -47,9 +59,12 @@
 - **类型：** AFK | HITL
 - **阻塞于：** 切片 1
 - **覆盖：** [TODO]
+- **需阅读的文件：** [TODO: | 文件 | 目的 |；单文件小改可省略]
 - **交付物：** [TODO]
+- **需修改的文件：** [TODO: | 文件 | 改动内容 |]
 - **保留/不动：** [TODO]
 - **复用：** [TODO]
+- **实现要点：** [TODO]
 - **验收切片：** [TODO]
 - **对齐：** [TODO]
 - **ADR 引用：** [TODO]
@@ -67,6 +82,9 @@ P1  phase1-xxx  切片名称  依赖 P0
 ]
 ```
 
+## 5.5. 关键决策
+[TODO: 汇总影响全局或跨切片的技术选型与取舍，如方案选择（工具类 vs 正则）、字段复用/新建决策、SQL 追加规则等。防止下游对同一问题反复争论。单文件小改可删除本节。]
+
 ## 6. 风险与回滚
 [TODO: 条件段——本期涉及删除/数据迁移/外部副作用/高耦合时填：风险 / 触发条件 / 缓解 / 回滚 表；有 prd-overview.md 风险则继承细化。纯增量小改可删除本节。]