silvermoon 0.1.0 → 0.1.3-rc.1

package/docs/getting-started.md

@@ -48,10 +48,39 @@ The repository URL is credential-free, canonical shared state. Credentials,
 named remotes, and URL rewrites remain local Git concerns. Silvermoon metadata
 paths are fixed and cannot be overridden by configuration.
 
-## Configure Preferred Language
+## Add Optional Project Phase Guidance
+
+Projects with additional lifecycle requirements may add any of these fixed
+files:
+
+```text
+.silvermoon/guidance/
+|-- preparing.md
+|-- implementing.md
+`-- deploying.md
+```
+
+Each file is optional, repository-owned Markdown for only its named phase.
+`whats-next <idea>` returns the applicable file only after that actionable
+phase becomes the highest-priority next action. A successful `create-idea`
+returns only preparing guidance after local preflight and before relying on
+the new scaffold. The report includes the fixed path, exact Git blob
+`contentRevision`, and captured content, so consumers must not reread the file.
+
+Keep each file at most 32 KiB of valid UTF-8 without a BOM or NUL byte, with at
+least one non-whitespace character. Use regular files and no extra entries in
+the directory. Lifecycle commands validate only the phase they are about to
+return; every `check` target validates the complete directory.
+
+Guidance is additive and lower priority than Silvermoon's canonical workflow.
+Put every applicable idea-specific requirement into the current world contract
+and matching ledger entries. The guidance itself is not a fourth contract,
+approval, acceptance, status fact, or completion evidence.
+
+## Configure Content And Output Language
 
 All language values are canonical BCP 47 tags such as `en` or `zh-CN`.
-Silvermoon resolves natural-language output in this order:
+Silvermoon resolves the language for project-owned content in this order:
 
 1. optional idea `status.yaml` `language`;
 2. optional project `.silvermoon/config.yaml` `preferredLanguage`;
@@ -67,7 +96,23 @@ 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.
-The shared observation reports the resolved non-empty language tag.
+That command continues to accept any canonical BCP 47 tag.
+
+For one invocation's Silvermoon-owned output, `whats-next` and `check` accept
+only the built-in `en-US` and `zh-CN` locales. Input casing is normalized, so
+`EN-us` and `zh-cn` are accepted. This override has higher display precedence
+than idea, project, or user content language and is never persisted:
+
+```sh
+silvermoon whats-next <idea> --language zh-CN
+silvermoon check --worktree --language en-US
+```
+
+Every observation reports the actual built-in locale as `outputLanguage`.
+When configuration is available, `configuration.preferredLanguage` remains
+the resolved content language and can therefore differ from `outputLanguage`.
+Without a temporary override, Chinese content tags use `zh-CN` output and all
+other content tags use the built-in `en-US` output.
 
 ## Create The First Idea
 
@@ -82,7 +127,10 @@ 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.
+`status.yaml`. If valid preparing guidance exists, the success report includes
+its snapshot-bound content. Invalid preparing guidance stops before any
+scaffold path is written. The command 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

package/docs/maintaining.md

@@ -62,4 +62,7 @@ Use [npm package releases](./npm-package-releases.md) for trusted publishing,
 tag rules, release validation, and failure recovery. Publishing occurs only
 through `.github/workflows/publish-npm.yml` from an immutable
 `npm/silvermoon/v<version>` tag whose commit is reachable from `origin/main`.
-Never publish locally or add an npm token.
+The workflow generates both package READMEs in an isolated staging tree,
+validates and publishes one tarball, then checks its registry integrity,
+package-level README, provenance, and commit-pinned jsDelivr assets. Never
+publish locally or add an npm token.

package/docs/npm-package-releases.md

@@ -11,7 +11,7 @@ The current release mapping is:
 | --- | --- | --- |
 | `silvermoon` | `silvermoon` | `.` |
 
-A stable tag such as `npm/silvermoon/v0.1.1` publishes with the npm `latest`
+A stable tag such as `npm/silvermoon/v0.1.3` publishes with the npm `latest`
 dist-tag. A named prerelease such as `npm/silvermoon/v0.2.0-beta.1` publishes
 with the `beta` dist-tag. Numeric-only prerelease channels are intentionally
 rejected.
@@ -76,12 +76,12 @@ the release namespace.
 5. Fetch the current primary branch and tags.
 6. Create the package-specific tag at `origin/main` and push that exact tag.
 
-For `silvermoon@0.1.1`:
+For `silvermoon@0.1.3`:
 
 ```sh
 git fetch origin main --tags
-git tag npm/silvermoon/v0.1.1 origin/main
-git push origin refs/tags/npm/silvermoon/v0.1.1
+git tag npm/silvermoon/v0.1.3 origin/main
+git push origin refs/tags/npm/silvermoon/v0.1.3
 ```
 
 The tag version must exactly equal [`package.json`](../package.json). The
@@ -92,13 +92,27 @@ The [`publish-npm.yml`](../.github/workflows/publish-npm.yml) workflow then:
 1. verifies the tagged commit is reachable from refreshed `origin/main`;
 2. installs the frozen pnpm dependencies;
 3. runs the allowlisted release planner and confirms the version is absent
-   from npm;
+   from npm, or records that an exact-version rerun must skip publication;
 4. runs `pnpm test:unit`, `pnpm test:contract`, `pnpm test:integration`, and
    `pnpm check:skills`;
-5. runs the selected package's `npm run pack:check` and
-   `npm run test:e2e`; and
-6. publishes only the selected directory with provenance and the derived npm
-   dist-tag.
+5. creates an isolated `git archive` staging tree and generates commit-pinned
+   English and Chinese package READMEs without changing the tagged checkout;
+6. records the tagged commit as `gitHead` in the isolated package manifest,
+   creates one tarball, records its path, SHA-256, npm shasum, registry
+   integrity, and complete file list, then passes that same file to
+   `npm run pack:check` and `npm run test:e2e`; the pre-publication check
+   requires the tarball manifest to contain that exact commit;
+7. publishes that exact tarball with provenance and the derived npm dist-tag
+   when the version was absent; and
+8. runs `verify-npm-release.mjs` until the registry is consistent or the
+   bounded retry window expires.
+
+The post-publication verifier requires the exact version and dist-tag, matching
+tarball and registry `gitHead`, registry integrity and tarball bytes,
+package-level README, both tarball READMEs, npm publish and SLSA provenance
+attestations, tagged Git commit, and commit-pinned jsDelivr SVG responses to
+match the candidate. A successful run prints `VERIFY_NPM_RELEASE_OK` with the
+verified identities.
 
 Release runs are serialized within this repository. The registry preflight and
 `npm publish` cannot form one cross-system transaction, so an external
@@ -110,13 +124,20 @@ duplicate publication without replacing the existing version.
 Publication stops before `npm publish` when the tag is malformed, the release
 key is unknown, the package is private, the package name or version differs
 from the mapping and tag, the npm publish configuration is not public npmjs,
-the commit is outside `origin/main`, the version already exists, registry state
-cannot be verified, or validation fails.
+the commit is outside `origin/main`, registry state cannot be observed, or
+validation fails. If the exact version already exists during a workflow rerun,
+the publish step is skipped and the verifier must prove that registry content
+is byte-identical to the rebuilt candidate and carries the expected provenance.
+Any mismatch is a hard failure.
 
 For a transient GitHub or registry failure before publication, rerun the same
 workflow run. Do not move or recreate the tag. For a source, manifest, or
 validation failure, make a new commit on `main`, choose a new version, and push
 a new tag after the fix is merged. npm versions and release tags are immutable.
+For a transient verification failure after publication, rerun only the failed
+workflow job when GitHub offers that option; the planner recognizes the
+existing version, skips `npm publish`, and performs the same complete
+verification again.
 
 ## Add another package
 

package/docs/operations.md

@@ -9,6 +9,7 @@ publishing Silvermoon ideas.
 npx silvermoon whats-next
 npx silvermoon whats-next 01M36QGPNTXEPP61DA4KP4AVZF
 npx silvermoon whats-next publish-documentation --json
+npx silvermoon whats-next publish-documentation --language zh-CN
 ```
 
 Without a selector, Silvermoon asks for a choice among multiple active ideas,
@@ -17,10 +18,13 @@ 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.
+The shared observation exposes the resolved content preference as
+`configuration.preferredLanguage` and the built-in rendering locale as
+`outputLanguage`. Instructions use the content preference for world entries,
+same-world supporting artifacts, and the ledger. A caller may use
+`--language en-US|zh-CN` to override only Silvermoon-owned output for one
+`whats-next` invocation. Commands, identifiers, schema fields, protocol
+markers, and verbatim tool output retain their original form.
 
 Every invocation follows three strict layers. It first checks Git,
 configuration compatibility, and `.agents/skills/silvermoon`. It then checks
@@ -29,6 +33,15 @@ 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.
 
+When a selector resolves to an actionable phase and synchronization is ready,
+Silvermoon reads only `.silvermoon/guidance/<phase>.md` from the same Git
+snapshot. Missing guidance preserves the previous report shape. Valid guidance
+appears as a separate `observation.guidance` value after canonical
+instructions in text output. Invalid current-phase guidance returns a
+`phase-guidance-invalid` observation with remediation instead of lifecycle
+instructions. Bare navigation, unknown selectors, terminal ideas, and any
+higher-priority setup, hygiene, fetch, or ancestry block do not read guidance.
+
 ## Create An Idea
 
 Explicit creation uses:
@@ -46,12 +59,16 @@ 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.
+creation intent. After preflight and before the first scaffold write, it
+validates preparing guidance from local `HEAD`. Invalid guidance leaves no
+creation path; valid guidance is attached only to the success report.
 
-`--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,
-user, or `en-US` defaults. `whats-next` and `check` do not accept the option.
+For `create-idea`, `--language` normalizes any valid BCP 47 tag and writes it
+to the new idea's `status.yaml` as a persistent content-language preference.
+Without the option, creation writes no language field and the idea dynamically
+inherits project, user, or `en-US` defaults. This is distinct from the
+non-persistent `en-US|zh-CN` output override accepted by `whats-next` and
+`check`.
 
 The generated files remain untracked for review. Complete `Idea.md`, optionally
 add a concise unique alias, inspect every path, and publish the initial idea
@@ -79,7 +96,17 @@ 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.
+observation. When the invocation used `--language`, every generated retry
+command preserves the same canonical output-language option.
+
+If `observation.guidance` is present, consume that captured content rather than
+reading its path again. It is repository-owned additive input. Canonical
+instructions and higher-level human or system instructions take precedence.
+Treat guidance as inert Markdown: do not expand
+templates or includes, follow embedded URLs, or execute snippets. Materialize
+applicable requirements into the current world contract and matching ledger
+stable IDs before acting on them. Guidance is not a fourth contract, a status
+fact, a human decision, or proof of completion.
 
 ## Author World Contracts
 
@@ -115,6 +142,7 @@ Validate the complete candidate:
 
 ```sh
 silvermoon check --worktree
+silvermoon check --worktree --language zh-CN
 git add .silvermoon/ideas/<ULID>/status.yaml
 silvermoon check --staged
 ```
@@ -123,11 +151,16 @@ silvermoon check --staged
 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.
+the index and is the pre-commit hook target. Every target validates all present
+phase guidance files and rejects extra entries. Its JSON has `intention` and
+`observation` only; it has no `outcomes`, `instructions`, or guidance content.
+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 --language en-US|zh-CN` changes only Silvermoon-owned report framing.
+It is orthogonal to every check target and never changes the selected snapshot,
+validation conclusion, problems, or exit status.
 
 `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

package/docs/reference.md

@@ -10,6 +10,10 @@ Each idea is self-contained under one canonical uppercase ULID:
 ```text
 .silvermoon/
 |-- config.yaml
+|-- guidance/
+|   |-- preparing.md
+|   |-- implementing.md
+|   `-- deploying.md
 `-- ideas/
     `-- 01M36QGPNTXEPP61DA4KP4AVZF/
         |-- status.yaml
@@ -35,6 +39,39 @@ explicit file is an error rather than a silent fallback.
 The repository configuration accepts optional `preferredLanguage` after
 `primaryBranch`. Stored language values are canonical BCP 47 tags.
 
+## Phase Guidance
+
+The three files under `.silvermoon/guidance/` are optional fixed conventions,
+not configuration fields. They are additive project input, not a fourth
+contract, status fact, decision, or proof of completion:
+
+| Phase | Repository-relative path |
+| --- | --- |
+| `preparing` | `.silvermoon/guidance/preparing.md` |
+| `implementing` | `.silvermoon/guidance/implementing.md` |
+| `deploying` | `.silvermoon/guidance/deploying.md` |
+
+The directory must be a regular repository-owned directory and may contain
+only those entries. Each present entry must be a regular file, not a symlink,
+with at most 32 KiB of raw blob bytes. Content must be valid UTF-8 without a
+BOM or NUL byte and must contain a non-whitespace character. CRLF is accepted
+and report content is normalized to LF. Silvermoon treats the body as inert
+Markdown: it does not parse frontmatter, interpolate values, resolve includes,
+fetch URLs, execute snippets, translate content, or write it to traces.
+
+Lifecycle commands use on-demand validation. Selected `whats-next` reads only
+the selected actionable phase after project, local repository, fetch, and
+ancestry readiness. `create-idea` reads only preparing guidance after local
+preflight and before writing any scaffold path. Errors in another phase and
+extra directory entries do not preempt those commands. Bare navigation,
+selector misses, completed or abandoned ideas, and readiness blocks do not
+read or return guidance.
+
+All `check` targets use complete validation: they reject any invalid phase file
+or extra entry in their selected HEAD, worktree, index, commit, or remote
+snapshot. A missing directory or missing phase file is valid. Checks never
+return guidance content.
+
 ## World Revisions
 
 Each world is an opaque Git tree:
@@ -67,13 +104,21 @@ world revision and does not change lifecycle decisions. Explicit
 `abandoned: false`, derived state, criteria mirrors, source locators, unknown
 keys, YAML aliases or anchors, comments, and noncanonical YAML are rejected.
 
-Effective language resolves as `idea language > project preferredLanguage >
-user preferredLanguage > en-US`. Every complete observation exposes the
-resolved non-empty tag as `configuration.preferredLanguage`. Missing idea
-language remains dynamically inherited and is never written back. Dialogue
-project status presents this effective value as `interaction language`
-(`交互语言`), meaning the language Silvermoon should use to interact with the
-user rather than a programming language used by the project.
+Effective content language resolves as `idea language > project
+preferredLanguage > user preferredLanguage > en-US`. Every complete
+observation exposes the resolved non-empty tag as
+`configuration.preferredLanguage`. Missing idea language remains dynamically
+inherited and is never written back. Dialogue project status presents this
+effective value as `content language` (`内容语言`).
+
+Every command observation also exposes an independent `outputLanguage`.
+Silvermoon's built-in output locales are exactly `en-US` and `zh-CN`.
+`whats-next --language <tag>` and `check --language <tag>` normalize casing
+before enforcing that allowlist, apply only to the current invocation, and
+take display precedence over content language. Without an explicit output
+override, content tags beginning with `zh` select `zh-CN`; every other content
+tag selects `en-US`. Output selection never writes configuration or idea
+status.
 
 State is derived in order:
 
@@ -88,9 +133,9 @@ State is derived in order:
 ## Public Commands
 
 ```sh
-silvermoon whats-next [idea] [--trace <file.trace.jsonl>]
+silvermoon whats-next [idea] [--language <en-US|zh-CN>] [--trace <file.trace.jsonl>]
 silvermoon create-idea [--language <tag>] [--trace <file.trace.jsonl>]
-silvermoon check [--remote | --commit <revision> | --staged | --worktree] [--trace <file.trace.jsonl>]
+silvermoon check [--remote | --commit <revision> | --staged | --worktree] [--language <en-US|zh-CN>] [--trace <file.trace.jsonl>]
 ```
 
 `whats-next` and `create-idea` build one dialogue envelope:
@@ -100,19 +145,24 @@ silvermoon check [--remote | --commit <revision> | --staged | --worktree] [--tra
   "intention": {
     "command": "whats-next",
     "args": {
-      "idea": null
+      "idea": null,
+      "language": null
     }
   },
-  "observation": {},
+  "observation": {
+    "outputLanguage": "en-US"
+  },
   "outcomes": [],
   "instructions": ""
 }
 ```
 
-- `intention` contains the command and normalized business arguments. Output
-  format is not part of the intention.
+- `intention` contains the command and normalized business arguments. For
+  `whats-next` and `check`, `args.language` is the canonical temporary output
+  override or `null`. Output format is not part of the intention.
 - `observation` describes the reliable facts for the requested command and
-  intent, not a mandatory global idea inventory.
+  intent, not a mandatory global idea inventory. `outputLanguage` is present
+  even when Git, configuration, or a requested snapshot is unavailable.
 - `outcomes` records only high-level repository side effects actually
   attempted by this invocation. Each item has `type`, `status` (`success` or
   `failure`), and `summary`. An empty array means no side effect was attempted.
@@ -120,6 +170,25 @@ silvermoon check [--remote | --commit <revision> | --staged | --worktree] [--tra
   readiness layer. A single remediation is plain text; multiple remediations
   are numbered in priority order.
 
+After readiness, an actionable selected idea or successful creation may add
+`guidance` to the command-specific observation:
+
+```json
+{
+  "guidance": {
+    "phase": "implementing",
+    "path": ".silvermoon/guidance/implementing.md",
+    "contentRevision": "<git-blob-object-id>",
+    "content": "Repository-owned Markdown captured from the snapshot.\n"
+  }
+}
+```
+
+`path`, `contentRevision`, and `content` come from one Git snapshot. The object
+ID follows the repository's SHA-1 or SHA-256 object format. Guidance never
+appears at the top level or inside canonical `instructions`, and an absent file
+does not produce an empty field.
+
 Default dialogue output renders the same report with concise lists under
 `## Current instruction`, `## Project status`, and `## Suggested next steps`
 (in Chinese: `## 本次指示`, `## 项目现状`, `## 下一步建议`). The optional
@@ -132,10 +201,13 @@ second reasoning path. Within the project-status section, nonempty navigation
 candidates and observed problems appear under `### Ideas you can continue` and
 `### Issues to address` (in Chinese: `### 可继续推进的想法` and
 `### 需要处理的问题`). Suggested next steps refer to these candidates without
-repeating their inventory. Empty sections are omitted. Dialogue exit status
-`0` means a trustworthy report was formed, even when it reports readiness
-blocks or a failed operation; `1` means an internal failure prevented a
-trustworthy report; `2` means invalid CLI usage.
+repeating their inventory. When guidance is present, a separate
+`## Project phase guidance` section follows suggested next steps, identifies
+its project provenance and metadata, and blockquotes every content line.
+Empty sections are omitted. Dialogue exit status `0` means a trustworthy
+report was formed, even when it reports readiness blocks or a failed
+operation; `1` means an internal failure prevented a trustworthy report; `2`
+means invalid CLI usage.
 
 All commands accept `--trace <file.trace.jsonl>`. If the supplied path does not
 end with the exact lowercase `.trace.jsonl` suffix, Silvermoon appends it while
@@ -150,7 +222,11 @@ stdout, or stderr. The path is relative to the caller's working directory when
 not absolute. Events are buffered so a trace inside the repository cannot
 affect that invocation's worktree observation. The file is written after the
 measured command work finishes and uses exclusive creation, so an existing
-normalized target is never overwritten.
+normalized target is never overwritten. The top command span records the
+canonical output-language override or `null` for `whats-next` and `check`.
+
+Unsupported output locales, empty values, and invalid BCP 47 tags are usage
+errors with exit status `2`, before repository inspection or fetch.
 
 Observations are discriminated by command intent and `state`:
 
@@ -167,12 +243,18 @@ Observations are discriminated by command intent and `state`:
 - Selected `whats-next` returns `idea-selected` with only `selectedIdea`
   (`id`, optional `alias`, lifecycle `state`), including terminal ideas.
   Unknown selectors return `idea-not-found` with `candidates`, not a
-  fabricated selected idea.
+  fabricated selected idea. An actionable selection may also contain
+  snapshot-bound `guidance`.
+- `phase-guidance-invalid` means command readiness reached the current
+  actionable phase, but that phase's optional file exists and is invalid. It
+  contains problems and repair instructions, not lifecycle instructions or
+  guidance content.
 - After a successful `create-idea` preflight, `idea-created` carries
   `createdIdea` (`id`, `path`, `state: "preparing"`). This confirms
-  pre-creation readiness, not a clean post-creation worktree. An attempted but
-  failed scaffold returns `idea-create-failed` without `createdIdea`; preflight
-  failures retain their setup or local preparation state.
+  pre-creation readiness, not a clean post-creation worktree, and may also
+  contain captured preparing `guidance`. An attempted but failed scaffold
+  returns `idea-create-failed` without `createdIdea`; preflight failures retain
+  their setup or local preparation state.
 
 Dialogue versions have `version.type: "worktree"`. When present, `ideas.counts` has
 `preparing`, `implementing`, `deploying`, `completed`, and `abandoned`;
@@ -196,11 +278,12 @@ never selects an idea: it always lists every active idea alongside the option
 to discuss and run `create-idea`.
 
 `create-idea` requires the configured primary branch and upstream plus a clean
-worktree, then creates one canonical scaffold. It does not fetch, compare
-remote ancestry, or require local HEAD to match the remote tip. Its optional
-language override is normalized before preflight and is the only command
-override; without it the status remains dynamically inherited. It does not
-stage, commit, push, or record approval.
+worktree, validates optional preparing guidance from the same local `HEAD`,
+then creates one canonical scaffold. It does not fetch, compare remote
+ancestry, or require local HEAD to match the remote tip. Its optional
+content-language choice accepts any canonical BCP 47 tag, is normalized before
+preflight, and is persisted to the new idea; without it the status remains
+dynamically inherited. It does not stage, commit, push, or record approval.
 
 ## Validation Targets
 
@@ -218,7 +301,8 @@ stage, commit, push, or record approval.
 Targets are mutually exclusive and never change the caller's branch, index, or
 worktree. `--remote` may fetch Git objects, but it does not produce dialogue
 outcomes. `check` validates the selected snapshot's project contract only:
-Git, configuration, canonical skill, idea layout, world revisions, and status.
+Git, configuration, canonical skill, idea layout, world revisions, status, and
+the complete optional phase guidance directory.
 Its result depends on the materialized tree, not commit parents, parent order,
 branch, merge/cherry-pick path, or retained decision reachability. A canonical
 decision revision that differs from the current world is a valid historical
@@ -233,12 +317,16 @@ Unlike dialogue commands, `check --json` contains **only** `intention` and
 {
   "intention": {
     "command": "check",
-    "args": { "target": { "type": "staged" } }
+    "args": {
+      "target": { "type": "staged" },
+      "language": null
+    }
   },
   "observation": {
     "state": "project-ready",
     "root": "D:\\Code\\silvermoon",
     "version": { "type": "staged" },
+    "outputLanguage": "en-US",
     "configuration": {
       "primaryRepository": "https://example.com/owner/repository.git",
       "primaryBranch": "main",
@@ -267,6 +355,10 @@ Unlike dialogue commands, `check --json` contains **only** `intention` and
 reports `commit: null` and a problem. Staged and worktree versions only
 contain `type`.
 
+`--language en-US|zh-CN` is orthogonal to every target. It changes only
+Silvermoon-owned natural-language framing and leaves the target, snapshot,
+validation state, problems, and exit status unchanged.
+
 The `check` observation has its own discriminated states:
 
 - `project-ready` has root, version, resolved configuration, idea summary,
@@ -286,9 +378,10 @@ internal failure and must fail closed; `2` means invalid CLI usage. Do not
 infer success merely from a rendered report or empty-looking output.
 
 Runtime checks verify canonical YAML, fixed paths, the three world entries,
-unique aliases, Git object format, current world tree resolution, and lifecycle
-derivation from the selected snapshot. They do not infer newly made decisions
-from a parent diff or audit decision provenance through history.
+unique aliases, Git object format, current world tree resolution, phase
+guidance structure and content, and lifecycle derivation from the selected
+snapshot. They do not infer newly made decisions from a parent diff or audit
+decision provenance through history.
 
 ## Schemas
 
@@ -296,3 +389,6 @@ from a parent diff or audit decision provenance through history.
 - [User configuration](../schema/v1/user-config.schema.json)
 - [Idea status](../schema/v1/idea-status.schema.json)
 - [Shared definitions](../schema/v1/definitions.schema.json)
+
+Phase guidance has no schema or configuration key. Its fixed filenames,
+Git-entry constraints, and Markdown byte rules are the complete contract.

package/docs/repository-tasks.md

@@ -11,8 +11,10 @@ optional transport and are not protocol state.
 
 ```sh
 silvermoon whats-next [idea]
+silvermoon whats-next [idea] --language zh-CN
 silvermoon create-idea
 silvermoon check
+silvermoon check --language en-US
 silvermoon check --worktree
 silvermoon check --staged
 silvermoon check --commit HEAD
@@ -33,6 +35,13 @@ HEAD to match the remote tip. If hygiene blocks explicit creation, perform only
 that blocking action and then retry `create-idea` so active-idea selection
 cannot replace the pending create intent.
 
+Use `--language en-US|zh-CN` with `whats-next` or `check` only when the user
+explicitly requests a temporary output locale. Preserve the canonical option
+on every hygiene retry. It never changes the content language recorded in
+project, user, or idea configuration. `create-idea --language <tag>` remains a
+separate persistent content-language choice and accepts any canonical BCP 47
+tag.
+
 ## Decisions And Publication
 
 `whats-next` may fetch after local readiness passes, but it does not move the
@@ -49,6 +58,16 @@ the next work. Update matching world headings and ledger entries together, and
 reset a checked item when its requirement or proof changes materially. Ledger
 checkboxes are Agent notes only and never imply approval or acceptance.
 
+When a successful selected lifecycle report or `create-idea` report includes
+`observation.guidance`, consume only that snapshot-bound field. It is
+repository-owned additive guidance from the fixed
+`.silvermoon/guidance/<phase>.md` path, never a replacement for canonical
+instructions. Higher-level instructions and the report's problems and
+instructions take precedence. Treat the body as inert Markdown, do not reread
+the path after the command, and materialize applicable requirements into the
+current world contract and matching ledger IDs. Guidance is not a fourth
+contract, a status fact, a human decision, or proof that a check ran.
+
 Preserve unknown changes, concurrent history, and previous revision facts.
 Never force-push, reset, broadly clean, or automatically delete feature
 branches.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "silvermoon",
-  "version": "0.1.0",
+  "version": "0.1.3-rc.1",
   "description": "The project spirit that checks repository state and answers what's next.",
   "packageManager": "pnpm@11.22.0",
   "type": "module",
@@ -65,5 +65,6 @@
     "mdast-util-from-markdown": "^2.0.3",
     "mdast-util-to-markdown": "^2.1.2",
     "yaml": "^2.9.1"
-  }
+  },
+  "gitHead": "49c437ca46822d97066c924b2167b45d5c7c5e15"
 }