silvermoon 0.2.1 → 0.3.0-rc.1

package/docs/getting-started.md

@@ -30,8 +30,8 @@ npx skills add <path-to-running-silvermoon>/skills --skill silvermoon --agent un
 
 If the repository root contains `package.json`, Silvermoon requires valid JSON
 and an exact `devDependencies.silvermoon` value of `^<running-version>`.
-Follow the setup report's package-manager-specific command, then install the
-root dependencies and register the project-local canonical skill:
+Follow all commands in the setup report in order; then register the
+project-local canonical skill:
 
 ```sh
 npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent universal --yes --copy
@@ -125,6 +125,14 @@ 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.
 
+The resolved content language applies to natural-language content throughout
+`Idea.md`, `Implementation.md`, `Deployment.md`, same-world supporting files,
+and `ledger.md`. Canonical headings, stable IDs, paths, CLI options, and schema
+fields are machine contracts and remain unchanged. `create-idea` localizes
+built-in English and Chinese scaffolds; for another canonical language tag its
+next step names the fallback template language and requires the Agent to
+replace every natural-language placeholder before continuing.
+
 ## Inspect The Local Idea Inventory
 
 Use the dedicated read-only query when the question is which ideas exist,
@@ -153,8 +161,8 @@ fetches or contacts the configured primary. Staged, unstaged, and untracked
 idea changes are therefore visible when they form a valid snapshot. Invalid
 query arguments fail with exit `2` before repository or trace access; an
 untrusted project or layout exits `1` instead of returning a partial list.
-The command has no temporary `--language` option and uses the project's
-resolved output language.
+Use `--language en|en-US|zh|zh-CN` to override only the output language for
+this invocation; without it, the project's resolved output language is used.
 
 ## Create The First Idea
 
@@ -191,13 +199,17 @@ Then ask what comes next with the generated ULID or an exact unique alias:
 silvermoon whats-next <idea>
 ```
 
-Default Markdown renders only the self-contained response. Add `--json` when a
-programmatic consumer needs the complete
-`intention / observation / actions / response` report. Read every problem and
-execute applicable `response.nextSteps` in order; `actions` contains only
-side effects Silvermoon already attempted. Run the same command again only
-after an expected repository change, an unexpected input change, or a newly
-arrived external result.
+The default human audience opens the bundled `tui-md` view only when stdin and
+stdout are both TTYs; press `q`, `Esc`, or `Ctrl+C` to exit. Pipes,
+redirections, and other non-TTY uses receive raw Markdown. Agents should add
+`--audience agent` to receive the same raw response Markdown even when attached
+to a TTY. Add `--json` when a programmatic consumer needs the complete
+`intention / observation / actions / response` report; an explicitly supplied
+`--audience` cannot be combined with `--json`. Read every problem and execute
+applicable `response.nextSteps` in order; `actions` contains only side effects
+Silvermoon already attempted. Run the same command again only after an expected
+repository change, an unexpected input change, or a newly arrived external
+result.
 
 ## Make Decisions Explicit
 

package/docs/maintaining.md

@@ -15,31 +15,108 @@ Use the smallest check that covers a change:
 
 ```sh
 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 check:sanity      # offline pure logic and lightweight contracts
+pnpm check:commit      # worktree tests plus staged metadata validation
+pnpm lint:markdown     # Markdown lint (contract tests check links)
+pnpm test              # complete unit/runtime and repository contracts
 pnpm test:integration  # real filesystem and Git behavior
 pnpm test:e2e          # packed and installed CLI behavior
 pnpm check             # complete release-grade validation
-pnpm check:skills      # skill discovery and structure
+pnpm check:release     # same complete release-grade validation
+pnpm check:skills:local # local skill copy consistency, no discovery
+pnpm check:skills      # local consistency and external skill discovery
 ```
 
+## Validation tiers
+
+| Scenario | Responsibility |
+| --- | --- |
+| Edit / Agent iteration | `check:sanity`: CLI syntax, pure unit tests, schema and API contracts; add change-specific tests |
+| Before commit | `check:commit`: sanity, local contracts and Markdown, skill consistency, Git/CLI smoke, whitespace, staged Silvermoon metadata |
+| Ordinary CI | Unconditional sanity then complete unit/runtime on Ubuntu/Windows/macOS, Node 22/24; complete contracts and integration, static checks and skill discovery |
+| Before delivery / release | `check` or `check:release`: every release-grade gate including package contents, installed-package E2E and external discovery |
+| After publication | The existing release workflow's `verify-npm-release.mjs`: registry identity, integrity, provenance, README and CDN |
+
+`test:unit` includes `test/runtime` so moving filesystem, Git and terminal
+tests out of sanity does not remove matrix coverage. `check:quick` retains its
+original syntax plus complete unit/runtime and contract meaning, not a new
+sanity alias. No assertions are duplicated into a second suite. The sanity
+worker guard rejects real child processes and network I/O; it does not block
+the Node test runner from creating workers. Terminal integration stays in
+runtime, outside sanity.
+
+Each CI matrix job runs the actual `pnpm check:sanity` entrypoint before the
+complete unit/runtime suite. Passing `test:unit` alone does not prove the
+sanity I/O boundary: it intentionally permits runtime tests. Tests that call
+real Git, even only to compare pure logic with Git's behavior, belong in
+`test/runtime`, not `test/unit`. Keep their assertions and platform coverage
+when splitting mixed-cost files; never disable the sanity guard to admit them.
+
+`check:commit` always prints its scope: tests validate the **worktree**, while
+`silvermoon check --staged` validates **staged Silvermoon metadata only**.
+With partial staging these are different candidates; a passing command does
+not prove staged code passed the tests. Align index and worktree and rerun
+before claiming exact-candidate evidence. The command never stages, stashes,
+installs a hook or changes Git configuration.
+
+CI adds package contents and installed-package E2E unless every changed path
+is known idea metadata under `.silvermoon/ideas/<ULID>/`. Everything else,
+including shipped docs, dependencies/locks, CLI entries, skills, tests,
+scripts, workflows and unknown paths, requires package validation. The
+selector uses the full base/head diff and both endpoints of renames; missing
+history, malformed or empty changes conservatively require validation with
+an explicit reason. Core jobs never use path filtering. Run
+`node scripts/ci-package-risk.mjs --full` to inspect the full decision;
+`workflow_dispatch` executes the full CI set, and local `check:release` always
+executes package/E2E regardless of the diff.
+
+`check:skills:local` needs no external discovery tool.
+`check:skills:discover` runs `npx skills add . --list` and can use the network;
+`check:skills` runs both in order. Missing tools and failed external checks
+are errors, not successful skips. No validation entrypoint publishes npm.
+
 `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.
 
+Each full check reports `CHECK_DURATION` for every gate and `CHECK_TOTAL` for
+the complete run. These values use a monotonic clock and are diagnostic, not
+machine-independent budgets. To compare performance, record the Node.js and
+pnpm versions and test counts, run `pnpm check` once to warm the checkout, then
+repeat it five times and compare the median under the same machine and checkout
+conditions. Keep each sample; do not count network, queueing, or cache
+fluctuations in installed-package smoke tests as code performance gains.
+
 Edit the canonical skill only under `skills/silvermoon`, then run
 `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`.
+For documentation and skill iteration, run `pnpm lint:markdown`,
+`pnpm check:skills:local`, and relevant contract tests; run external
+`pnpm check:skills` before skill delivery.
 
-Run `pnpm check` after CLI, schema, repository model, release, or skill changes.
+Run `pnpm check` before delivery of CLI, schema, repository model, release,
+or skill changes, not after every edit.
 Documentation work must also preserve Markdown links, package contents,
 installed-package rendering surfaces, and `git diff --check`.
 
+## GitHub Actions Dependencies
+
+Every external action under `.github/workflows` is pinned to a full commit SHA
+with its exact semantic version in an inline comment. Never replace a pin with
+a movable major tag. Dependabot checks the `github-actions` ecosystem weekly
+and proposes reviewable SHA/version updates; do not auto-merge those PRs.
+Review the upstream release and action ownership, then require the complete CI
+gate before merging.
+
+The branch ruleset depends only on the stable `Required checks` job name. That
+aggregate job fails unless package-risk selection, unit, contract, and
+integration jobs succeed, and it requires package validation to succeed when
+risk selection enables it. Keep this name and fail-closed behavior synchronized
+with `.github/rulesets/main.json`.
+
 ## Documentation Ownership
 
 - [Getting Started](./getting-started.md) owns installation, configuration,

package/docs/npm-package-releases.md

@@ -64,7 +64,8 @@ the release namespace.
 ## Publish a version
 
 1. Update the selected package's `version` in its committed `package.json`.
-2. Run `pnpm install --frozen-lockfile` and `pnpm check`. The complete check
+2. Run `pnpm install --frozen-lockfile` and `pnpm check` (or `pnpm check:release`).
+   Neither validation command publishes a package. The complete check
    includes unit, contract, integration, package contents, installed-package
    E2E, and skill discovery.
 3. Merge the version change to `main`; do not tag an unmerged branch or local
@@ -95,9 +96,16 @@ The [`publish-npm.yml`](../.github/workflows/publish-npm.yml) workflow then:
 3. runs the allowlisted release planner and confirms the version is absent
    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`;
+   `pnpm check:skills`, Markdown/whitespace and checked-out Silvermoon snapshot
+   validation, all unconditionally;
 5. creates an isolated `git archive` staging tree and generates commit-pinned
    English and Chinese package READMEs without changing the tagged checkout;
+   the repository READMEs use canonical `./assets/...` image paths so branch,
+   pull-request, and local previews show the current checkout, while staging
+   converts those images to release-commit-pinned jsDelivr URLs and converts
+   ordinary relative document links to commit-pinned GitHub blob URLs;
+   repository artwork remains available at those immutable URLs but is
+   excluded from the npm tarball;
 6. records the tagged commit as `gitHead` and the canonical `README.md` content
    in the isolated package manifest, creates one tarball, records its path,
    SHA-256, npm shasum, registry integrity, and complete file list, then passes
@@ -114,8 +122,12 @@ The [`publish-npm.yml`](../.github/workflows/publish-npm.yml) workflow then:
 
 The post-publication verifier requires the exact version and dist-tag, matching
 tarball and registry `gitHead`, registry integrity and tarball bytes, both
-tarball READMEs, npm publish and SLSA provenance attestations, tagged Git
-commit, and commit-pinned jsDelivr SVG responses to match the candidate.
+tarball READMEs, MIT license, homepage, bugs and repository metadata, npm
+publish and SLSA provenance attestations, tagged Git commit, and commit-pinned
+jsDelivr SVG responses to match the candidate.
+README generation rejects traversal, non-canonical paths, and relative resources
+outside the approved `./assets/...` image namespace rather than guessing a
+published destination.
 Releases on the `latest` dist-tag additionally require npm's package-level
 README to match the candidate; prerelease channels leave that `latest` package
 page state unchanged. A successful run prints `VERIFY_NPM_RELEASE_OK` with the
@@ -126,6 +138,23 @@ Release runs are serialized within this repository. The registry preflight and
 publisher could still win that interval; npm then atomically rejects the
 duplicate publication without replacing the existing version.
 
+### GitHub Release
+
+Prepare release notes in the repository before creating the immutable tag.
+After the trusted-publishing workflow succeeds and its verifier proves the npm
+result, create the GitHub Release from the already-existing tag. For `0.3.0`:
+
+```sh
+gh release create npm/silvermoon/v0.3.0 \
+  --verify-tag \
+  --title "Silvermoon 0.3.0" \
+  --notes-file .github/release-notes/0.3.0.md
+```
+
+Do not let a release command create, move, or replace the tag. The GitHub
+Release, npm version, provenance, changelog, and release notes must resolve to
+the same commit before deployment acceptance.
+
 ## Failure behavior
 
 Publication stops before `npm publish` when the tag is malformed, the release

package/docs/operations.md

@@ -22,7 +22,7 @@ The shared observation exposes the resolved content preference as
 `configuration.preferredLanguage` and the built-in rendering locale as
 `outputLanguage`. Response next steps 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
+`--language en|en-US|zh|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.
 
@@ -103,8 +103,8 @@ 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`.
+non-persistent `en|en-US|zh|zh-CN` output override accepted by `list-ideas`,
+`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
@@ -118,9 +118,13 @@ unpublished local candidate, and never treat publication as approval.
 ## Follow One Report
 
 Treat `intention`, `observation`, `actions`, and `response` as one immutable
-report for every command. Default output renders only `response`; `--json`
-serializes all four projections and retains `actions: []` when no side effect
-was attempted. Actions are historical facts. Future work appears only in
+report for every command. The implicit `human` audience uses the bundled
+`tui-md` view only when both stdin and stdout are TTYs; `q`, `Esc`, and
+`Ctrl+C` exit the view. Human pipelines and redirections receive raw response
+Markdown. `--audience agent` always emits that raw Markdown without TUI control
+sequences. `--json` serializes all four projections and retains `actions: []`
+when no side effect was attempted; an explicit `--audience` conflicts with
+`--json`. Actions are historical facts. Future work appears only in
 `response.nextSteps`.
 
 Project setup takes precedence over repository synchronization, which takes
@@ -195,7 +199,7 @@ returned. 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.
+`check --language en|en-US|zh|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.
 

package/docs/reference.md

@@ -112,13 +112,24 @@ 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.
+Silvermoon's built-in output locales are `en-US` and `zh-CN`; short aliases
+`en` and `zh` are accepted and normalize to those locales.
+`list-ideas`, `whats-next`, and `check` accept `--language
+<en|en-US|zh|zh-CN>`, normalize casing, and apply the override only to the
+current invocation. It takes 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.
+
+The effective content language governs natural-language prose, comments,
+short titles, and placeholders in all three world contracts, their same-world
+supporting files, and `ledger.md`. Canonical headings, stable IDs, paths, CLI
+options, and schema fields remain unchanged. `create-idea` provides localized
+scaffolds for built-in English and Chinese templates; for another canonical
+BCP 47 tag it reports the explicit fallback template language and requires the
+Agent to replace natural-language placeholders with the effective content
+language. Selected-idea `whats-next` instructions repeat the effective content
+language even when a temporary output-language override is active.
 
 State is derived in order:
 
@@ -130,13 +141,27 @@ State is derived in order:
    `deploymentRevision`.
 5. `completed` when all three revisions match.
 
+## Experimental JavaScript Package API
+
+The package root export is available for programmatic reuse, but remains
+experimental for every Silvermoon `0.x` release. A minor release before
+`1.0.0` may add, remove, rename, or change exported JavaScript functions and
+classes without a deprecation period. Patch releases are intended for
+compatible fixes. Consumers that import from `silvermoon` should pin the exact
+package version and review the changelog before upgrading.
+
+This boundary applies only to the root JavaScript export. The CLI, versioned
+JSON Schemas, trace versions, and repository file contracts keep their own
+documented compatibility rules. The package does not yet promise stable
+TypeScript declarations or a stable `1.0.0` JavaScript API.
+
 ## Public Commands
 
 ```sh
-silvermoon list-ideas [--state <state>] [--all] [--query <text>] [--created-since <RFC3339>] [--created-before <RFC3339>] [--sort <newest|oldest>] [--limit <positive-integer>] [--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] [--language <en-US|zh-CN>] [--trace <file.trace.jsonl>]
+silvermoon list-ideas [--state <state>] [--all] [--query <text>] [--created-since <RFC3339>] [--created-before <RFC3339>] [--sort <newest|oldest>] [--limit <positive-integer>] [--language <en|en-US|zh|zh-CN>] [--audience <human|agent>] [--trace <file.trace.jsonl>]
+silvermoon whats-next [idea] [--language <en|en-US|zh|zh-CN>] [--audience <human|agent>] [--trace <file.trace.jsonl>]
+silvermoon create-idea [--language <tag>] [--audience <human|agent>] [--trace <file.trace.jsonl>]
+silvermoon check [--remote | --commit <revision> | --staged | --worktree] [--language <en|en-US|zh|zh-CN>] [--audience <human|agent>] [--trace <file.trace.jsonl>]
 ```
 
 Every valid invocation starts one ordered domain-message stream with
@@ -211,11 +236,40 @@ neither field. The public observation intentionally omits content so the
 response is the only rendered payload while still remaining a deterministic
 projection.
 
-Default Markdown renders only `response`, never the intention, observation, or
-action history. It begins with the answer, then includes only relevant idea
-references, inventory details, validation details, problems, next steps, and
-blockquoted guidance. `--json` serializes the four projections from the same
-domain stream; there is no YAML output or second reasoning path. A trustworthy
+Audience selection is independent of report construction. When `--audience` is
+omitted, the audience is `human`: stdin and stdout must both be TTYs for the
+bundled `tui-md` view to start. That view supports scrolling; drag to select
+text and press `y` to copy it. On local Windows terminals, the built-in
+PowerShell clipboard command is used when the terminal clipboard protocol is
+unavailable. Copy feedback temporarily replaces the shortcut hint, using a
+muted green for success or amber for problems, then clears after about three
+seconds without shifting the document. If copying fails, the
+view displays a diagnostic; terminal-native selection may be available with
+Shift+drag. Exit with `q`, `Esc`, or `Ctrl+C`.
+The TUI document uses the available terminal width rather than a fixed
+100-column limit. Tables that fit the view measure Chinese characters by
+terminal cells so wide screens do not wrap otherwise-fitting columns; tables
+too wide for the screen retain horizontal navigation.
+If either stream is not a TTY, human output is raw
+Markdown. `--audience agent` always emits raw Markdown without TUI control
+sequences. On Windows, TUI frames use Node's terminal stream for UTF-8 output
+without changing the console code page. Both Markdown paths render only
+`response`, never the intention, observation, or action history, and derive their
+content from the same command report. They begin with the answer, then include
+only relevant idea references,
+inventory details, validation details, problems, next steps, and blockquoted
+guidance. Text reports render problems as a Markdown table. `list-ideas` and
+`whats-next` active choices use the same `Alias / ID`, state, created, title
+columns: an alias replaces the ID in that column when present. Structured
+dates in these lists and any displayed creation-time filter bounds are short
+relative times (just now, minutes, hours, days); after seven days they show a
+local calendar date without a time.
+Future dates are labelled as upcoming, not as elapsed. JSON retains exact
+UTC timestamps and all filtering still uses the exact values.
+
+`--json` without an explicitly selected audience serializes the four
+projections from the same domain stream; explicit `--json --audience ...` is a
+usage error. There is no YAML output or second reasoning path. A trustworthy
 blocked report still exits `0` for `whats-next` and `create-idea`.
 `list-ideas` exits `0` only for a trustworthy inventory (including an empty
 result) and exits `1` for setup or layout unavailability. `check` exits `0`
@@ -235,15 +289,53 @@ monotonic `sequence`, and UTC timestamp:
 - `channel: "telemetry"` records paired `span-start` and `span-end` events,
   parent span IDs, monotonic `durationMs`, and success or error status.
 
-Action telemetry carries the corresponding action ID. Trace projection never
-includes guidance or file content, Git arguments/stdout/stderr, environment
-data, credentials, tokens, or unbounded error text. Turning trace off, replacing
-the domain sink with a no-op, or deleting every telemetry event does not change
-the domain stream or final report. 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 measured command work finishes and uses exclusive creation, so
-an existing normalized target is never overwritten.
+The root `command.*` span starts after Commander has parsed the invocation and
+covers domain dispatch through JSON or Markdown output. Its safe attributes
+identify the renderer; executable invocations also include the monotonic
+`bootstrapDurationMs` from process entry through dispatch. Non-interactive
+output has a child `output.render` span. Human TUI rendering remains outside
+the command span so waiting for input is not reported as automated command
+work.
+
+Action telemetry carries the corresponding action ID. All production
+subprocesses use the trace-aware runner. Git subprocesses emit `git.command`
+with only the subcommand, argument count, network classification, exit code,
+and signal; neither Git arguments nor process input or output are recorded.
+Trace projection never includes guidance or file content, environment data,
+credentials, tokens, or unbounded error text. Turning trace off, replacing the
+domain sink with a no-op, or deleting every telemetry event does not change the
+domain stream or final report.
+
+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. After the command span ends, a root
+`trace.flush` span covers exclusive file creation and the durable write of all
+preceding events; its final span-end record is appended as the trace trailer.
+Flush and close failures are returned as command errors. An existing normalized
+target is never overwritten.
+
+### Reproducible performance traces
+
+Performance comparisons use a disposable clean clone pinned to one commit and
+tree on the same machine and storage volume. When a command needs the primary,
+map the canonical primary URL to a local bare repository with Git `insteadOf`;
+do not replace the configured URL or skip the command's normal fetch. Prove the
+clone clean before and after every sample. For `create-idea`, remove only the
+exact idea path returned by that sample, then prove the clone clean again.
+
+Benchmark this matrix: default and `--all` inventory; bare and selected aligned
+navigation; creation; and HEAD, staged, worktree, and remote checks. Run one
+unrecorded warm-up followed by five independent JSON invocations with unique
+trace files. Retain every measured sample rather than removing network, cache,
+or timing outliers.
+
+Use the matching `command.*` span-end duration as total command work. Network
+duration is the sum of child `git.command` span-end durations whose safe
+`network` attribute is `true`; subtract that sum from each individual total
+before calculating a non-network median. Report all five totals, all five
+network/non-network decompositions where applicable, median, minimum, maximum,
+Git process count, `snapshot.materialize*` count, and inventory candidate/title
+read counts. Keep raw traces outside the measured repository.
 
 Unsupported output locales, empty values, invalid BCP 47 tags, and invalid
 `list-ideas` filters are usage errors with exit status `2`, before repository
@@ -260,12 +352,16 @@ Observations are discriminated by command intent and `state`:
   safety checks fail. It includes `root`, `version`, `configuration`, and at
   least one `problem`, but no idea inventory or remote synchronization facts.
 - Bare `whats-next` returns `navigation-ready` with `ideas.counts` and
-  `ideas.activeIdeas` (possibly empty). It never selects a candidate.
+  `ideas.activeIdeas` (possibly empty). Each active item includes `id`,
+  lifecycle `state`, UTC `createdAt`, and optional alias/title read from the
+  current idea document; missing titles render as `-`. It never selects a
+  candidate.
 - 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. An actionable selection may also contain
-  snapshot-bound guidance provenance; captured content is in the response.
+  Unknown selectors return `idea-not-found` with the same enriched active
+  `candidates`, not a fabricated selected idea. An actionable selection may
+  also contain snapshot-bound guidance provenance; captured content is in
+  the response.
 - `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
@@ -287,7 +383,8 @@ Observations are discriminated by command intent and `state`:
 
 Dialogue versions have `version.type: "worktree"`. When present, `ideas.counts` has
 `preparing`, `implementing`, `deploying`, `completed`, and `abandoned`;
-`activeIdeas` contains only minimal references for the first three states.
+`activeIdeas` contains only minimal references for the first three states
+outside navigation; navigation enriches those references after readiness.
 Problems have only stable `type` and natural-language `summary`; remediation
 belongs in `response.nextSteps`.
 
@@ -328,7 +425,9 @@ The query validates Git presence, configuration, canonical skill, and the
 complete idea layout before filtering. It reads staged, unstaged, and
 untracked idea changes from the current worktree snapshot but never checks
 worktree hygiene, branch, upstream, or primary ancestry, and never fetches or
-accesses the network. It has no temporary `--language` option.
+accesses the network. `list-ideas --language <en|en-US|zh|zh-CN>` overrides only
+Silvermoon-owned output for that invocation; without it, the project's
+resolved output language is used.
 
 ## Validation Targets
 
@@ -411,7 +510,7 @@ Like every public command, `check --json` contains all four projections:
 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
+`--language en|en-US|zh|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.
 

package/docs/repository-tasks.md

@@ -28,7 +28,9 @@ primary moves, reobserve instead of replaying approval or acceptance.
 Choose the entry command from the user's intent. Explicit inventory requests
 use `silvermoon list-ideas`; explicit new-idea requests use
 `silvermoon create-idea` even when unrelated active ideas exist; all navigation
-uses `silvermoon whats-next [idea]`. Add `--json` only for a programmatic
+uses `silvermoon whats-next [idea]`. Agents should append `--audience agent`
+to report commands and hygiene retries to avoid the human TUI on dual-TTY
+streams. Add `--json` instead only for a programmatic
 consumer. All three apply the same project and complete idea-layout checks,
 but their repository readiness differs. `list-ideas` reads the valid local
 worktree snapshot without hygiene, branch, upstream, network, or ancestry
@@ -39,21 +41,37 @@ 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.
+Use `--language en|en-US|zh|zh-CN` with `list-ideas`, `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
+## Decisions And Synchronization
 
 `whats-next` may fetch after local readiness passes, but it does not move the
 worktree, index, branches, or named refs. Human approvals, implementation
 acceptance, deployment acceptance, and abandonment are ordinary edits to one
-idea `status.yaml` after an explicit decision. Validate the candidate and
-publish a normal non-force commit. Prefer status-only decision commits when
-practical.
+idea `status.yaml` after an explicit decision.
+
+Before requesting a human decision, validate the candidate, synchronize its
+normal non-force commit to primary, confirm reachability from the refreshed
+primary, and reobserve the exact world revision and effective content language.
+This synchronization is Agent work and does not require a lifecycle decision.
+Keep the review message short: use that language to state the review focus and
+exact decision question, and provide local plus commit-pinned remote links to
+the canonical contract, same-world supporting files, ledger, evidence, and key
+deliverables. Durable detail belongs in those repository files, not in the
+chat message. Render this index as ordinary assistant Markdown. When using an
+interactive decision tool, put only the exact question and choices in that
+tool; local workspace links in tool-owned surfaces may fail even when the
+files exist. In VS Code on Windows, ordinary-message local links use absolute
+drive paths with forward slashes and never `file://` URIs.
+
+After an explicit decision, change only the corresponding status fact,
+validate it, prefer a status-only commit when practical, synchronize it to
+primary, and reobserve the resulting lifecycle state.
 
 The required idea-root `ledger.md` is the Agent continuation surface. After
 repository hygiene and lifecycle routing, combine the reported
@@ -80,12 +98,18 @@ branches.
 
 ## Repository Checks
 
-- Run `pnpm test` for the fast unit-and-contract developer suite.
+- Iterate with `pnpm check:sanity` and change-specific tests. Run
+  `pnpm check:commit` before committing; see the
+  [validation tiers](./maintaining.md#validation-tiers).
+- `pnpm test` and `pnpm check:quick` retain the complete unit/runtime and
+  contract suites, including real runtime behavior; they are not sanity aliases.
 - Run `pnpm test:integration` for real filesystem and Git behavior, and
   `pnpm test:e2e` for the installed package.
-- Run `pnpm check` after CLI, schema, repository model, release, or skill
-  changes; it remains the complete release-grade validation entrypoint.
-- Run `pnpm check:skills` after skill changes.
+- Run `pnpm check` (or `pnpm check:release`) before delivery of CLI, schema,
+  repository model, release, or skill changes. It remains the complete
+  release-grade validation entrypoint, not the per-edit default.
+- Run `pnpm check:skills:local` while editing skills and `pnpm check:skills`
+  before delivery; external discovery failures remain failures.
 - Validate package contents, installed-package smoke behavior, Markdown links,
   and `git diff --check` before delivery review.
 - Use `silvermoon check --commit HEAD` for checked-out CI and
@@ -96,3 +120,7 @@ branches.
   Only exit code `0` permits the commit; `1` means invalid or unavailable and
   `2` means invalid usage. Its JSON uses all four projections; only
   `check --remote` normally records an action.
+- `check:commit` does not install a hook or stage files. Its tests inspect the
+  worktree while `check --staged` inspects Silvermoon metadata in the index.
+  Partial staging is not exact-candidate test evidence; align worktree and
+  index and rerun before claiming staged code passed.