silvermoon 0.1.3 → 0.2.0-rc.1

package/docs/reference.md

@@ -133,12 +133,21 @@ State is derived in order:
 ## 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>]
 ```
 
-`whats-next` and `create-idea` build one dialogue envelope:
+Every valid invocation starts one ordered domain-message stream with
+`intention.accepted`. Observation facts are folded through one immutable
+reducer. Side effects are represented by exactly one `action.requested` and
+one `action.finished` message with the same run-local action ID. A final
+`response.created` message is emitted only after the observation is terminal
+and no action is pending.
+
+All successful and trustworthy blocked commands return exactly four
+projections:
 
 ```json
 {
@@ -152,81 +161,93 @@ silvermoon check [--remote | --commit <revision> | --staged | --worktree] [--lan
   "observation": {
     "outputLanguage": "en-US"
   },
-  "outcomes": [],
-  "instructions": ""
+  "actions": [],
+  "response": {
+    "kind": "choice-required",
+    "language": "en-US",
+    "summary": "No active ideas are available.",
+    "choices": [],
+    "nextSteps": []
+  }
 }
 ```
 
 - `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.
+  override or `null`. For `list-ideas`, args contain the expanded canonical
+  state set, normalized UTC bounds, sort, and numeric limit. 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. `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.
-- `instructions` contains all ordered next-step guidance for the current
-  readiness layer. A single remediation is plain text; multiple remediations
-  are numbered in priority order.
+- `actions` projects only side effects already attempted by this invocation.
+  Each item has a unique `id`, stable `type`, `success` or `failure` status,
+  and a structured `result` or `problem`. An empty array means no side effect
+  was attempted. Probes and future work do not appear here.
+- `response` is a command-specific discriminated union produced only from the
+  intention and final internal observation. Its variants are `blocked`,
+  `choice-required`, `idea-created`, `idea-list`, `next-steps`, and
+  `validation-result`. It contains the localized summary and any ordered
+  `nextSteps`, choices, items, validation result, or guidance needed by the
+  caller.
 
 After readiness, an actionable selected idea or successful creation may add
-`guidance` to the command-specific observation:
+content-free `guidance` provenance to the public observation:
 
 ```json
 {
   "guidance": {
     "phase": "implementing",
     "path": ".silvermoon/guidance/implementing.md",
-    "contentRevision": "<git-blob-object-id>",
-    "content": "Repository-owned Markdown captured from the snapshot.\n"
+    "contentRevision": "<git-blob-object-id>"
   }
 }
 ```
 
-`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
-`## Actions and results` (`## 本次操作及结果`) appears only when a visible
-outcome remains. A successful fetch is omitted from text when local HEAD
-matches the fetched primary; failed fetches and synchronization problems remain
-visible. JSON always records attempted outcomes, even when text omits routine
-success. `--json` serializes the same decision; there is no YAML output or
-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. 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.
+The matching `response.guidance` carries the same three provenance fields plus
+the captured `content`. All fields come from one Git snapshot, and the object
+ID follows the repository's SHA-1 or SHA-256 format. An absent file produces
+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
+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`
+only for a valid snapshot and otherwise exits `1`. Internal failures also exit
+`1`; invalid CLI usage exits `2`.
 
 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
 preserving the directory and original name. Repository-local `*.trace.jsonl`
 files are ignored by the canonical repository. The trace is newline-delimited
-JSON with paired `span-start` and `span-end` events, UTC timestamps, monotonic
-`durationMs`, parent span IDs, and success or error status. It covers the
-command, snapshot observation, adoption, user configuration, idea layout,
-repository readiness, temporary snapshot materialization, and individual Git
-commands. Git events record the subcommand and result but not command arguments,
-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. 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.
+JSON using trace schema version 2. Every record shares one `traceId`, global
+monotonic `sequence`, and UTC timestamp:
+
+- `channel: "domain"` records allowlisted summaries of intention,
+  observation transitions, action lifecycle, and response metadata. It
+  includes domain `messageSequence` for replay correlation.
+- `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.
+
+Unsupported output locales, empty values, invalid BCP 47 tags, and invalid
+`list-ideas` filters are usage errors with exit status `2`, before repository
+inspection, trace creation, or fetch.
 
 Observations are discriminated by command intent and `state`:
 
@@ -244,7 +265,7 @@ Observations are discriminated by command intent and `state`:
   (`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`.
+  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
@@ -252,15 +273,23 @@ Observations are discriminated by command intent and `state`:
 - 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, 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.
+  contain preparing-guidance provenance. An attempted but failed scaffold
+  returns `idea-create-failed` without `createdIdea`, records separate
+  scaffold and cleanup actions, and exposes cleanup facts; preflight failures
+  retain their setup or local preparation state.
+- Successful `list-ideas` returns `ideas-listed`. Its observation contains the
+  normalized snapshot facts, all-five-state counts for the filtered set,
+  matched/returned/truncated totals, and ordered items with ID, lifecycle
+  state, UTC `createdAt`, and optional alias/title. Its empty `actions` and
+  `idea-list` response are deterministic projections of the same command run.
+  Setup or layout failures remain cumulative `project-setup-required`
+  observations and never return a partial inventory.
 
 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.
 Problems have only stable `type` and natural-language `summary`; remediation
-belongs in dialogue `instructions`.
+belongs in `response.nextSteps`.
 
 Project setup is ecosystem-neutral. It checks Git, configuration schema
 compatibility, and canonical skill content at `.agents/skills/silvermoon`.
@@ -286,6 +315,21 @@ 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.
 
+`list-ideas` is a local worktree query, not lifecycle navigation. With no
+filters it selects the three active states. Repeated `--state` values form a
+deduplicated union and `active` expands to those states; `--all` selects all
+five states and is mutually exclusive with `--state`. Case-insensitive literal
+`--query` matches ID, alias, or the first level-one `Idea.md` heading. RFC 3339
+creation bounds use `[created-since, created-before)` against the timestamp
+encoded in each ULID. Sorting defaults to stable newest-first, and limit is
+applied after filtering and sorting without changing matched counts.
+
+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.
+
 ## Validation Targets
 
 - `check` validates only the committed `HEAD` snapshot. It is not a
@@ -300,8 +344,8 @@ dynamically inherited. It does not stage, commit, push, or record approval.
   locating and validating the remote snapshot.
 
 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:
+worktree. `--remote` may fetch Git objects and records that attempt as an
+action. `check` validates the selected snapshot's project contract only:
 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,
@@ -311,8 +355,7 @@ fact and naturally derives an earlier lifecycle state; it need not still exist
 in the local object database. `check` does not check local worktree cleanliness,
 upstream, or ancestry readiness, route ideas, or give next-step instructions.
 
-Unlike dialogue commands, `check --json` contains **only** `intention` and
-`observation`:
+Like every public command, `check --json` contains all four projections:
 
 ```json
 {
@@ -344,6 +387,18 @@ Unlike dialogue commands, `check --json` contains **only** `intention` and
       "activeIdeas": []
     },
     "problems": []
+  },
+  "actions": [],
+  "response": {
+    "kind": "validation-result",
+    "language": "en-US",
+    "summary": "The requested Silvermoon snapshot is valid.",
+    "validation": {
+      "target": { "type": "staged" },
+      "valid": true,
+      "version": { "type": "staged" }
+    },
+    "problems": []
   }
 }
 ```
@@ -370,13 +425,13 @@ The `check` observation has its own discriminated states:
   when the target cannot be resolved, fetched, or materialized; it does not
   pretend the project was checked.
 
-There are no `outcomes` or `instructions` keys in a check report. Its default
-human-readable output gives only the target, validation conclusion, and
-problems, not the dialogue's four sections. Text and JSON derive from the same
-validation result. Exit code `0` means `project-ready` and is the **only**
-pre-commit/CI pass condition. Exit code `1` means invalid, unavailable, or an
-internal failure and must fail closed; `2` means invalid CLI usage. Do not
-infer success merely from a rendered report or empty-looking output.
+Its default human-readable output renders only the validation response. Text
+and JSON derive from the same validation result. `actions` is empty for local
+targets and contains the paired fetch result for `--remote`. Exit code `0`
+means `project-ready` and is the **only** pre-commit/CI pass condition. Exit
+code `1` means invalid, unavailable, or an 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, phase
@@ -386,10 +441,13 @@ decision provenance through history.
 
 ## Schemas
 
+- [Command report](../schema/v1/command-report.schema.json)
+- [Domain message](../schema/v1/domain-message.schema.json)
 - [Repository configuration](../schema/v1/config.schema.json)
 - [User configuration](../schema/v1/user-config.schema.json)
 - [Idea status](../schema/v1/idea-status.schema.json)
 - [Shared definitions](../schema/v1/definitions.schema.json)
+- [Unified trace event](../schema/v2/trace-event.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

@@ -10,6 +10,7 @@ The shared authority is `https://github.com/shazhou-ww/silvermoon.git` on
 optional transport and are not protocol state.
 
 ```sh
+silvermoon list-ideas
 silvermoon whats-next [idea]
 silvermoon whats-next [idea] --language zh-CN
 silvermoon create-idea
@@ -24,16 +25,19 @@ silvermoon check --remote
 Use the primary commit stated in the report as the expected remote tip. When
 primary moves, reobserve instead of replaying approval or acceptance.
 
-Choose the entry command from the user's intent. Explicit new-idea requests use
+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
-consumer. Both commands apply the
-same project checks, but their repository readiness differs. `whats-next`
-checks local hygiene and remote ancestry. `create-idea` requires the configured
-primary branch and upstream plus a clean worktree, without fetching or requiring
-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.
+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
+checks. `whats-next` checks local hygiene and remote ancestry. `create-idea`
+requires the configured primary branch and upstream plus a clean worktree,
+without fetching or requiring 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
@@ -52,21 +56,23 @@ publish a normal non-force commit. Prefer status-only decision commits when
 practical.
 
 The required idea-root `ledger.md` is the Agent continuation surface. After
-repository hygiene and lifecycle routing, combine the reported instructions, world
-contracts, and unchecked Implementation or Deployment ledger entries to infer
-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.
+repository hygiene and lifecycle routing, combine the reported
+`response.nextSteps`, world contracts, and unchecked Implementation or
+Deployment ledger entries to infer 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.
+`response.guidance`, consume only that snapshot-bound field.
+`observation.guidance` is its content-free provenance. It is repository-owned
+additive guidance from the fixed `.silvermoon/guidance/<phase>.md` path, never
+a replacement for canonical `response.nextSteps`. Higher-level instructions,
+the report's problems, and `response.nextSteps` 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
@@ -88,5 +94,5 @@ branches.
   committed `HEAD`, not the pending index. `check` validates only the chosen
   project's snapshot, not repository synchronization or idea navigation.
   Only exit code `0` permits the commit; `1` means invalid or unavailable and
-  `2` means invalid usage. Its JSON contains `intention` and `observation`,
-  not dialogue `outcomes` or `instructions`.
+  `2` means invalid usage. Its JSON uses all four projections; only
+  `check --remote` normally records an action.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "silvermoon",
-  "version": "0.1.3",
+  "version": "0.2.0-rc.1",
   "description": "The project spirit that checks repository state and answers what's next.",
   "packageManager": "pnpm@11.22.0",
   "type": "module",
@@ -66,7 +66,7 @@
     "mdast-util-to-markdown": "^2.1.2",
     "yaml": "^2.9.1"
   },
-  "gitHead": "36f91ea380cfbe132eeda6431dfc81ed6b542557",
-  "readme": "<!-- markdownlint-disable-file MD041 -->\n\n<p align=\"center\">\n  <!-- markdownlint-disable-next-line MD013 -->\n  <img src=\"https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@36f91ea380cfbe132eeda6431dfc81ed6b542557/assets/silvermoon.svg\" width=\"960\" alt=\"Silvermoon, the artifact spirit of the project\">\n</p>\n\n<p align=\"center\">\n  <!-- markdownlint-disable-next-line MD013 -->\n  <a href=\"https://npmx.dev/package/silvermoon\"><img src=\"https://img.shields.io/npm/v/silvermoon?style=flat-square\" alt=\"npm version\"></a>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <a href=\"https://npmx.dev/package/silvermoon\"><img src=\"https://img.shields.io/node/v/silvermoon?style=flat-square\" alt=\"Node.js version\"></a>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <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>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <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>\n</p>\n\n<p align=\"center\">\n  English | <a href=\"https://github.com/shazhou-ww/silvermoon/blob/36f91ea380cfbe132eeda6431dfc81ed6b542557/README.zh-CN.md\">简体中文</a>\n</p>\n\n# Silvermoon\n\n**The artifact spirit of the project.**\n\n## Quick Start\n\nSilvermoon needs Node.js 22 or newer and Git access to the repository's primary\nbranch.\n\n```sh\nnpm install --global silvermoon\nsilvermoon whats-next\n```\n\nSilvermoon is ecosystem-neutral: the target repository does not need\n`package.json`, a package manager, a Silvermoon dependency, or `node_modules`.\nThe first report lists every applicable setup step in order, including the\nexact `npx skills add ... --agent universal` command that registers the\ncanonical skill at `.agents/skills/silvermoon`.\n\nCreate `.silvermoon/config.yaml`:\n\n```yaml\nversion: 1\nprimaryRepository: https://github.com/example/repository.git\nprimaryBranch: main\npreferredLanguage: en\n```\n\n`preferredLanguage` is optional. A specific idea can override it with\n`language` in `status.yaml`, and `create-idea --language <tag>` can set that\noverride when the idea is created. Otherwise Silvermoon checks\n`~/.config/silvermoon/config.yaml` and finally defaults to `en-US`.\nThese stored values choose the language for project-owned content. To change\nonly one command's built-in output, use `whats-next --language en-US|zh-CN` or\n`check --language en-US|zh-CN`; the temporary override is never persisted.\n\nThen create an idea and let the registered Silvermoon skill guide one safe\nnext action at a time:\n\n```sh\nsilvermoon create-idea\nsilvermoon whats-next <idea>\nsilvermoon whats-next <idea> --language zh-CN\n```\n\nDescribe the desired world in the generated `Idea.md`, review it, and approve\nthat exact revision. From then on, Silvermoon keeps the goal, implementation,\nrepository state, and real-world result connected. See\n[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/36f91ea380cfbe132eeda6431dfc81ed6b542557/docs/getting-started.md) for the complete first workflow.\nDefault dialogue output uses lightweight Markdown headings for intent,\nobservation, and next instructions, plus actions and outcomes only when an\noperation was attempted. Add `--json` only when a programmatic consumer needs\nthe `intention / observation / outcomes / instructions` envelope. For\npre-commit validation, run `silvermoon check --staged`: unlike the default\n`check` (committed `HEAD`), it checks the index and exits `0` only when the\nproject snapshot is valid. See the [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/36f91ea380cfbe132eeda6431dfc81ed6b542557/docs/reference.md)\nfor validation targets and exit codes. Add `--trace <file.trace.jsonl>` to any\ncommand to write paired task and Git timing spans for performance analysis.\nIf the argument does not end with the exact lowercase `.trace.jsonl` suffix,\nSilvermoon appends it. Repository-local `*.trace.jsonl` files are ignored.\nTrace files are created only after the measured command work completes and\nnever overwrite an existing file.\n\nProjects may optionally add `.silvermoon/guidance/preparing.md`,\n`implementing.md`, and `deploying.md`. Silvermoon returns only the current\nactionable phase's snapshot-bound, repository-owned Markdown after canonical\ninstructions; `create-idea` can return preparing guidance. This guidance is\nadditive, never a fourth contract or decision fact, and `check` validates the\ncomplete fixed directory. See [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/36f91ea380cfbe132eeda6431dfc81ed6b542557/docs/core-concepts.md).\n\n## Why Silvermoon\n\nLong-running Agent work usually asks people to carry too much invisible state.\nSomeone must remember what was intended, whether the code still matches the\ntask, and which conversation or machine knows the latest truth. Silvermoon\nmakes those concerns part of the project instead.\n\nIt lets people step back from continuous supervision and return at the\ndecisions that belong to them: approving the intended outcome, accepting the\nimplementation, and accepting that the result is true in the outside world.\nBetween those boundaries, an Agent can inspect repository facts and continue\nthe highest-priority safe action.\n\nIt also refuses to let a detached task card declare success. Current artifacts\nand explicit decisions jointly determine state, so a changed goal or\nimplementation naturally invalidates conclusions that depended on the older\nrevision. Because those facts live in Git, work can continue across devices,\nsessions, Agents, and hosting platforms.\n\n## The Project's Artifact Spirit\n\n> Fellow Daoist, you wouldn't want your lifebound project to be without an\n> artifact spirit, would you?\n\n<table>\n  <tr>\n    <td width=\"160\" align=\"center\" valign=\"top\">\n      <!-- markdownlint-disable-next-line MD013 -->\n      <img src=\"https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@36f91ea380cfbe132eeda6431dfc81ed6b542557/assets/silvermoon-avatar.svg\" width=\"128\" alt=\"Line portrait of Silvermoon, the project's artifact spirit\">\n    </td>\n    <td valign=\"top\">\n      Silvermoon is named after a character in <em>A Record of a Mortal's\n      Journey to Immortality</em>. She comes from the Silvermoon Wolf Clan in\n      the Spirit Realm and is one of the split souls of Ling Long. After losing\n      part of her memory in the human realm, she lives as an artifact spirit\n      first in a wolf-headed jade scepter and later in Han Li's Bamboo\n      Cloudswarm Swords.\n      <br><br>\n      That image fits this project: Silvermoon does not belong to one operator\n      or one chat. It lives with the project's artifacts, understands their\n      state, and helps each companion find what comes next. The biography is\n      inspiration, not a prerequisite for using the tool.\n    </td>\n  </tr>\n</table>\n\nWatch *A Record of a Mortal's Journey to Immortality*:\n\n<!-- markdownlint-disable-next-line MD013 -->\n- 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\")\n<!-- markdownlint-disable-next-line MD013 -->\n- 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\")\n\n## From Ideal To Real\n\nA project is more than a task list or a transcript. It is an ideal becoming\nreal through three nested worlds.\n\n**Ideal World (道心)** names the outcome worth pursuing. **Inner World (内景)**\ngives that intent shape in repository artifacts. **Outer World (现世)** asks\nwhether the shaped work is true where it must actually operate.\n\n> 道心立意，内景成形，现世验真。\n\nThe worlds nest from the inside out. Implementation contains the ideal it\nserves, and deployment contains both. This is an engineering relationship, not\njust a metaphor: when an inner world changes, conclusions from an outer world\nno longer have the same foundation and must be proven again.\n\nHumans own approval and acceptance. Agents own continuation: they read the\ncontracts, the ledger, and Git facts; preserve concurrent work; execute one\nsafe action; and reobserve only after something changes. The context belongs to\nthe project, not to a fleeting conversation.\n\n## Further Reading\n\n- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/36f91ea380cfbe132eeda6431dfc81ed6b542557/docs/getting-started.md) — installation, configuration,\n  and the first idea.\n- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/36f91ea380cfbe132eeda6431dfc81ed6b542557/docs/core-concepts.md) — project ownership, the three\n  worlds, revisions, and decision boundaries.\n- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/36f91ea380cfbe132eeda6431dfc81ed6b542557/docs/operations.md) — navigation, creation,\n  publication, hygiene, and continuation.\n- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/36f91ea380cfbe132eeda6431dfc81ed6b542557/docs/reference.md) — storage, derived state, CLI\n  reports, validation targets, and schemas.\n- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/36f91ea380cfbe132eeda6431dfc81ed6b542557/docs/maintaining.md) — development checks,\n  documentation ownership, and release guidance.\n",
+  "gitHead": "fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400",
+  "readme": "<!-- markdownlint-disable-file MD041 -->\n\n<p align=\"center\">\n  <!-- markdownlint-disable-next-line MD013 -->\n  <img src=\"https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/assets/silvermoon.svg\" width=\"960\" alt=\"Silvermoon, the artifact spirit of the project\">\n</p>\n\n<p align=\"center\">\n  <!-- markdownlint-disable-next-line MD013 -->\n  <a href=\"https://npmx.dev/package/silvermoon\"><img src=\"https://img.shields.io/npm/v/silvermoon?style=flat-square\" alt=\"npm version\"></a>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <a href=\"https://npmx.dev/package/silvermoon\"><img src=\"https://img.shields.io/node/v/silvermoon?style=flat-square\" alt=\"Node.js version\"></a>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <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>\n  <!-- markdownlint-disable-next-line MD013 -->\n  <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>\n</p>\n\n<p align=\"center\">\n  English | <a href=\"https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/README.zh-CN.md\">简体中文</a>\n</p>\n\n# Silvermoon\n\n**The artifact spirit of the project.**\n\n## Quick Start\n\nSilvermoon needs Node.js 22 or newer and Git access to the repository's primary\nbranch.\n\n```sh\nnpm install --global silvermoon\nsilvermoon whats-next\nsilvermoon list-ideas\n```\n\nSilvermoon is ecosystem-neutral: the target repository does not need\n`package.json`, a package manager, a Silvermoon dependency, or `node_modules`.\nThe first report lists every applicable setup step in order, including the\nexact `npx skills add ... --agent universal` command that registers the\ncanonical skill at `.agents/skills/silvermoon`.\n\nCreate `.silvermoon/config.yaml`:\n\n```yaml\nversion: 1\nprimaryRepository: https://github.com/example/repository.git\nprimaryBranch: main\npreferredLanguage: en\n```\n\n`preferredLanguage` is optional. A specific idea can override it with\n`language` in `status.yaml`, and `create-idea --language <tag>` can set that\noverride when the idea is created. Otherwise Silvermoon checks\n`~/.config/silvermoon/config.yaml` and finally defaults to `en-US`.\nThese stored values choose the language for project-owned content. To change\nonly one command's built-in output, use `whats-next --language en-US|zh-CN` or\n`check --language en-US|zh-CN`; the temporary override is never persisted.\n\nUse `list-ideas` when you only need the current local inventory. It defaults to\nactive ideas and supports repeatable `--state`, `--all`, literal `--query`,\nRFC 3339 `--created-since` / `--created-before`, `--sort`, and `--limit`.\nUnlike lifecycle navigation, this read-only query uses the valid worktree\nsnapshot without checking branch, upstream, cleanliness, network, or primary\nsynchronization.\n\nThen create an idea and let the registered Silvermoon skill guide one safe\nnext action at a time:\n\n```sh\nsilvermoon create-idea\nsilvermoon whats-next <idea>\nsilvermoon whats-next <idea> --language zh-CN\n```\n\nDescribe the desired world in the generated `Idea.md`, review it, and approve\nthat exact revision. From then on, Silvermoon keeps the goal, implementation,\nrepository state, and real-world result connected. See\n[Getting Started](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/getting-started.md) for the complete first workflow.\nEvery command processes one ordered, versioned domain-message stream. Add\n`--json` when a programmatic consumer needs its four deterministic projections:\n`intention`, `observation`, `actions`, and `response`. Actions are side effects\nalready attempted; future work belongs only to `response.nextSteps`. Default\nMarkdown renders only the self-contained response instead of exposing the\ninternal projections. For pre-commit validation, run\n`silvermoon check --staged`: unlike the default `check` (committed `HEAD`), it\nchecks the index and exits `0` only when the project snapshot is valid. See the\n[Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/reference.md) for validation targets and exit\ncodes.\n\nAdd `--trace <file.trace.jsonl>` to any command to write one schema-versioned\nJSONL timeline. Its `domain` channel contains allowlisted message summaries,\nand its `telemetry` channel contains paired performance spans; both share one\ntrace ID and global sequence. Trace output never includes guidance or file\ncontent, Git arguments/output, environment data, or credentials. If the\nargument does not end with the exact lowercase `.trace.jsonl` suffix,\nSilvermoon appends it. Repository-local `*.trace.jsonl` files are ignored.\nTrace files are buffered, created only after command work completes, and never\noverwrite an existing file.\n\nProjects may optionally add `.silvermoon/guidance/preparing.md`,\n`implementing.md`, and `deploying.md`. Silvermoon returns only the current\nactionable phase's snapshot-bound, repository-owned Markdown in\n`response.guidance`; `observation.guidance` carries its provenance without\ncontent. `create-idea` can return preparing guidance. This guidance is\nadditive, never a fourth contract or decision fact, and `check` validates the\ncomplete fixed directory. See [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/core-concepts.md).\n\n## Why Silvermoon\n\nLong-running Agent work usually asks people to carry too much invisible state.\nSomeone must remember what was intended, whether the code still matches the\ntask, and which conversation or machine knows the latest truth. Silvermoon\nmakes those concerns part of the project instead.\n\nIt lets people step back from continuous supervision and return at the\ndecisions that belong to them: approving the intended outcome, accepting the\nimplementation, and accepting that the result is true in the outside world.\nBetween those boundaries, an Agent can inspect repository facts and continue\nthe highest-priority safe action.\n\nIt also refuses to let a detached task card declare success. Current artifacts\nand explicit decisions jointly determine state, so a changed goal or\nimplementation naturally invalidates conclusions that depended on the older\nrevision. Because those facts live in Git, work can continue across devices,\nsessions, Agents, and hosting platforms.\n\n## The Project's Artifact Spirit\n\n> Fellow Daoist, you wouldn't want your lifebound project to be without an\n> artifact spirit, would you?\n\n<table>\n  <tr>\n    <td width=\"160\" align=\"center\" valign=\"top\">\n      <!-- markdownlint-disable-next-line MD013 -->\n      <img src=\"https://cdn.jsdelivr.net/gh/shazhou-ww/silvermoon@fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/assets/silvermoon-avatar.svg\" width=\"128\" alt=\"Line portrait of Silvermoon, the project's artifact spirit\">\n    </td>\n    <td valign=\"top\">\n      Silvermoon is named after a character in <em>A Record of a Mortal's\n      Journey to Immortality</em>. She comes from the Silvermoon Wolf Clan in\n      the Spirit Realm and is one of the split souls of Ling Long. After losing\n      part of her memory in the human realm, she lives as an artifact spirit\n      first in a wolf-headed jade scepter and later in Han Li's Bamboo\n      Cloudswarm Swords.\n      <br><br>\n      That image fits this project: Silvermoon does not belong to one operator\n      or one chat. It lives with the project's artifacts, understands their\n      state, and helps each companion find what comes next. The biography is\n      inspiration, not a prerequisite for using the tool.\n    </td>\n  </tr>\n</table>\n\nWatch *A Record of a Mortal's Journey to Immortality*:\n\n<!-- markdownlint-disable-next-line MD013 -->\n- 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\")\n<!-- markdownlint-disable-next-line MD013 -->\n- 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\")\n\n## From Ideal To Real\n\nA project is more than a task list or a transcript. It is an ideal becoming\nreal through three nested worlds.\n\n**Ideal World (道心)** names the outcome worth pursuing. **Inner World (内景)**\ngives that intent shape in repository artifacts. **Outer World (现世)** asks\nwhether the shaped work is true where it must actually operate.\n\n> 道心立意，内景成形，现世验真。\n\nThe worlds nest from the inside out. Implementation contains the ideal it\nserves, and deployment contains both. This is an engineering relationship, not\njust a metaphor: when an inner world changes, conclusions from an outer world\nno longer have the same foundation and must be proven again.\n\nHumans own approval and acceptance. Agents own continuation: they read the\ncontracts, the ledger, and Git facts; preserve concurrent work; execute one\nsafe action; and reobserve only after something changes. The context belongs to\nthe project, not to a fleeting conversation.\n\n## Further Reading\n\n- [Getting Started](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/getting-started.md) — installation, configuration,\n  and the first idea.\n- [Core Concepts](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/core-concepts.md) — project ownership, the three\n  worlds, revisions, and decision boundaries.\n- [Operating Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/operations.md) — navigation, creation,\n  publication, hygiene, and continuation.\n- [Technical Reference](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/reference.md) — storage, derived state, CLI\n  reports, validation targets, and schemas.\n- [Maintaining Silvermoon](https://github.com/shazhou-ww/silvermoon/blob/fcc881a6a5e7b7f2aad283f3b151a4c15fd6f400/docs/maintaining.md) — development checks,\n  documentation ownership, and release guidance.\n",
   "readmeFilename": "README.md"
 }

package/schema/v1/command-report.schema.json

@@ -0,0 +1,178 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/shazhou-ww/silvermoon/raw/refs/heads/main/schema/v1/command-report.schema.json",
+  "title": "Silvermoon command report v1",
+  "description": "The four public projections returned by every trustworthy Silvermoon command.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "intention",
+    "observation",
+    "actions",
+    "response"
+  ],
+  "properties": {
+    "intention": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "command",
+        "args"
+      ],
+      "properties": {
+        "command": {
+          "enum": [
+            "whats-next",
+            "create-idea",
+            "check",
+            "list-ideas"
+          ]
+        },
+        "args": {
+          "type": "object"
+        }
+      }
+    },
+    "observation": {
+      "type": "object",
+      "required": [
+        "state",
+        "problems"
+      ],
+      "properties": {
+        "state": {
+          "type": "string",
+          "minLength": 1
+        },
+        "problems": {
+          "type": "array"
+        }
+      }
+    },
+    "actions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "id",
+          "type",
+          "status"
+        ],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^action-[1-9][0-9]*$"
+          },
+          "type": {
+            "type": "string",
+            "minLength": 1
+          },
+          "status": {
+            "enum": [
+              "success",
+              "failure"
+            ]
+          },
+          "result": {
+            "type": "object"
+          },
+          "problem": {
+            "type": "object",
+            "required": [
+              "type"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        },
+        "allOf": [
+          {
+            "if": {
+              "properties": {
+                "status": {
+                  "const": "success"
+                }
+              }
+            },
+            "then": {
+              "properties": {
+                "result": {
+                  "type": "object"
+                }
+              },
+              "required": [
+                "result"
+              ]
+            },
+            "else": {
+              "properties": {
+                "problem": {
+                  "type": "object"
+                }
+              },
+              "required": [
+                "problem"
+              ]
+            }
+          }
+        ]
+      }
+    },
+    "response": {
+      "type": "object",
+      "required": [
+        "kind",
+        "language",
+        "summary"
+      ],
+      "properties": {
+        "kind": {
+          "enum": [
+            "blocked",
+            "choice-required",
+            "idea-created",
+            "idea-list",
+            "next-steps",
+            "validation-result"
+          ]
+        },
+        "language": {
+          "enum": [
+            "en-US",
+            "zh-CN"
+          ]
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1
+        },
+        "nextSteps": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "additionalProperties": false,
+            "required": [
+              "type",
+              "text"
+            ],
+            "properties": {
+              "type": {
+                "type": "string",
+                "minLength": 1
+              },
+              "text": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}