silvermoon 0.3.0-rc.2 → 0.4.0

package/docs/operations.md

@@ -6,10 +6,10 @@ publishing Silvermoon ideas.
 ## Navigate
 
 ```sh
-npx silvermoon whats-next
-npx silvermoon whats-next 01M36QGPNTXEPP61DA4KP4AVZF
-npx silvermoon whats-next publish-documentation --json
-npx silvermoon whats-next publish-documentation --language zh-CN
+silvermoon whats-next
+silvermoon whats-next 01M36QGPNTXEPP61DA4KP4AVZF
+silvermoon whats-next publish-documentation --json
+silvermoon whats-next publish-documentation --language zh-CN
 ```
 
 Without a selector, Silvermoon asks for a choice among multiple active ideas,
@@ -27,11 +27,41 @@ entries, same-world supporting artifacts, and the ledger. A caller may use
 markers, and verbatim tool output retain their original form.
 
 Every `whats-next` invocation follows three strict layers. It first checks Git,
-configuration compatibility, and `.agents/skills/silvermoon`. It then checks
-local conflicts, changes, HEAD, and upstream identity before any remote access.
-Only after those checks pass does it fetch primary, compare ancestry, and
-route idea work. It never edits, checks out, merges, commits, stashes, deletes,
-resets, fast-forwards, or pushes.
+configuration compatibility, metadata schema, and layout. It then checks local
+conflicts, changes, HEAD, and upstream identity before any remote access. Only
+after those checks pass does it fetch primary, compare ancestry, and route idea
+work. Runtime and personal skill health belong to device readiness, never the
+project snapshot. `whats-next` never edits, checks out, merges, commits,
+stashes, deletes, resets, fast-forwards, or pushes.
+
+Dialogue reports expose runtime source/version, personal skill health, and
+latest-runtime status under the non-blocking device advisory. Global
+installations reuse a successful npm `latest` result for less than 24 hours;
+source checkouts and embedding hosts do not perform that registry query.
+Registry or skill failures remain device diagnostics and do not replace
+project problems or lifecycle instructions.
+
+Project schema readiness is reported per schema-bearing file. A valid file at
+the runtime's write target is `current`; a valid readable historical file is
+`migration-required`; a declaration above the runtime's read capability is
+`runtime-upgrade-required`; malformed content is `invalid`. `whats-next` and
+write preparation stop on historical metadata until its declared migration is
+run. `list-ideas` may continue to read a valid historical project, and
+snapshot-only `check` validates it without requiring migration.
+
+Since `0.4.0`, `schema/capabilities.json` is the runtime-owned compatibility
+contract. Each historical read version must have one continuous path to its
+family target. A migration edge names one global executable and its packaged
+and source-checkout entrypoints; storage-only transformations do not appear as
+schema edges. For the current v1-to-v2 edge, plan with
+`silvermoon-migrate-v1-to-v2 --root <project>` and apply only the exact
+reviewed digest. Ordinary navigation never migrates automatically.
+
+When project preparation encounters a future schema, it bypasses the 24-hour
+runtime freshness cache once for that observation. The report distinguishes a
+new runtime being available, the confirmed latest runtime still lacking the
+capability, and an unavailable registry. Snapshot-only `check` remains
+deterministic and performs no registry access.
 
 When a selector resolves to an actionable phase and synchronization is ready,
 Silvermoon reads only `.silvermoon/guidance/<phase>.md` from the same Git
@@ -57,11 +87,12 @@ silvermoon list-ideas --sort oldest --limit 25 --json
 ```
 
 The command reads one valid local worktree snapshot. It checks the project
-configuration, canonical skill, and complete idea layout, but deliberately
+configuration and complete idea layout, but deliberately
 does not check conflicts, cleanliness, current branch, upstream, primary
-ancestry, or network availability. It never fetches. Filters cannot hide an
-invalid idea; setup or layout failures return a `blocked` four-projection
-report and exit `1`.
+ancestry, or primary network availability. The project query never fetches;
+the independent device advisory may refresh npm `latest` when its cache is
+expired. Filters cannot hide an invalid idea; setup or layout failures return
+a `blocked` four-projection report and exit `1`.
 
 The default state set is `preparing`, `implementing`, and `deploying`.
 Repeated `--state` values form a deduplicated union, `active` expands to those
@@ -91,8 +122,9 @@ Creation intent is distinct from active-idea selection. If hygiene blocks the
 command, perform only the reported remediation and retry `create-idea`; do not
 replace the request with selector-less navigation.
 
-Creation checks project readiness, then requires the configured primary branch
-and upstream plus a clean worktree. It does not fetch, compare ancestry, or
+Creation checks project readiness, then requires a local branch whose upstream
+identifies the configured primary repository and branch, plus a clean worktree.
+The local branch name is unrestricted. It does not fetch, compare ancestry, or
 require local HEAD to be aligned with the remote tip. Its preparation reports
 omit the active-idea inventory because existing work does not replace explicit
 creation intent. After preflight and before the first scaffold write, it
@@ -100,7 +132,8 @@ validates preparing guidance from local `HEAD`. Invalid guidance leaves no
 creation path; valid guidance is attached only to the success report.
 
 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.
+to v1 `status.yaml`, or a v2 `setLanguage` event, 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|en-US|zh|zh-CN` output override accepted by `list-ideas`,
@@ -110,10 +143,10 @@ The generated files remain untracked for review. Complete `Idea.md`, optionally
 add a concise unique alias, inspect every path, and publish the initial idea
 through ordinary Git. Validate and commit the complete prepared idea, then make
 that commit reachable from configured primary using the repository's normal
-non-force publication path before asking the user to review or approve it. If
+non-force publication path before asking the user to review or accept it. If
 publication requires a pull request, wait until it reaches primary. Reobserve
-the exact `idealRevision` after publication; never ask for approval of an
-unpublished local candidate, and never treat publication as approval.
+the exact `idealRevision` after publication; never ask for acceptance of an
+unpublished local candidate, and never treat publication as acceptance.
 
 ## Follow One Report
 
@@ -163,15 +196,38 @@ World's real-world deployment contract. The latter two contain `## Steps` and
 Each criterion states both the observable outcome and how an Agent can prove
 it. World contracts do not use task-list checkboxes.
 
-The required idea-root `ledger.md` mirrors those IDs and short titles as
-checkboxes under Implementation and Deployment. Update a world heading and its
-ledger entry together. Add new items unchecked, and reset a completed item when
-its requirement or proof changes materially.
+During preparation, replace all scaffold placeholders in `Implementation.md`
+and `Deployment.md` with lightweight first versions of no more than three
+high-level steps and three observable criteria each. Mirror them unchecked in
+`ledger.md`. They provide a feasibility path before Idea acceptance but remain
+provisional: `acceptIdeal` accepts only the Ideal tree. Refine each seed during
+its own lifecycle phase rather than writing speculative architecture, detailed
+task trees, or execution evidence up front.
+
+The required idea-root `ledger.md` is an execution checklist only, not
+operational prose, a decision log, a discussion record, or a fourth world. It
+mirrors those IDs and short titles as checkboxes under Implementation and
+Deployment. Do not record work notes, explanations, or extra sections in
+`ledger.md`. Update a world heading and its ledger entry together. Add new
+items unchecked, and reset a completed item when its requirement or proof
+changes materially.
 
 ## Record A Human Decision
 
+For v2, finish and synchronize the current world before the human gate, append
+the matching `submitIdeal`, `submitInner`, or `submitOuter` for that exact
+revision, integrate the event, and reobserve. Only a current submission with
+upstream control produces the corresponding `response.review`; ping/pong may
+transfer control within the same phase without changing the submission fact.
+
 After an explicit decision, reconfirm that it applies to the selected idea and
-the current reported world revision. Edit only the corresponding status fact:
+the current reported world revision. For v2, use the
+[event commands and recovery protocol](../skills/silvermoon/references/events.md)
+instead of editing JSONL; stage the changed canonical `events.jsonl` after a
+validated append. The expected digest is the Git blob OID of the complete
+file, while retries also require the exact record after that prefix. An
+`accept*` append must match the already submitted revision.
+For v1, edit only the corresponding status fact:
 
 - `approvedRevision`
 - `implementationAcceptedRevision`
@@ -187,8 +243,9 @@ git add .silvermoon/ideas/<ULID>/status.yaml
 silvermoon check --staged
 ```
 
-`check` is a project-only validator, not a navigation command. It does not
-check worktree hygiene, upstream, or ancestry and does not suggest next steps.
+`check` is a project validator, not a navigation command. V2 additionally
+validates conditional append-only primary history. It does not check worktree
+hygiene or upstream and does not suggest lifecycle next steps.
 Without a target it validates committed `HEAD`, not the pending commit.
 `--worktree` validates the full candidate, while `--staged` validates exactly
 the index and is the pre-commit hook target. Every target validates all present
@@ -214,18 +271,35 @@ their mismatch is what derives the idea's earlier lifecycle state.
 Prefer a status-only decision commit, publish through the repository's normal
 non-force path, and verify the commit is reachable from refreshed primary.
 
-When asking for approval or acceptance, identify the idea by alias and ULID,
-state the exact reported world revision, and link the corresponding canonical
-entry at the published primary commit: `Idea.md` for ideal approval,
-`Implementation.md` for implementation acceptance, or `Deployment.md` for
-deployment acceptance. Use a commit-pinned web permalink rather than a local
-workspace path or a branch name that can move. The linked revision and
-publication are review context only; the user must still make the decision
-explicitly.
+When asking for acceptance, identify the idea by alias and ULID,
+follow the latest `response.nextSteps`, and seed the index from
+`response.review`. Its `presentation` object owns the fixed gate labels,
+document labels, primary connector, and exact decision question from the
+effective content language. Preserve those strings when `requiresLocalization`
+is false; otherwise localize all human-visible presentation values to the
+reported `contentLanguage` without changing machine identifiers. Never use the
+temporary report output language for gate prose. State the exact reported world
+revision and primary commit internally, and show their 12-character references.
+Link the corresponding canonical entry: `Idea.md` for
+idea acceptance, `Implementation.md` for implementation acceptance, or
+`Deployment.md` for deployment acceptance. Provide a host-clickable local link
+for navigation and a commit-pinned web permalink for the immutable candidate;
+never substitute a moving branch URL. Complete this review index as a standalone
+assistant message. Do not open an interactive decision in the same turn because
+the tool surface may hide the links; a later decision interaction contains only
+the exact question and choices. Use the compact order directed by the report
+for all three gates. Ideal review omits downstream placeholders. Implementation
+and Deployment always link their corresponding contract and `ledger.md`; other
+files appear only when they contain substantive review material. Keep test,
+CI, deployment, and SLO detail in the
+linked evidence instead of repeating policy or completion narration. If the
+later decision interaction is unavailable or returns no explicit choice, do not
+retry or restate the unchanged gate. The linked revision and publication are
+review context only; the user must still make the decision explicitly.
 
 ## Publish Work
 
 Before publication, compare with the observed primary tip, run checks focused
 on the change, and inspect the exact diff. On push rejection, branch movement,
 or a newly discovered conflict, preserve both histories, fetch, and reobserve.
-Never replay approval or acceptance automatically against a new revision.
+Never replay acceptance automatically against a new revision.