silvermoon 0.0.2 → 0.1.0

package/README.md

@@ -0,0 +1,168 @@
+<!-- markdownlint-disable-file MD041 -->
+
+<p align="center">
+  <!-- markdownlint-disable-next-line MD013 -->
+  <img src="https://raw.githubusercontent.com/shazhou-ww/silvermoon/936bf4af71450499aebe4ccac7562ce583f34f8b/assets/silvermoon.svg" width="960" alt="Silvermoon, the artifact spirit of the project">
+</p>
+
+<p align="center">
+  <!-- markdownlint-disable-next-line MD013 -->
+  <a href="https://npmx.dev/package/silvermoon"><img src="https://img.shields.io/npm/v/silvermoon?style=flat-square" alt="npm version"></a>
+  <!-- markdownlint-disable-next-line MD013 -->
+  <a href="https://npmx.dev/package/silvermoon"><img src="https://img.shields.io/node/v/silvermoon?style=flat-square" alt="Node.js version"></a>
+  <!-- markdownlint-disable-next-line MD013 -->
+  <a href="https://npmx.dev/package/silvermoon"><img src="https://img.shields.io/npm/unpacked-size/silvermoon?style=flat-square" alt="npm unpacked size"></a>
+  <!-- markdownlint-disable-next-line MD013 -->
+  <a href="https://github.com/shazhou-ww/silvermoon/actions/workflows/ci.yml?query=branch%3Amain"><img src="https://img.shields.io/github/actions/workflow/status/shazhou-ww/silvermoon/ci.yml?branch=main&style=flat-square&label=CI" alt="CI status"></a>
+</p>
+
+<p align="center">
+  English | <a href="https://github.com/shazhou-ww/silvermoon/blob/936bf4af71450499aebe4ccac7562ce583f34f8b/README.zh-CN.md">简体中文</a>
+</p>
+
+# Silvermoon
+
+**The artifact spirit of the project.**
+
+## Quick Start
+
+Silvermoon needs Node.js 22 or newer and Git access to the repository's primary
+branch.
+
+```sh
+npm install --global silvermoon
+silvermoon whats-next
+```
+
+Silvermoon is ecosystem-neutral: the target repository does not need
+`package.json`, a package manager, a Silvermoon dependency, or `node_modules`.
+The first report lists every applicable setup step in order, including the
+exact `npx skills add ... --agent universal` command that registers the
+canonical skill at `.agents/skills/silvermoon`.
+
+Create `.silvermoon/config.yaml`:
+
+```yaml
+version: 1
+primaryRepository: https://github.com/example/repository.git
+primaryBranch: main
+preferredLanguage: en
+```
+
+`preferredLanguage` is optional. A specific idea can override it with
+`language` in `status.yaml`, and `create-idea --language <tag>` can set that
+override when the idea is created. Otherwise Silvermoon checks
+`~/.config/silvermoon/config.yaml` and finally defaults to `en-US`.
+
+Then create an idea and let the registered Silvermoon skill guide one safe
+next action at a time:
+
+```sh
+silvermoon create-idea
+silvermoon whats-next <idea>
+```
+
+Describe the desired world in the generated `Idea.md`, review it, and approve
+that exact revision. From then on, Silvermoon keeps the goal, implementation,
+repository state, and real-world result connected. See
+[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/936bf4af71450499aebe4ccac7562ce583f34f8b/docs/getting-started.md) for the complete first workflow.
+Default dialogue output uses lightweight Markdown headings for intent,
+observation, and next instructions, plus actions and outcomes only when an
+operation was attempted. Add `--json` only when a programmatic consumer needs
+the `intention / observation / outcomes / instructions` envelope. For
+pre-commit validation, run `silvermoon check --staged`: unlike the default
+`check` (committed `HEAD`), it checks the index and exits `0` only when the
+project snapshot is valid. See the [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/936bf4af71450499aebe4ccac7562ce583f34f8b/docs/reference.md)
+for validation targets and exit codes. Add `--trace <file.trace.jsonl>` to any
+command to write paired task and Git timing spans for performance analysis.
+If the argument does not end with the exact lowercase `.trace.jsonl` suffix,
+Silvermoon appends it. Repository-local `*.trace.jsonl` files are ignored.
+Trace files are created only after the measured command work completes and
+never overwrite an existing file.
+
+## Why Silvermoon
+
+Long-running Agent work usually asks people to carry too much invisible state.
+Someone must remember what was intended, whether the code still matches the
+task, and which conversation or machine knows the latest truth. Silvermoon
+makes those concerns part of the project instead.
+
+It lets people step back from continuous supervision and return at the
+decisions that belong to them: approving the intended outcome, accepting the
+implementation, and accepting that the result is true in the outside world.
+Between those boundaries, an Agent can inspect repository facts and continue
+the highest-priority safe action.
+
+It also refuses to let a detached task card declare success. Current artifacts
+and explicit decisions jointly determine state, so a changed goal or
+implementation naturally invalidates conclusions that depended on the older
+revision. Because those facts live in Git, work can continue across devices,
+sessions, Agents, and hosting platforms.
+
+## The Project's Artifact Spirit
+
+> Fellow Daoist, you wouldn't want your lifebound project to be without an
+> artifact spirit, would you?
+
+<table>
+  <tr>
+    <td width="160" align="center" valign="top">
+      <!-- markdownlint-disable-next-line MD013 -->
+      <img src="https://raw.githubusercontent.com/shazhou-ww/silvermoon/936bf4af71450499aebe4ccac7562ce583f34f8b/docs/assets/silvermoon-avatar.svg" width="128" alt="Line portrait of Silvermoon, the project's artifact spirit">
+    </td>
+    <td valign="top">
+      Silvermoon is named after a character in <em>A Record of a Mortal's
+      Journey to Immortality</em>. She comes from the Silvermoon Wolf Clan in
+      the Spirit Realm and is one of the split souls of Ling Long. After losing
+      part of her memory in the human realm, she lives as an artifact spirit
+      first in a wolf-headed jade scepter and later in Han Li's Bamboo
+      Cloudswarm Swords.
+      <br><br>
+      That image fits this project: Silvermoon does not belong to one operator
+      or one chat. It lives with the project's artifacts, understands their
+      state, and helps each companion find what comes next. The biography is
+      inspiration, not a prerequisite for using the tool.
+    </td>
+  </tr>
+</table>
+
+Watch *A Record of a Mortal's Journey to Immortality*:
+
+<!-- markdownlint-disable-next-line MD013 -->
+- YouTube: [Episode 150: Overseas Turmoil 26](https://www.youtube.com/watch?v=GJgezoCBIHM "A Record of a Mortal's Journey to Immortality — Episode 150: Overseas Turmoil 26")
+<!-- markdownlint-disable-next-line MD013 -->
+- Bilibili: [Episode 150: Overseas Turmoil 26](https://www.bilibili.com/bangumi/play/ep1231558 "A Record of a Mortal's Journey to Immortality — Episode 150: Overseas Turmoil 26")
+
+## From Ideal To Real
+
+A project is more than a task list or a transcript. It is an ideal becoming
+real through three nested worlds.
+
+**Ideal World (道心)** names the outcome worth pursuing. **Inner World (内景)**
+gives that intent shape in repository artifacts. **Outer World (现世)** asks
+whether the shaped work is true where it must actually operate.
+
+> 道心立意，内景成形，现世验真。
+
+The worlds nest from the inside out. Implementation contains the ideal it
+serves, and deployment contains both. This is an engineering relationship, not
+just a metaphor: when an inner world changes, conclusions from an outer world
+no longer have the same foundation and must be proven again.
+
+Humans own approval and acceptance. Agents own continuation: they read the
+contracts, the ledger, and Git facts; preserve concurrent work; execute one
+safe action; and reobserve only after something changes. The context belongs to
+the project, not to a fleeting conversation.
+
+## Further Reading
+
+- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/936bf4af71450499aebe4ccac7562ce583f34f8b/docs/getting-started.md) — installation, configuration,
+  and the first idea.
+- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/936bf4af71450499aebe4ccac7562ce583f34f8b/docs/core-concepts.md) — project ownership, the three
+  worlds, revisions, and decision boundaries.
+- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/936bf4af71450499aebe4ccac7562ce583f34f8b/docs/operations.md) — navigation, creation,
+  publication, hygiene, and continuation.
+- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/936bf4af71450499aebe4ccac7562ce583f34f8b/docs/reference.md) — storage, derived state, CLI
+  reports, validation targets, and schemas.
+- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/936bf4af71450499aebe4ccac7562ce583f34f8b/docs/maintaining.md) — development checks,
+  documentation ownership, and release guidance.

package/README.zh-CN.md

@@ -18,10 +18,15 @@
 Silvermoon 需要 Node.js 22 或更高版本，并且能够通过 Git 访问仓库的 primary branch。
 
 ```sh
-npm install --save-dev silvermoon
-npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent github-copilot --yes --copy
+npm install --global silvermoon
+silvermoon whats-next
 ```
 
+Silvermoon 不依赖目标仓库的技术栈：目标项目无需 `package.json`、package manager、
+Silvermoon dependency 或 `node_modules`。首次报告会按顺序列出所有适用的整备步骤，
+其中包括把 canonical skill 注册到 `.agents/skills/silvermoon` 的精确
+`npx skills add ... --agent universal` 命令。
+
 创建 `.silvermoon/config.yaml`：
 
 ```yaml
@@ -38,13 +43,23 @@ preferredLanguage: zh-CN
 然后创建一个 idea，让已注册的 Silvermoon skill 每次引导一个安全的下一步行动：
 
 ```sh
-npx silvermoon create-idea --json
-npx silvermoon whats-next <idea> --json
+silvermoon create-idea
+silvermoon whats-next <idea>
 ```
 
 在生成的 `Idea.md` 中描述想要抵达的世界，审阅并批准这个精确 revision。此后，
 Silvermoon 会让目标、实现、仓库状态与现实结果始终相连。完整的首次工作流见英文
 [Getting Started](./docs/getting-started.md)。
+对话命令默认以轻量 Markdown 标题呈现意图、观察和下一步；只有实际尝试了操作，
+才出现动作与结果段落。程序消费者可使用 `--json` 获取
+`intention / observation / outcomes / instructions` envelope。提交前使用
+`silvermoon check --staged` 验证 index；无参数 `check` 只验证已提交的 `HEAD`，
+不能替代提交前检查。只有项目快照有效时检查才以退出码 `0` 放行，详见英文
+[Technical Reference](./docs/reference.md)。任何命令都可以添加
+`--trace <file.trace.jsonl>`，写出用于性能分析的成对任务与 Git 计时 span。参数若
+没有以精确的小写 `.trace.jsonl` 结尾，Silvermoon 会自动追加；repository 内的
+`*.trace.jsonl` 会被忽略。trace 文件只在待测命令工作完成后创建，并且绝不覆盖
+已有文件。
 
 ## 为什么需要 Silvermoon
 

package/docs/core-concepts.md

@@ -27,16 +27,16 @@ the same primary history and continue from the same facts.
 
 ## Three Nested Worlds
 
-**Ideal World (道心)** is the canonical intent in `Idea.md`. It defines the
-outcome, scope, and constraints without prescribing implementation.
+**Ideal World (理想世界)** is defined by the ideal contract in `Idea.md`. It
+describes the outcome, scope, and constraints without prescribing
+implementation.
 
-**Inner World (内景)** is the canonical implementation contract in
+**Inner World (主体世界)** contains the inner implementation contract in
 `Implementation.md` plus the repository deliverables that give the ideal form.
 
-**Outer World (现世)** is the canonical deployment contract in `Deployment.md`
-plus evidence that the implementation is true where it must operate.
-
-> 道心立意，内景成形，现世验真。
+**Outer World (现实世界)** contains the real-world deployment contract in
+`Deployment.md` plus evidence that the implementation is true where it must
+operate.
 
 The directory structure makes the relationship concrete: the Inner World
 contains the Ideal World, and the Outer World contains both. Each world is an
@@ -62,8 +62,10 @@ work, but a checked item is not approval or acceptance.
 
 ## One Project, Shared Facts
 
-`whats-next` observes the configured remote primary and returns the exact
-`observedPrimaryCommit` used for its guidance. Writers use that commit as the
-expected shared tip. If primary moves, they fetch and reobserve rather than
-replaying a stale decision. This is coordination through ordinary Git, not a
-distributed lock.
+`whats-next` first checks local worktree, HEAD, and upstream facts, then fetches
+the configured remote primary only when local hygiene permits it. Its
+observation and instructions report the exact local and remote commits used
+for ancestry guidance. Writers use the reported remote commit as the expected
+shared tip. If primary moves, they fetch and reobserve rather than replaying a
+stale decision. This is coordination through ordinary Git, not a distributed
+lock.

package/docs/getting-started.md

@@ -9,23 +9,28 @@ This guide is the authoritative setup and first-use path for Silvermoon.
 - Permission to fetch that branch and to publish ordinary non-force commits
   through the repository's normal collaboration path.
 
-## Install The Project Dependency
+## Run Silvermoon And Register Its Skill
 
-Install Silvermoon in the repository so every collaborator uses the declared
-version:
+Install Silvermoon independently of the target project's dependency graph, or
+invoke a chosen version temporarily:
 
 ```sh
-npm install --save-dev silvermoon
+npm install --global silvermoon
+silvermoon whats-next
+# or: npx silvermoon@<version> whats-next
 ```
 
-Register the canonical packaged skill through the supported `skills` interface:
+The setup report gives the exact path for the running installation. Use it to
+register the bundled canonical skill through the universal `skills` target:
 
 ```sh
-npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent github-copilot --yes --copy
+npx skills add <path-to-running-silvermoon>/skills --skill silvermoon --agent universal --yes --copy
 ```
 
-Silvermoon diagnoses whether the project dependency, installed package, and
-repository-local skill match. It does not install dependencies or mutate skill
+The registration lives only at `.agents/skills/silvermoon`. Silvermoon checks
+that its content exactly matches the running installation. It does not require
+the target repository to use Node, contain `package.json`, declare a
+Silvermoon dependency, or have `node_modules`, and it never mutates skill
 registration itself.
 
 ## Configure The Shared Primary
@@ -62,45 +67,66 @@ preferredLanguage: zh-CN
 
 Inherited values remain dynamic and are not copied into an idea. Use
 `create-idea --language <tag>` only when the new idea needs a stable override.
-`whats-next` reports both the effective tag and its source.
+The shared observation reports the resolved non-empty language tag.
 
 ## Create The First Idea
 
 Run:
 
 ```sh
-npx silvermoon create-idea --json
-npx silvermoon create-idea --language zh-cn --json
+silvermoon create-idea
+silvermoon create-idea --language zh-cn
 ```
 
-The command first applies the same repository, worktree, conflict, and ancestry
-hygiene used by navigation. When those checks pass, it creates one untracked
-idea scaffold with `Idea.md`, `Implementation.md`, `Deployment.md`,
-`ledger.md`, and `status.yaml`. It never stages, commits, pushes, or records a
-human decision.
-
-Replace the guidance in `Idea.md` with the desired outcome, scope, and
-constraints. Keep implementation and deployment placeholders synchronized
-until their lifecycle phases. Review every generated path and publish the
-prepared idea through ordinary Git.
+The command requires the configured primary branch and upstream plus a clean
+local worktree. It does not fetch or require local HEAD to match the remote
+tip. When those checks pass, it creates one untracked idea scaffold with
+`Idea.md`, `Implementation.md`, `Deployment.md`, `ledger.md`, and
+`status.yaml`. It never stages, commits, pushes, or records a human decision.
+
+Replace the guidance in the `Idea.md` ideal contract with the desired outcome,
+scope, and constraints. Keep the `Implementation.md` inner implementation
+contract and `Deployment.md` real-world deployment contract placeholders
+synchronized until their lifecycle phases. Review every generated path,
+validate the complete candidate, and commit and publish the prepared idea to
+the configured primary through the repository's normal non-force publication
+path. Verify it is reachable from refreshed primary before asking the user to
+review or approve the exact reported ideal revision. If publication requires a
+pull request, wait until it reaches primary; never ask for approval of an
+unpublished local candidate. Publication does not itself approve the idea.
 
 Then ask what comes next with the generated ULID or an exact unique alias:
 
 ```sh
-npx silvermoon whats-next <idea> --json
+silvermoon whats-next <idea>
 ```
 
-The report contains one highest-priority action. Execute only that action. Run
-the same command again only after an expected repository change, an unexpected
-input change, or a newly arrived external result.
+The default dialogue uses lightweight Markdown headings for intent,
+observation, and ordered next instructions; actions and outcomes appear only
+when an operation was attempted. Add `--json` only when a programmatic
+consumer needs the `intention / observation / outcomes / instructions`
+envelope. Execute the applicable instructions in order and run the same
+command again only after an expected repository change, an unexpected input
+change, or a newly arrived external result.
 
 ## Make Decisions Explicit
 
 Silvermoon never infers approval or acceptance. After a person explicitly
 approves the current ideal, accepts the current implementation, or accepts the
 current deployment, record the exact revision reported by `whats-next` in the
-corresponding `status.yaml` field. Validate the full candidate, stage it,
-validate the staged snapshot, and publish a normal non-force commit.
+corresponding `status.yaml` field. Validate the full candidate with
+`silvermoon check --worktree`, stage it, then run `silvermoon check --staged`
+to validate the index before publishing a normal non-force commit. Default
+`check` validates committed `HEAD`, not the pending commit; only a successful
+project validation exits `0`.
+
+When requesting any approval or acceptance, include the idea's alias and ULID,
+the decision and exact world revision, plus a clickable permalink to the
+canonical world entry pinned to the published primary commit. Link to
+`Idea.md`, `Implementation.md`, or `Deployment.md` as appropriate. Do not use
+a local workspace path or a branch-floating link; if the host has no known
+permalink format, provide the primary commit and repository-relative path and
+explain the limitation.
 
 Continue with [Core Concepts](./core-concepts.md) before changing lifecycle
 contracts, or use [Operating Silvermoon](./operations.md) for the routine

package/docs/maintaining.md

@@ -14,7 +14,8 @@ pnpm install --frozen-lockfile
 Use the smallest check that covers a change:
 
 ```sh
-pnpm sync:skills       # refresh the generated GitHub Copilot skill copy
+pnpm sync:skills       # refresh the generated universal skill copy
+pnpm lint:markdown     # Markdown lint and link checks
 pnpm test              # fast unit and repository contract tests
 pnpm test:integration  # real filesystem and Git behavior
 pnpm test:e2e          # packed and installed CLI behavior
@@ -22,10 +23,18 @@ pnpm check             # complete release-grade validation
 pnpm check:skills      # skill discovery and structure
 ```
 
+`pnpm check` runs the independent release-grade checks concurrently and waits
+for all of them before reporting every failure. Run the narrower commands above
+while iterating, then use `pnpm check` before delivery.
+
 Edit the canonical skill only under `skills/silvermoon`, then run
-`pnpm sync:skills`. The checked-in `.github/skills/silvermoon` directory is a
+`pnpm sync:skills`. The checked-in `.agents/skills/silvermoon` directory is a
 generated copy so repository skill discovery works without symbolic-link
 support. `pnpm check:skills` rejects a stale or manually edited copy.
+The repository-only publish skill is maintained directly under
+`.agents/skills/publish`; it is not part of the generated copy or npm package.
+For documentation and skill changes, run `pnpm lint:markdown`,
+`pnpm check:skills`, and `node --test test/contract/skill.test.mjs`.
 
 Run `pnpm check` after CLI, schema, repository model, release, or skill changes.
 Documentation work must also preserve Markdown links, package contents,

package/docs/operations.md

@@ -12,34 +12,42 @@ npx silvermoon whats-next publish-documentation --json
 ```
 
 Without a selector, Silvermoon asks for a choice among multiple active ideas,
-continues a single active idea, or reports that a new idea can be created. A
-selector is either a canonical uppercase ULID or an exact, unique,
-case-sensitive alias.
-
-Each successful report includes the effective `language` tag and its `idea`,
-`project`, `global`, or `default` source. Its action guidance requires the
-Agent to use that language for world entries, same-world supporting artifacts,
-the ledger, and user-facing explanations. Commands, identifiers, schema fields,
+and the option to discuss and create a new idea. This remains true with zero,
+one, or many active ideas: only a selector chooses work. Completed and abandoned
+ideas are excluded from default candidates. A selector is either a canonical
+uppercase ULID or an exact, unique, case-sensitive alias.
+
+The shared observation includes a resolved non-empty `preferredLanguage`.
+Instructions use it for world entries, same-world supporting artifacts, the
+ledger, and user-facing explanations. Commands, identifiers, schema fields,
 protocol markers, and verbatim tool output retain their original form.
 
-Every invocation first checks the configured primary branch, merge conflicts,
-worktree changes, and local/remote primary ancestry. It may fetch and inspect,
-but it never edits, checks out, merges, commits, stashes, deletes, resets,
-fast-forwards, or pushes.
+Every invocation follows three strict layers. It first checks Git,
+configuration compatibility, and `.agents/skills/silvermoon`. It then checks
+local conflicts, changes, HEAD, and upstream identity before any remote access.
+Only after those checks pass does it fetch primary, compare ancestry, and
+route idea work. It never edits, checks out, merges, commits, stashes, deletes,
+resets, fast-forwards, or pushes.
 
 ## Create An Idea
 
 Explicit creation uses:
 
 ```sh
-npx silvermoon create-idea --json
-npx silvermoon create-idea --language zh-cn --json
+silvermoon create-idea
+silvermoon create-idea --language zh-cn
 ```
 
 Creation intent is distinct from active-idea selection. If hygiene blocks the
 command, perform only the reported remediation and retry `create-idea`; do not
 replace the request with selector-less navigation.
 
+Creation checks project readiness, then requires the configured primary branch
+and upstream plus a clean worktree. It does not fetch, compare ancestry, or
+require local HEAD to be aligned with the remote tip. Its preparation reports
+omit the active-idea inventory because existing work does not replace explicit
+creation intent.
+
 `--language` is the only command-level language override. It normalizes a valid
 BCP 47 tag and writes it to the new idea's `status.yaml`. Without the option,
 creation writes no language field and the idea dynamically inherits project,
@@ -47,26 +55,38 @@ user, or `en-US` defaults. `whats-next` and `check` do not accept the option.
 
 The generated files remain untracked for review. Complete `Idea.md`, optionally
 add a concise unique alias, inspect every path, and publish the initial idea
-through ordinary Git.
-
-## Execute One Action
-
-Treat the command, request, `observedPrimaryCommit`, selected idea, and action
-as one immutable observation. Execute only the highest-priority action.
-
-Repository hygiene actions take precedence over lifecycle work. Inspect exact
-staged, unstaged, untracked, and conflicted paths; preserve unknown and
-concurrent work. Never force-push, use `reset --hard`, broadly clean the
-worktree, or silently rewrite history to satisfy guidance.
+through ordinary Git. Validate and commit the complete prepared idea, then make
+that commit reachable from configured primary using the repository's normal
+non-force publication path before asking the user to review or approve it. If
+publication requires a pull request, wait until it reaches primary. Reobserve
+the exact `idealRevision` after publication; never ask for approval of an
+unpublished local candidate, and never treat publication as approval.
+
+## Follow One Observation
+
+Treat `intention`, `observation`, `outcomes`, and `instructions` as one
+immutable dialogue report for `whats-next` and `create-idea`. Default output
+uses lightweight Markdown headings and lists for intent, observation, and
+next instructions, including actions and outcomes only if an operation was
+attempted. `--json` serializes the same model, retaining `outcomes: []` when
+none were attempted.
+
+Project setup takes precedence over repository synchronization, which takes
+precedence over lifecycle work. Instructions include every known remediation
+for the current layer in priority order. Large change sets report complete
+counts, bounded path samples, omitted counts, and exact commands for the full
+diff. Preserve unknown and concurrent work. Never force-push, use
+`reset --hard`, broadly clean the worktree, or silently rewrite history.
 
 After an observable change, run `whats-next` again. Do not poll an unchanged
 observation.
 
 ## Author World Contracts
 
-`Idea.md` is the Ideal World entry. `Implementation.md` and `Deployment.md`
-contain `## Steps` and `## Acceptance criteria`. Every item uses a stable
-level-three heading:
+`Idea.md` is the Ideal World's ideal contract. `Implementation.md` is the
+Inner World's inner implementation contract, and `Deployment.md` is the Outer
+World's real-world deployment contract. The latter two contain `## Steps` and
+`## Acceptance criteria`. Every item uses a stable level-three heading:
 
 - implementation steps: `I-Sxx`
 - implementation criteria: `I-ACxx`
@@ -94,14 +114,41 @@ the current reported world revision. Edit only the corresponding status fact:
 Validate the complete candidate:
 
 ```sh
-npx silvermoon check --worktree --json
+silvermoon check --worktree
 git add .silvermoon/ideas/<ULID>/status.yaml
-npx silvermoon check --staged --json
+silvermoon check --staged
 ```
 
+`check` is a project-only validator, not a navigation command. It does not
+check worktree hygiene, upstream, or ancestry and does not suggest next steps.
+Without a target it validates committed `HEAD`, not the pending commit.
+`--worktree` validates the full candidate, while `--staged` validates exactly
+the index and is the pre-commit hook target. Its JSON has `intention` and
+`observation` only; it has no `outcomes` or `instructions`. Exit status `0`
+means the chosen project snapshot is valid; `1` means invalid or unavailable
+and must block the commit; `2` means invalid CLI usage. Do not treat the
+existence of a report as permission to commit.
+
+`check` does not infer that a status field was newly written, prove who
+authorized it, compare it with a commit parent, or search history for its
+origin. Those are workflow responsibilities: match an explicit human decision
+to the exact revision reported by `whats-next`, edit only the corresponding
+status fact, review the candidate, and publish without rewriting concurrent
+history. Old decision revisions may remain in status after a world changes;
+their mismatch is what derives the idea's earlier lifecycle state.
+
 Prefer a status-only decision commit, publish through the repository's normal
 non-force path, and verify the commit is reachable from refreshed primary.
 
+When asking for approval or acceptance, identify the idea by alias and ULID,
+state the exact reported world revision, and link the corresponding canonical
+entry at the published primary commit: `Idea.md` for ideal approval,
+`Implementation.md` for implementation acceptance, or `Deployment.md` for
+deployment acceptance. Use a commit-pinned web permalink rather than a local
+workspace path or a branch name that can move. The linked revision and
+publication are review context only; the user must still make the decision
+explicitly.
+
 ## Publish Work
 
 Before publication, compare with the observed primary tip, run checks focused