create-yss-spec 2.1.10 → 2.1.13

package/template/.cursor/skills/implementation-repo-onboarding/SKILL.md

@@ -0,0 +1,50 @@
+---
+name: implementation-repo-onboarding
+description: Use when connecting an existing frontend, backend, fullstack, or other implementation Git repository to this Harness repository.
+---
+
+# Implementation Repo Onboarding
+
+用于把已有前端、后端或其他实现仓库接入当前 Harness / 研发管理仓库。默认只做只读扫描和文档记录，不改实现仓库。
+
+## Inputs
+
+- 外部仓库 URL 或本地路径。
+- `repo_role`: backend / frontend / fullstack / other。
+- 目标 feature / change 名称。
+- 可选：默认分支、CI 平台、验证命令、OpenAPI 位置。
+
+## Workflow
+
+1. 确认当前仓库是 Harness 仓库，读取 `docs/process/implementation-repo-integration.md`。
+2. 如果输入是本地路径，只读检查 Git remote、当前分支、目录结构、构建文件和测试脚本。
+3. 如果输入是远端 URL，优先使用只读 Git 查询；需要 clone 时只能 clone 到临时目录，不能 clone 到 Harness 仓库内。
+4. 识别技术栈、包管理器、CI、测试命令、构建命令、OpenAPI 接入和设计 token 接入。
+5. 判定实现位置：Harness 内只能使用 `apps/backend/<project>/` 或 `apps/frontend/<project>/`；`apps/backend/`、`apps/frontend/` 仅为容器，`app/backend/`、`app/frontend/` 及其子路径必须标记为阻断。外部实现仓库记录真实项目根路径，不套用 Harness 占位路径。
+6. 按 `docs/templates/implementation-repo-registry-template.md` 输出实现仓库登记内容。
+7. 列出 `known_gaps`、人审点、fresh verification 命令和需要回写到 Harness change / Issue / checkpoint 的信息。
+
+## Baseline Checks
+
+| repo_role | 必查项 |
+|---|---|
+| backend | 构建工具、模块结构、测试命令、OpenAPI 产出、YSS DDD 基线、数据库 / 迁移红线 |
+| frontend | 包管理器、框架、路由、YSS UI / Ant Design、Orval / API client、设计 token、lint / type-check / build |
+| fullstack | 前后端边界、契约生成方式、独立测试命令、CI 阶段拆分 |
+| other | owner、构建 / 测试 / 发布命令、与 Harness change 的关系 |
+
+## Boundaries
+
+- 不直接提交、推送、创建 MR / PR 或修改实现仓库。
+- 不把实现仓库源码复制进 Harness 仓库。
+- 不把缺失命令编造为已存在；找不到时标记 `unknown` 或 `需人工确认`。
+- 不得把 `app/backend/`、`app/frontend/` 或 `apps/backend/`、`apps/frontend/` 容器根登记为可生成项目根。
+- 触碰认证、授权、SQL、迁移、加密、公共基础库 API 时标记 `TODO-HUMAN-REVIEW`。
+
+## Output
+
+- 实现仓库登记草案。
+- 工程基线发现。
+- known gaps 和补齐计划。
+- fresh verification 命令。
+- Harness 回写位置建议。

package/template/.cursor/skills/improve-codebase-architecture/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files** — monospaced list, `font-mono text-sm`.
+- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
+- **Problem** — one sentence. What hurts.
+- **Solution** — one sentence. What changes.
+- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable) — one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise — but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, leverage, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow — interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"leverage: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "it's worth noting that…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.

package/template/.cursor/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: improve-codebase-architecture
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **leverage**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
+- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan — YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then spawn a sub-agent to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and leverage, and how tests would improve
+- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it clearly in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [HTML-REPORT.md](HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, run the `/grilling` skill to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern.

package/template/.cursor/skills/improve-codebase-architecture/agents/openai.yaml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "Improve Codebase Architecture"
+  short_description: "Find and grill architecture improvements"
+policy:
+  allow_implicit_invocation: false

package/template/.cursor/skills/llm-wiki/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: llm-wiki
+description: >
+  Compile and maintain a Karpathy-pattern LLM wiki (raw + wiki + schema) with
+  init, incremental refresh, global rebuild, lint, and narrow ingest. Use when
+  the user wants a local knowledge wiki, incremental wiki refresh, wiki rebuild,
+  compiling a named research note into the wiki, `/llm-wiki`, or an answer from
+  an existing wiki.
+---
+
+# llm-wiki
+
+Compile a persistent wiki from live documents and code. The wiki is the IR; live sources are the truth. Read [schema](references/schema.md), then the matching mode file.
+
+One-off notes are out of scope. Use this skill to compile or lint a persistent wiki (`raw/` + `wiki/` + `.wiki-manifest.json`), or to answer from an existing wiki per [query.md](references/query.md).
+
+## Mode
+
+| User intent | Mode | Completion |
+|---|---|---|
+| 从零构建知识库 | `init` | 三层目录 + schema + index + log + 文章 + `.wiki-manifest.json`，lint 退出 0 |
+| 源变了，更新受影响页 | `refresh` | 只改漂移命中的文章；human-owned 不改；lint 0；log 有 REFRESH |
+| 全局按新源重编译 | `rebuild` | raw 对齐 live；稳定 ID 与 human-owned 保留；LLM 页全量重写；lint 0；log 有 REBUILD |
+| 健康检查 | `lint` | 结构脚本 exit 0 + 已跑 advise 并报告条数；对变更页做 live 源抽查 |
+| 把点名外源或已落盘 research 笔记编进 wiki | `ingest` | raw 登记 + manifest 源 + 四态候选经确认后写页；lint 0；log 有 `INGEST` |
+
+Ambiguous → ask. Existing wiki + "构建" → ask refresh vs rebuild, do not init over it.
+
+Query is not a mode. Follow [query.md](references/query.md). Query never writes and never ingests.
+
+## Layout
+
+```
+<wiki-root>/
+  raw/                  # immutable copies + labelled extracts
+  wiki/                 # articles + index.md + log.md + CLAUDE.md
+  .wiki-manifest.json   # compile graph (sources ↔ articles)
+```
+
+Scripts live in this skill's `scripts/` directory (the folder that contains this `SKILL.md`). Run them from the repo root so `--wiki` / `--repo` resolve correctly:
+
+```bash
+node <skill-root>/scripts/inventory.mjs hash --wiki <wiki-root>
+node <skill-root>/scripts/inventory.mjs status --wiki <wiki-root>
+node <skill-root>/scripts/lint-wikilinks.mjs <wiki-root>
+node <skill-root>/scripts/advise.mjs <wiki-root>
+node <skill-root>/scripts/extract.mjs skill-names --in <live-lock.json> --out <wiki-root>/<rawPath>
+```
+
+`status` is a stable alias of `drift`. `<skill-root>` is the canonical skill directory or a projection that points at it. Do not hard-code `.agents/skills/llm-wiki`.
+
+## Steps
+
+1. Detect: `wiki/index.md` + `CLAUDE.md` (or `AGENTS.md`) means a wiki exists.
+2. If the user is asking a repository question, load [query.md](references/query.md) and stop. Do not lint, ingest, or append `log.md`.
+3. Load the mode algorithm: [compile.md](references/compile.md) for init/refresh/rebuild, [ingest.md](references/ingest.md) for ingest. For init/rebuild corpus choice, load [discover.md](discover.md). For writing, load [writing.md](references/writing.md). For checks, load [lint.md](references/lint.md).
+4. **Fact order:** called code > table comments / config defaults > stale raw copies. After writing, re-read live sources for a sample of claims (`N = min(5, changed pages)`).
+5. Run structural lint and advise. Append `log.md`. Stop.
+
+`refresh` without a manifest: stop. Rebuild, or reconstruct the manifest from existing「来源」sections — do not guess `sourceIds`.

package/template/.cursor/skills/llm-wiki/assets/CLAUDE.md.template

@@ -0,0 +1,26 @@
+# CLAUDE.md — Wiki schema
+
+本文档是本 wiki 的 schema（结构契约）。正文语言遵循宿主项目的文档语言规则；英文专有名词、类名、枚举值、表名与 API 路径保持原样。
+
+## 三层结构
+
+- **`raw/`** — 不可变原始源。从 live 文档拷贝，或从 live 源提取且标明出处的派生摘要。只读，不靠改 raw 来「修正」事实。
+- **文章（`wiki/*.md`）** — LLM 生成的知识文章。文件名（不含 `.md`）即文章 ID，必须全局唯一。使用 `[[wikilink]]` 互引。
+- **`index.md`** — 内容目录。`##` 节标题定义分类；节下列出该分类下的 `[[wikilink]]`。
+
+## 文章写作约定
+
+- 首行为 `# H1`，随后紧跟首段摘要。
+- 正文使用 `[[目标文章名]]`；目标必须是本 wiki 内存在的文章文件名（不含 `.md`）。
+- 论断必须能追溯到 `raw/` 或 live 代码路径。文末使用 `## 来源`。
+- 分类归属由 `index.md` 决定。
+- 可选 frontmatter：`human-owned: true` 时 refresh / rebuild 不得重写正文。
+- 仅当多个来源冲突，或 live 与旧 raw 不一致时写可选 `## Status`（`Disputed` / `Outdated`）。单一 live 正确则不写。
+
+## 基础设施文件
+
+`index.md`、`log.md`、`CLAUDE.md`、`AGENTS.md`、`soul.md`、`concept-table.md` 为基础设施文件，不视为文章。
+
+## 操作日志
+
+`log.md` 只追加。格式：`## [YYYY-MM-DD] OPERATION | 描述`（CREATE / UPDATE / LINK / FIX / REFRESH / REBUILD / RETIRE / LINT / INGEST）。

package/template/.cursor/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/CLAUDE.md

@@ -0,0 +1,3 @@
+# CLAUDE.md
+
+fixture schema

package/template/.cursor/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/index.md

@@ -0,0 +1,5 @@
+# broken fixture
+
+## 分类
+
+- [[存在的页]]

package/template/.cursor/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/log.md

@@ -0,0 +1 @@
+# 操作日志

package/template/.cursor/skills/llm-wiki/assets/fixtures/broken-wiki/wiki//345/255/230/345/234/250/347/232/204/351/241/265.md

@@ -0,0 +1,7 @@
+# 存在的页
+
+摘要。引用了 [[不存在的页]]。
+
+## 来源
+
+- fixture

package/template/.cursor/skills/llm-wiki/references/compile.md

@@ -0,0 +1,126 @@
+# Compile modes
+
+Manifest schema is the incremental-compile graph. The agent fills `id`, `kind`, `livePath`, `rawPath`, `role`, `extract` (derived only), `articles`. Scripts fill `sha256`, `compiledAt`, `gitCommit`.
+
+## Manifest
+
+Path: `<wiki-root>/.wiki-manifest.json`
+
+```json
+{
+  "schemaVersion": 1,
+  "wikiRoot": "wiki/example",
+  "compiledAt": "ISO-8601",
+  "gitCommit": "hex or empty",
+  "profile": "mixed",
+  "sources": [
+    {
+      "id": "schema.sql",
+      "kind": "document",
+      "livePath": "apps/.../schema.sql",
+      "rawPath": "raw/schema.sql",
+      "sha256": "...",
+      "role": "copy"
+    },
+    {
+      "id": "skills-lock.json",
+      "kind": "derived",
+      "livePath": "skills-lock.json",
+      "rawPath": "raw/skills-lock-names.md",
+      "role": "extract",
+      "extract": { "kind": "skill-names" }
+    }
+  ],
+  "articles": [
+    {
+      "id": "连接器管理",
+      "file": "wiki/连接器管理.md",
+      "sourceIds": ["schema.sql"],
+      "humanOwned": false
+    }
+  ]
+}
+```
+
+`profile`: `mixed` (docs + code), `documents`, `code`.
+
+Source kinds:
+
+| kind | raw | when it drifts |
+|---|---|---|
+| `document` | copy of `livePath` | sync raw, rewrite articles that list this `id` |
+| `derived` | extract from `livePath` | re-run extract, rewrite dependents |
+| `code-surface` | none (`rawPath` null) | rewrite dependents; do not copy source into raw |
+
+`livePath` is repo-relative. `rawPath` is wiki-root-relative. `file` is wiki-root-relative.
+
+Article id = basename of `file` without `.md`. Renames are explicit `LINK` / `RETIRE`, never a silent refresh side effect.
+
+## Derived extracts
+
+Every `kind: derived` source must set `extract.kind` to one of `skill-names`, `heading-list`, or `prose-note`. Refresh and rebuild re-run that recipe into `rawPath`. Do not copy the live file in full.
+
+Shared rules:
+
+1. Input is `livePath` (or the live files the recipe names).
+2. Output is `rawPath` only.
+3. Sort or section order must be stable and documented for that kind.
+4. The extract must be smaller than the live input and must not include secrets, hashes, or lock metadata unless the recipe says those names are the payload.
+5. Replay the same recipe on drift; do not hand-edit raw to "fix" names.
+
+| `extract.kind` | Replay |
+|---|---|
+| `skill-names` | `extract.mjs skill-names --in <livePath> --out <wiki-root>/<rawPath>`. Lists `skills.shared` and `skills.platform` keys, `localeCompare` sorted. No hashes or paths. |
+| `heading-list` | Agent: list headings from the live file in document order, verbatim. No body copy. No script in this skill. |
+| `prose-note` | Agent: short labelled note that cites the live inputs. Stable section order. No full-file copy. No script in this skill. |
+
+## init
+
+Done when the target is a detectable Karpathy wiki and lint exits 0.
+
+1. If `wiki/index.md` already exists: ask refresh vs rebuild. Do not init over it.
+2. Ask: wiki path, corpus roots, coverage, and body language (follow the host project's document-language rule). See [discover.md](discover.md).
+3. Discover corpus with the [discover.md](discover.md) checklist. Do not ingest `docs/` wholesale.
+4. Write raw copies/extracts. Write manifest source list. Run `inventory.mjs hash`.
+5. Write `wiki/CLAUDE.md` from the template, adapted to this corpus — do not hard-code a previous product name.
+6. Write `index.md` categories first, then articles. Categories are index `##` headings.
+7. Orchestrator writes hub pages. Other pages go to subagents with disjoint file lists ([writing.md](writing.md)).
+8. Lint. Sample live-source facts. Append `log.md` `CREATE`.
+
+## refresh
+
+Done when only drift-hit articles change, human-owned pages are untouched, lint exits 0, and log has a structured `REFRESH`.
+
+1. No manifest → stop. Rebuild, or rebuild the manifest from existing「来源」sections. Do not invent `sourceIds`.
+2. `inventory.mjs status` (alias of `drift`) against every `livePath`. Pass each Agent-listed new file as `--candidate <livePath>`. Do not scan the tree. Read the JSON keys `changed`, `missing`, `unchanged`, `articles`, `unmapped`, `humanOwned`. Non-empty `changed` or `missing` is stale. Exit `0` with that JSON is normal, not a failure. Exit `2` is a script error.
+3. Impact set = `articles`. Rewrite those pages except `humanOwned` (wikilinks only).
+4. For `document` / `derived`: update raw first (derived: re-run `extract`), then rewrite hit articles.
+5. Each `unmapped` live path must get one triage: `New` / `Update` / `Disputed` / `No material`. Do not create pages silently. `No material` appends log only.
+6. Deleted sources → mark missing in citing articles; do not delete pages silently.
+7. Unhit articles: zero bytes changed.
+8. Rewrite is not "rewrite the whole wiki and call it refresh".
+9. Lint. Sample facts on hit pages. Append `REFRESH` with machine-readable fields:
+
+```
+## [YYYY-MM-DD] REFRESH | <summary>
+- changed: <sourceId>, ...
+- missing: <sourceId>, ...
+- articles: <articleId>, ...
+- unmapped: <livePath> (New|Update|Disputed|No material)
+```
+
+Omit an empty `changed` / `missing` / `articles` line. Repeat `unmapped` once per candidate. `status` / `drift` never fail just because those arrays are non-empty.
+
+## rebuild
+
+Done when raw matches live, LLM-owned pages are rewritten, stable ids and human-owned pages remain, lint exits 0, and log has `REBUILD`.
+
+1. Rediscover corpus with [discover.md](discover.md). Do not trust the old source list as complete.
+2. Recopy / re-extract raw.
+3. Keep article ids that still earn a page. Retired ids: `RETIRE` in log, drop from index.
+4. `humanOwned: true` (frontmatter or manifest): fix wikilinks only.
+5. Rewrite remaining articles. Rebuild index (categories may evolve).
+6. Replace manifest via `inventory.mjs hash`.
+7. Full lint + sample + `REBUILD`.
+
+rebuild is not `rm -rf wiki`. Stable ids keep old `[[wikilink]]` and external links valid.

package/template/.cursor/skills/llm-wiki/references/discover.md

@@ -0,0 +1,41 @@
+# Discover corpus
+
+Discovery is an Agent checklist, not a scanner. Use it for `init` and `rebuild`. Confirm the answers, then write sources. Do not silently ingest every markdown file.
+
+## Ask first
+
+1. Wiki path (`<wiki-root>`).
+2. Corpus roots the user wants covered.
+3. Coverage: `core` (authoritative process / contract files) or `full` (core plus extra docs the user names).
+4. Body language: follow the host project's document-language rule.
+
+If any answer is missing, ask. Do not guess from directory names or Git remotes.
+
+## Default include (core)
+
+Unless the user replaces this list with the host's single source-of-truth table:
+
+- Root authoritative files (for example `README`, `AGENTS`, `CONTEXT`, repository-identity manifest)
+- `docs/adr/`
+- `docs/process/`
+- `docs/agents/`
+- `docs/templates/`
+- Frozen contracts the user names
+
+`full` adds only roots the user listed. It is not "everything under `docs/`".
+
+## Default exclude
+
+- `docs/reviews/`
+- `docs/.scratch/`
+- Agent projection directories (copies or symlinks of shared skills)
+- `node_modules`
+- Whole lock files (`package-lock.json`, `pnpm-lock.yaml`, `skills-lock.json` as a document). A lock may appear only as `kind: derived` with an `extract` recipe.
+
+## Threshold
+
+If the candidate `document` count would exceed 40, list the candidates and stop. Do not write `raw/`, articles, or the manifest until the user confirms the list.
+
+## After the list is confirmed
+
+Write raw copies or extracts, then fill manifest `sources` per [compile.md](compile.md). Derived sources need `extract`. Code surfaces are not copies.

package/template/.cursor/skills/llm-wiki/references/ingest.md

@@ -0,0 +1,36 @@
+# Ingest
+
+Ingest is a compile mode. It adds a user-named external source or an already-written research note to the wiki. It does not replace `refresh`.
+
+Query must not ingest. Mapped live sources that changed go to `refresh`.
+
+## Allowed inputs
+
+- A URL, paste, or file outside the repo that the user named in this turn.
+- An already-written research note on disk (for example under the host's research archive). One-off fact gathering still belongs to the host's research skill; ingest only compiles a note that already exists.
+
+Forbidden inputs: `docs/reviews/`, `docs/.scratch/`, agent projection directories, lock files as documents, and any live authoritative file that is already a manifest `livePath`.
+
+Do not treat a web search as this skill's `refresh`. Confirm new web material as a named input first.
+
+## Done when
+
+`raw/` has the copy or labelled extract, the manifest lists the source, triage is recorded, confirmed pages are written (or none if the user declined), structural lint exits 0, advise has been run, and `log.md` has `INGEST`.
+
+## Steps
+
+1. Detect the wiki. No `wiki/index.md` → suggest `init`. Stop.
+2. If the path is already a manifest `livePath` → stop and use `refresh`.
+3. Write `raw/` as a copy or a labelled extract. Do not invent `extract.kind` values. Do not edit live authoritative files.
+4. Add a manifest source (`kind: document` or `derived`) with `livePath` (repo-relative when the file is in-repo; otherwise leave a labelled extract and record the origin in the extract header). Do not create a second config file (`inbox.md`, YAML sidecars). The pending queue is the new source plus the log.
+5. Run `inventory.mjs status --wiki <wiki-root> --candidate <livePath>` if the input is in-repo. Assign each unmapped path or new source one triage: `New` / `Update` / `Disputed` / `No material`.
+6. Show the candidate article list. **Stop until the user confirms.** Unconfirmed ingest changes zero article bytes. `No material` writes log only.
+7. After confirmation: write or update only the confirmed pages. Use `## Status` when triage is `Disputed`. Follow [writing.md](writing.md).
+8. `inventory.mjs hash`. Structural lint. Advise (report counts). Sample live/raw facts on changed pages. Append:
+
+```
+## [YYYY-MM-DD] INGEST | <summary>
+- source: <sourceId>
+- disposition: New|Update|Disputed|No material
+- articles: <articleId>, ...
+```

package/template/.cursor/skills/llm-wiki/references/lint.md

@@ -0,0 +1,54 @@
+# Lint
+
+From the repo root, run this skill's scripts (resolve `<skill-root>` from the directory that contains `SKILL.md`):
+
+```bash
+node <skill-root>/scripts/lint-wikilinks.mjs <wiki-root>
+node <skill-root>/scripts/advise.mjs <wiki-root>
+```
+
+`lint-wikilinks.mjs` exit 0 only when every structural check below passes. `advise.mjs` always prints JSON and exits `0` when the report is valid (exit `2` is a script error). Advise never fails lint and never auto-fixes.
+
+## Script checks
+
+- Every `[[target]]` in articles and `index.md` resolves to `wiki/target.md` (infrastructure filenames are not valid article targets). Cross-path targets such as `[[../other]]` fail; they are not ignored.
+- Every article H1 equals the article id (filename without `.md`).
+- Every `[[wikilink]]` in `index.md` exists on disk.
+- Every article file appears in `index.md`. Orphans fail.
+- Every article has a `## 来源` heading.
+- Infrastructure files are not articles: `index.md`, `log.md`, `CLAUDE.md`, `AGENTS.md`, `soul.md`, `concept-table.md`.
+- Missing `## Status` is not a failure.
+- If `.wiki-manifest.json` exists:
+  - each `articles[].file` exists; each `sources[].livePath` exists when set; `sha256` mismatch is stale (fail)
+  - every non-infrastructure `wiki/*.md` appears in `articles[]`
+  - each `articles[].id` equals the basename of `file` without `.md`
+  - each `sourceIds[]` exists in `sources[].id`
+  - `profile === "documents"` forbids `kind: code-surface`
+  - `kind: document|derived` requires a `rawPath` whose file exists; `code-surface` requires `rawPath == null`
+  - `kind: derived` requires `extract.kind` in `skill-names` | `heading-list` | `prose-note`
+
+`STALE HASH` during lint means the wiki is being claimed healthy while live files drifted. That is separate from `inventory.mjs status`, which reports the same drift with exit `0`.
+
+## Advise (do not repair)
+
+After the structural script, run `advise.mjs` and report the counts. JSON keys:
+
+- `oneWayLinks`: article A → B and B has no link back to A. `index.md` links do not count as backlinks.
+- `missingTermPages`: backtick identifiers, `**bold**` phrases, or `##` headings that appear at least twice and are not an article id.
+- `unreferencedRaws`: manifest `rawPath` values not cited in any article `## 来源`.
+- `suspects`: high-signal literals (number+suffix such as `42K`, ISO dates, quoted strings of length ≥ 12) in the article body that do not appear in the cited live/raw files.
+
+Do not create pages. Do not rewrite numbers. Do not promote `suspects` to lint exit 1.
+
+## Agent checks (after scripts)
+
+From changed pages, sample `N = min(5, changed page count)` claims against **live** files, not against the wiki text just written.
+
+Look for: enum members, HTTP statuses, "persisted vs in-memory", hardcoded vs configured values, freeze coverage vs extra controllers. Advise cannot replace this pass.
+
+## Repair
+
+- Broken wikilink: add the page, retarget, or remove the link. Do not leave dangling `[[...]]`.
+- Stale hash: run refresh on that source, or `inventory.mjs hash` after a deliberate raw sync.
+- Missing manifest on an otherwise valid wiki: reconstruct from「来源」or rebuild. Do not invent mappings.
+- Advise findings: report only, unless the user asked to act on a specific item.