silvermoon 0.0.2 → 0.1.0

package/docs/reference.md

@@ -44,8 +44,9 @@ Each world is an opaque Git tree:
 - `deploymentRevision` identifies `outer/` and includes both nested worlds.
 
 `status.yaml` and `ledger.md` are outside all three world trees. The repository
-object format in use determines revision shape; Silvermoon validates object
-types and candidate bindings rather than interpreting world contents.
+object format in use determines revision shape. Silvermoon validates canonical
+revision shape, computes the current world trees, and compares those values to
+status facts rather than interpreting world contents.
 
 ## Status File
 
@@ -67,9 +68,12 @@ world revision and does not change lifecycle decisions. Explicit
 keys, YAML aliases or anchors, comments, and noncanonical YAML are rejected.
 
 Effective language resolves as `idea language > project preferredLanguage >
-user preferredLanguage > en-US`. JSON reports expose
-`language: { tag, source }`; human output shows the same values. Missing idea
-language remains dynamically inherited and is never written back.
+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.
 
 State is derived in order:
 
@@ -84,51 +88,207 @@ State is derived in order:
 ## Public Commands
 
 ```sh
-silvermoon whats-next [idea]
-silvermoon create-idea [--language <tag>]
-silvermoon check [--remote | --commit <revision> | --staged | --worktree]
+silvermoon whats-next [idea] [--trace <file.trace.jsonl>]
+silvermoon create-idea [--language <tag>] [--trace <file.trace.jsonl>]
+silvermoon check [--remote | --commit <revision> | --staged | --worktree] [--trace <file.trace.jsonl>]
 ```
 
-`whats-next` returns one highest-priority action after repository and onboarding
-diagnosis. JSON reports include `observedPrimaryCommit`, `language`,
-`selectedIdea`, and exactly one `action`. When onboarding passes without gaps,
-the report omits `onboarding`. Otherwise `onboarding.gaps` contains only unmet,
-conflicting, or unknown requirements, preserving their stable IDs, statuses,
-blocking flags, dependencies, observed facts, and structured remediation. The
-compact onboarding report also includes a recommended action and recheck
-command. Human-readable output follows the same quiet-success, actionable-gap
-semantics. Use `check` when a complete repository diagnostic is required.
-
-Execution source is classified as `source-checkout`, `project-local`,
-`temporary`, `global`, or `unknown`. Temporary execution can bootstrap
-diagnosis; normal idea work requires the exact project dependency, installed
-package, and matching repository-local skill.
-
-`create-idea` applies the same hygiene preflight and then creates one canonical
-scaffold. 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.
+`whats-next` and `create-idea` build one dialogue envelope:
+
+```json
+{
+  "intention": {
+    "command": "whats-next",
+    "args": {
+      "idea": null
+    }
+  },
+  "observation": {},
+  "outcomes": [],
+  "instructions": ""
+}
+```
+
+- `intention` contains the command and normalized business arguments. 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.
+- `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.
+
+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. 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
+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.
+
+Observations are discriminated by command intent and `state`:
+
+- `project-setup-required` uses `observedThrough` (`root`, `version`,
+  `configuration`, or `ideas`) to identify the deepest reliable cumulative
+  shape. Fields beyond that boundary are absent rather than null or fabricated.
+- `repository-sync-required` is used by `whats-next` and always includes
+  `root`, `version`, `configuration`, `ideas`, and at least one `problem`.
+- `repository-preparation-required` is used by `create-idea` when its local
+  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.
+- 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.
+- 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.
+
+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`.
+
+Project setup is ecosystem-neutral. It checks Git, configuration schema
+compatibility, and exact canonical skill content at
+`.agents/skills/silvermoon`. It does not inspect execution source or require a
+package manager, `package.json`, project-local Silvermoon dependency, or
+`node_modules`.
+
+`whats-next` checks local conflicts and changes before remote access, then HEAD
+and upstream identity, then fetch and ancestry. A local branch may have any
+name, but its upstream must identify the configured repository and primary
+branch. Change summaries have fixed item and UTF-8 byte budgets and provide
+full counts and omitted counts; instructions require inspection of the complete
+change set without prescribing a particular diff tool. Bare navigation
+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.
 
 ## Validation Targets
 
-- `check` validates only the committed `HEAD` snapshot and reads primary
-  coordinates from that snapshot.
+- `check` validates only the committed `HEAD` snapshot. It is not a
+  pre-commit check.
 - `check --worktree` validates the hypothetical commit formed from `HEAD`, the
   index, unstaged changes, and nonignored untracked files.
-- `check --staged` validates the index snapshot.
+- `check --staged` validates the index snapshot for a pre-commit hook.
 - `check --commit <revision>` validates one local commit snapshot.
 - `check --remote` fetches primary using committed coordinates, validates its
-  immutable tip, and proves retained revision facts against complete reachable
-  primary history.
+  immutable tip, and does not audit the history or provenance of retained
+  revision facts. Unrelated skill or idea findings in local `HEAD` do not block
+  locating and validating the remote snapshot.
 
 Targets are mutually exclusive and never change the caller's branch, index, or
-worktree. Exit status `0` means success, `1` means validation or operational
-failure, and `2` means invalid CLI usage. `--json` emits the stable report
-envelope.
+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.
+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
+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`:
+
+```json
+{
+  "intention": {
+    "command": "check",
+    "args": { "target": { "type": "staged" } }
+  },
+  "observation": {
+    "state": "project-ready",
+    "root": "D:\\Code\\silvermoon",
+    "version": { "type": "staged" },
+    "configuration": {
+      "primaryRepository": "https://example.com/owner/repository.git",
+      "primaryBranch": "main",
+      "preferredLanguage": "en-US"
+    },
+    "ideas": {
+      "counts": {
+        "preparing": 0,
+        "implementing": 0,
+        "deploying": 0,
+        "completed": 0,
+        "abandoned": 0
+      },
+      "activeIdeas": []
+    },
+    "problems": []
+  }
+}
+```
+
+`intention.args.target.type` is `head`, `staged`, `worktree`, `commit`, or
+`remote`; a requested `--commit` revision stays in intention. A resolved
+`HEAD` or local commit is reported in observation as
+`version: { type: "commit", commit: "<oid>" }`; a fetched remote tip is
+`{ type: "remote", commit: "<oid>" }`. Failed commit resolution or fetch
+reports `commit: null` and a problem. Staged and worktree versions only
+contain `type`.
+
+The `check` observation has its own discriminated states:
+
+- `project-ready` has root, version, resolved configuration, idea summary,
+  and empty problems. It says nothing about repository synchronization.
+- `project-setup-required` has nonempty problems and the same progressive
+  `observedThrough` variants as project setup in the dialogue.
+- `check-unavailable` has known root, target version, and nonempty problems
+  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.
 
 Runtime checks verify canonical YAML, fixed paths, the three world entries,
-unique aliases, Git object format, tree object types, per-world candidate
-revision binding, and acceptance history.
+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.
 
 ## Schemas
 

package/docs/repository-tasks.md

@@ -10,8 +10,8 @@ The shared authority is `https://github.com/shazhou-ww/silvermoon.git` on
 optional transport and are not protocol state.
 
 ```sh
-silvermoon whats-next [idea] --json
-silvermoon create-idea --json
+silvermoon whats-next [idea]
+silvermoon create-idea
 silvermoon check
 silvermoon check --worktree
 silvermoon check --staged
@@ -19,25 +19,31 @@ silvermoon check --commit HEAD
 silvermoon check --remote
 ```
 
-Use the report's `observedPrimaryCommit` as the expected remote tip. When
+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
-`silvermoon create-idea --json` even when unrelated active ideas exist; all
-navigation uses `silvermoon whats-next [idea] --json`. Both commands apply the
-same branch, conflict, worktree, and ancestry hygiene. If hygiene blocks an
-explicit creation, perform only that blocking action and then retry
-`create-idea` so active-idea selection cannot replace the pending create intent.
+`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.
 
 ## Decisions And Publication
 
-`whats-next` is read-only. 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.
+`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.
 
 The required idea-root `ledger.md` is the Agent continuation surface. After
-repository hygiene and lifecycle routing, combine the reported action, world
+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
@@ -59,3 +65,9 @@ branches.
   and `git diff --check` before delivery review.
 - Use `silvermoon check --commit HEAD` for checked-out CI and
   `silvermoon check --remote` for complete primary-history evidence.
+- Use `silvermoon check --staged` in pre-commit hooks: default `check` validates
+  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`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "silvermoon",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "description": "The project spirit that checks repository state and answers what's next.",
   "packageManager": "pnpm@11.22.0",
   "type": "module",
@@ -21,7 +21,7 @@
     "schema"
   ],
   "scripts": {
-    "check": "npm run lint:markdown && npm run check:quick && npm run test:integration && npm run pack:check && npm run test:e2e && npm run check:skills",
+    "check": "node scripts/run-checks.mjs",
     "check:quick": "node --check bin/silvermoon.js && npm test",
     "check:skills": "node scripts/sync-skills.mjs --check && npx skills add . --list",
     "lint:markdown": "markdownlint-cli2",

package/schema/v1/idea-status.schema.json

@@ -29,15 +29,15 @@
       "const": true
     },
     "approvedRevision": {
-      "description": "Accepted Ideal World (道心) tree object ID.",
+      "description": "Accepted Ideal World (理想世界) tree object ID.",
       "$ref": "definitions.schema.json#/$defs/objectId"
     },
     "implementationAcceptedRevision": {
-      "description": "Accepted Inner World (内景) tree object ID.",
+      "description": "Accepted Inner World (主体世界) tree object ID.",
       "$ref": "definitions.schema.json#/$defs/objectId"
     },
     "deploymentAcceptedRevision": {
-      "description": "Accepted Outer World (现世) tree object ID.",
+      "description": "Accepted Outer World (现实世界) tree object ID.",
       "$ref": "definitions.schema.json#/$defs/objectId"
     }
   }