create-yss-spec 3.0.0 → 3.0.1

package/template/.hermes/skills/java-backend-commit/references/scope-and-examples.md

@@ -1,118 +0,0 @@
-# Java 后端 Type、Scope 与示例
-
-## 目录
-
-- [规则优先级](#规则优先级)
-- [Type 选择](#type-选择)
-- [Scope 选择](#scope-选择)
-- [原子提交边界](#原子提交边界)
-- [消息示例](#消息示例)
-- [Java 验证](#java-验证)
-- [规范依据](#规范依据)
-
-## 规则优先级
-
-1. 仓库 commitlint 的 resolved config 和 hooks。
-2. 仓库 `AGENTS.md`、`CONTRIBUTING.md`、提交模板及明确文档。
-3. Maven/Gradle 模块定义、稳定业务术语及目标路径近期的有效提交。
-4. 本参考的通用回退规则。
-
-仓库允许空 scope 时仍优先使用能说明服务或业务域的 scope；跨全仓且没有清晰主域时可以省略。只有仓库明确要求时才添加工单 footer、DCO 或签名。
-
-## Type 选择
-
-| Type | 使用条件 | 不要用于 |
-|---|---|---|
-| `feat` | 新增 API、业务能力、运维能力或可用配置 | 纯重构或依赖升级 |
-| `fix` | 修复错误结果、异常、回归、事务或并发缺陷 | 仅格式化代码 |
-| `docs` | 只修改文档或 Javadoc | 代码行为变化 |
-| `style` | 仅格式、空格、导入排序等，不改变语义 | 接口或 UI 风格变化 |
-| `refactor` | 不增功能、不修 bug 的结构调整 | 性能优化或行为修复 |
-| `perf` | 有明确性能收益的代码或查询变化 | 无证据的“优化”措辞 |
-| `test` | 只增加或修正测试 | 功能代码及其配套测试 |
-| `build` | Maven/Gradle、依赖、插件、打包或编译配置 | 一般业务配置 |
-| `ci` | CI/CD 配置和流水线脚本 | 本地构建配置 |
-| `chore` | 其他不改变产品行为的维护工作 | 无法理解改动时的兜底 |
-| `revert` | 明确回滚一个或多个既有提交 | 普通修复 |
-
-## Scope 选择
-
-按以下顺序选择首个清晰候选：
-
-1. **仓库限定值**：若 `scope-enum` 生效，只能使用允许值或按规则省略。
-2. **构建模块**：Maven 使用稳定的 `artifactId`，Gradle 使用子项目名，例如 `order-service`、`risk-engine`。
-3. **服务或限界上下文**：单模块项目按稳定业务域使用 `order`、`customer`、`settlement`、`valuation` 等名称。
-4. **跨模块能力**：确实横跨业务域时使用仓库已有的 `api`、`db`、`security`、`messaging`、`observability`、`deps`、`build` 或 `ci`。
-
-命名使用小写 kebab-case。优先采用 `pom.xml`、Gradle settings、包名和产品文档中的既有术语。`controller`、`service`、`repository`、`entity`、`common` 和具体类名通常不能表达业务影响，不应作为默认 scope。
-
-## 原子提交边界
-
-- 同一业务能力的 controller、application/domain service、repository、DTO、迁移和测试可以同提交，确保提交可构建和回滚。
-- 公共契约与所有必需调用方修改通常同提交；若仓库支持分阶段兼容迁移，则按兼容阶段拆分。
-- `pom.xml`、version catalog 或 Gradle 文件与其 lock/verification metadata 一起提交；无关依赖升级单独使用 `build(deps)`。
-- Flyway/Liquibase 新迁移与对应实体、查询和测试可同提交；不要顺手重写已发布版本化迁移。
-- 两个独立业务域、不同发布风险或不同回滚策略的改动应拆分；同一文件内无法安全分离时先请求用户决定。
-
-## 消息示例
-
-```text
-feat(order): 支持批量取消待支付订单
-
-- 增加批量取消接口并复用单笔状态校验
-- 保持已支付订单处理和审计记录不变
-- 补充事务回滚与部分非法状态测试
-```
-
-```text
-fix(settlement): 修复重复回调导致结算流水重复入账的问题
-
-- 使用业务幂等键拦截已处理回调
-- 保留失败回调的可重试能力
-```
-
-```text
-build(deps): 升级 Spring Boot 与数据库驱动
-```
-
-```text
-feat(customer-api)!: 统一客户查询响应结构
-
-- 将分页数据统一为 items 和 total
-- 更新 OpenAPI 契约与消费者测试
-
-BREAKING CHANGE: 原 records 字段改为 items，调用方需更新反序列化模型
-```
-
-```text
-perf(valuation): 批量加载估值参数以减少重复查询
-
-- 将逐条查询合并为按产品批量加载
-- 增加查询次数断言并验证计算结果保持一致
-```
-
-错误与修正：
-
-| 错误 | 修正方向 |
-|---|---|
-| `fix：修改 OrderService` | 使用 ASCII 冒号并描述修复结果 |
-| `feat(controller): 新增接口` | 使用服务、模块或业务域 scope |
-| `chore: 修改数据库` | 判断是功能、修复、性能还是构建变化 |
-| `fix(order): 修复 bug` | 说明错误场景和用户可感知结果 |
-
-## Java 验证
-
-- 优先使用 wrapper，避免依赖开发机全局 Maven 或 Gradle 版本。
-- Maven 多模块可基于真实模块使用 `./mvnw -pl <module> -am test`；Gradle 可使用 `./gradlew :<module>:test`。不要编造模块路径或任务。
-- API 变更运行契约或集成测试；数据库变更运行迁移和 repository 测试；并发、事务和性能变更运行能证明关键性质的测试。
-- 使用仓库已有 Checkstyle、SpotBugs、PMD、Error Prone、JaCoCo 或格式检查任务；不要擅自引入新工具。
-- 测试产生的 `target/`、`build/`、日志和报告不得进入提交。
-
-## 规范依据
-
-- [Conventional Commits 1.0.0](https://www.conventionalcommits.org/en/v1.0.0/)
-- [commitlint：AI Agents](https://commitlint.js.org/guides/ai-agents.html)
-- [commitlint 官方 committing-with-commitlint skill](https://github.com/conventional-changelog/commitlint/tree/master/skills/committing-with-commitlint)
-- [Spring Framework CONTRIBUTING](https://github.com/spring-projects/spring-framework/blob/main/CONTRIBUTING.md)
-- [Git SubmittingPatches](https://git-scm.com/docs/SubmittingPatches)
-

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

@@ -1,60 +0,0 @@
----
-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-root>/wiki/index.md` + `CLAUDE.md` (or `AGENTS.md`) means a wiki exists. Default wiki-root is repo-root `wiki/`. If `yss-project.yaml` is `repository_mode: template-source`, wiki-root is `.template-source/wiki`.
-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/.hermes/skills/llm-wiki/assets/CLAUDE.md.template

@@ -1,26 +0,0 @@
-# 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/.hermes/skills/llm-wiki/assets/fixtures/broken-wiki/wiki/CLAUDE.md

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

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

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

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

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

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

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

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

@@ -1,126 +0,0 @@
-# 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/.hermes/skills/llm-wiki/references/discover.md

@@ -1,42 +0,0 @@
-# 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/`
-- `.template-source/evidence/`
-- `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/.hermes/skills/llm-wiki/references/ingest.md

@@ -1,36 +0,0 @@
-# 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/.hermes/skills/llm-wiki/references/lint.md

@@ -1,54 +0,0 @@
-# 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.

package/template/.hermes/skills/llm-wiki/references/query.md

@@ -1,21 +0,0 @@
-# Query
-
-Query is not a compile mode. It reads the wiki; it does not write `raw/`, articles, `index.md`, `log.md`, or `.wiki-manifest.json`.
-
-Use this algorithm when the user asks a repository question and a wiki exists, or asks to answer from the wiki. Do not open the whole corpus, and do not treat wiki prose as live fact.
-
-## Steps
-
-1. **Detect.** If `wiki/index.md` is absent, say the question is outside query: no wiki exists. Suggest `init`. Stop.
-
-2. **Freshness.** If `.wiki-manifest.json` exists, run `inventory.mjs status --wiki <wiki-root>` (same JSON as `drift`). Read `changed`, `missing`, `unchanged`, `articles`, `unmapped`, `humanOwned`. Exit `0` is a valid report, not a failure. Exit `2` is a script error. Show that source-status table. Non-empty `changed` or `missing` means stale: name those sources, ask whether to `refresh`, and do not present drifted pages as current fact. If the user still wants an answer, mark every claim that depends on a drifted source as stale.
-
-3. **Select pages.** First match proper nouns and distinctive terms against `index.md` category headings (`##`) and `[[wikilink]]` targets. If that set is empty or clearly too narrow for the question, search H1 and the first paragraph of each non-infrastructure `wiki/*.md` with the question's distinctive terms and obvious synonyms (`rg` is enough; do not build an index). Open at most `N = min(8, hit count)` articles. Do not open the whole wiki. Do not answer from one summary paragraph when more hit pages exist.
-
-4. **Verify claims.** For each assertion, re-read the live paths in that page's `## 来源` (repo-relative live files, not the wiki sentence). If wiki text conflicts with live, cite live and record wiki drift. Do not rewrite the wiki during query. Do not ingest.
-
-5. **Zero hits.** Only after **both** the index/`[[wikilink]]` pass and the H1/summary search are empty may you say the wiki does not cover the question. List the index categories considered and the search terms used. Do not invent article ids, pages, or facts.
-
-## Done when
-
-The answer cites the pages actually opened and the live sources actually re-read, or it states non-coverage. Query never completes via lint, `CREATE`, `REFRESH`, `REBUILD`, or `INGEST`.

package/template/.hermes/skills/llm-wiki/references/schema.md

@@ -1,45 +0,0 @@
-# Wiki schema
-
-Karpathy three-layer wiki. Detectable by `index.md`, `[[wikilink]]`, optional `raw/`, and `CLAUDE.md` or `AGENTS.md`.
-
-## Layers
-
-- **raw/** — immutable sources. The agent reads them; it does not edit them to "fix" facts. Wrong facts are fixed by recompiling the wiki from live paths. Allowed contents: copies of documents, and derived extracts that name their live inputs and an `extract` recipe (see [compile.md](compile.md)).
-- **wiki/** — LLM-owned markdown. Humans read; the agent writes. Article id = filename without `.md`, globally unique. Infrastructure files are not articles: `index.md`, `log.md`, `CLAUDE.md`, `AGENTS.md`, `soul.md`, `concept-table.md`.
-- **schema** — `wiki/CLAUDE.md` (this repo also accepts `AGENTS.md`). Conventions for ingest, refresh, rebuild, and lint. Co-evolve it with the domain; start from `assets/CLAUDE.md.template`.
-- **.wiki-manifest.json** — compile graph, sibling of `raw/` and `wiki/`. Not an article. Not a raw source.
-
-## index.md
-
-`##` headings are categories (taxonomy). Listed `[[wikilink]]` assign articles to categories. Categories come from index headings, not filename prefixes.
-
-## log.md
-
-Append-only. Format: `## [YYYY-MM-DD] OPERATION | 描述`
-
-Operations: `CREATE` `UPDATE` `LINK` `FIX` `REFRESH` `REBUILD` `RETIRE` `LINT` `INGEST`.
-
-## concept-table.md
-
-Optional. Infrastructure, same class as `index.md`. A table of concept, relationship, and article id. Rebuild may rewrite it. Do not move articles into `wiki/entities/`.
-
-## Articles
-
-1. `# H1` then a one-paragraph summary (parsers use this as summary).
-2. Body uses `[[ArticleId]]`. Target must be a wiki article filename without `.md`.
-3. Every claim traces to `raw/` or a live code path. End with a `## 来源` section.
-4. Optional YAML frontmatter: `human-owned: true` — refresh/rebuild must not rewrite the body; they may fix wikilinks only.
-5. Optional `## Status` when multiple `sourceIds` disagree, or live disagrees with old raw:
-
-```markdown
-## Status
-- kind: Disputed | Outdated
-- sources: <sourceId>, <sourceId>
-- note: one-line conflict
-```
-
-Do not write Status when a single live source is correct. Refresh that finds a conflict keeps both citations and the Status block; it must not silently overwrite with the newest live text and pretend there was no conflict. `human-owned` pages do not get a Status rewrite. Status is not an article id and is not an index category. Missing Status is not a lint failure.
-
-## Language
-
-Body language follows the host project's document-language rule. Keep identifiers, enums, table names, API paths, and filenames verbatim.

package/template/.hermes/skills/llm-wiki/references/writing.md

@@ -1,35 +0,0 @@
-# Writing
-
-## Page shape
-
-- `# H1` immediately followed by a summary paragraph.
-- `[[ArticleId]]` only; no relative `[[../other-wiki]]` inside a Karpathy wiki (cross-wiki use markdown links).
-- Close with `## 来源` listing raw files and live code paths actually read.
-- Optional `## Status` only when cited sources conflict or live disagrees with old raw. See [schema.md](schema.md). Missing Status is not a defect.
-- Do not invent enum values, table names, or endpoints. If unread, write「见源码」.
-
-## Fact order
-
-1. Called implementation (application service, domain method, mapper SQL).
-2. Table comments / OpenAPI / config defaults.
-3. Stale raw copies.
-
-A column default is not proof the runtime uses it. A freeze OpenAPI is not the full controller surface.
-
-## Coverage
-
-Core pages: deep (state machines, HTTP semantics, transactions). Extension pages: overview (models, enums, tables, links). Match the user's coverage choice from init.
-
-## Subagents
-
-When 2+ article groups have no shared files:
-
-- Each prompt lists exact write paths. Those agents must not touch `index.md`, `log.md`, `.wiki-manifest.json`, or `CLAUDE.md`.
-- Return: paths written + wikilink count per file.
-- Orchestrator merges, lints, samples facts, appends log.
-
-When article groups share no files, dispatch parallel subagents with disjoint write scopes.
-
-## Human-owned
-
-Frontmatter `human-owned: true` or manifest `humanOwned: true`. Refresh/rebuild leave the body; they may repair `[[wikilink]]` targets only. Do not add or rewrite `## Status` on these pages.