silvermoon 0.3.0-rc.2 → 0.4.0

package/docs/reference.md

@@ -16,7 +16,7 @@ Each idea is self-contained under one canonical uppercase ULID:
 |   `-- deploying.md
 `-- ideas/
     `-- 01M36QGPNTXEPP61DA4KP4AVZF/
-        |-- status.yaml
+        |-- status.yaml (v1) or events.jsonl (v2)
         |-- ledger.md
         `-- outer/
             |-- Deployment.md
@@ -80,12 +80,13 @@ Each world is an opaque Git tree:
 - `implementationRevision` identifies `inner/` and includes the Ideal World.
 - `deploymentRevision` identifies `outer/` and includes both nested worlds.
 
-`status.yaml` and `ledger.md` are outside all three world trees. The repository
+`status.yaml` (v1), `events.jsonl` (v2), and `ledger.md` are outside all three
+world trees. The repository
 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
+## Status File (v1)
 
 ```yaml
 version: 1
@@ -131,6 +132,14 @@ 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.
 
+Creation initially writes explicit scaffold placeholders. Before Ideal
+approval, preparation replaces the Implementation and Deployment placeholders
+with lightweight first versions of no more than three high-level steps and
+three observable criteria each, mirrored unchecked in `ledger.md`. These
+provisional seeds do not widen `acceptIdeal`, which remains bound only to
+`idealRevision`; their later refinement changes the containing downstream
+revisions normally.
+
 State is derived in order:
 
 1. `abandoned` when `abandoned: true`.
@@ -141,6 +150,77 @@ State is derived in order:
    `deploymentRevision`.
 5. `completed` when all three revisions match.
 
+## Event State (v2)
+
+Project `version: 2` replaces mutable status with one required regular
+`events.jsonl` file at each idea root. The file may be empty; otherwise it is
+canonical UTF-8 JSONL with LF record endings, a final LF, consecutive sequence
+numbers beginning at 1, and a 1 MiB limit per record including LF. Its strict
+twelve-event union updates accepted and submitted revision facts, interaction
+messages, and unified control; no observations, creation/import markers, or
+audit envelope are stored. The nested-world revisions and five lifecycle
+states are unchanged.
+
+Use `event replay` and `event append` for routine state. Exceptional history
+maintenance edits the complete `events.jsonl` file directly and validates it
+through ordinary Git review and snapshot/history checks. Append requests carry
+the exact byte length and Git blob OID of the complete file outside the business
+event; lifecycle writes also require expected primary. Canonical JSONL, human
+gates, concurrency, conditional append-only history, and interrupted-write
+recovery are specified in the
+[event operations contract](../skills/silvermoon/references/events.md).
+
+For repeated consumption, `event replay <ULID> --after-length <bytes>
+--after-digest <oid>` returns only the events after an exactly matched cursor.
+The `delta-observed` receipt is not a complete reduction or authorization;
+ordinary full replay is unchanged. The experimental project runtime exposes
+this additive query as `readSince(route, { length, digest })`.
+
+Canonical-ULID interaction appends may use an authenticated local projection
+bound to the complete event-file blob OID to avoid repeating reduction on the
+warm path. These Git-private, runtime/source-bound files are disposable derived
+state, not event facts or authorization. The authoritative file is still read
+and validated. Incremental snapshot acquisition performs precise source checks;
+Windows authenticates native ChangeTime-to-OID bindings because Git uses
+CreationTime. Coarse timestamps and missing source records force content
+verification.
+Default metadata append receipts contain exact historical validation summaries;
+`--full-history` preserves complete historical reduction output. Alias and
+metadata paths retain layout, prefix and explicit human-gate checks.
+Full replay and history audits are not advertised as constant-time operations.
+The runtime-owned `schema/capabilities.json` manifest declares every readable
+schema version, current write target, and continuous schema migration path.
+The `project-v1-to-v2` edge covers project configuration and idea state
+together. It names the installed `silvermoon-migrate-v1-to-v2` executable,
+the packaged `dist/bin/migrate-v1-to-v2.js` entrypoint, and the source-checkout
+`bin/migrate-v1-to-v2.ts` entrypoint. Its declared guarantees require a
+read-only plan, exact-digest apply, resume, rollback, and semantic projection
+equivalence.
+
+Use the installed global runtime to plan and apply the edge:
+
+```sh
+silvermoon-migrate-v1-to-v2 --root <project>
+silvermoon-migrate-v1-to-v2 --root <project> --apply --expected-digest <plan-digest>
+```
+
+Embedding hosts may call the experimental `runSchemaMigration` package API.
+The source checkout instead runs `node bin/migrate-v1-to-v2.ts` so it tests
+the unpublished implementation. No ordinary command automatically migrates a
+v1 project.
+
+V2's ten business types are `setAlias`, `setLanguage`, `submitIdeal`,
+`submitInner`, `submitOuter`, `acceptIdeal`, `acceptInner`, `acceptOuter`,
+`abandon`, and `resume`. The two interaction types, `ping` and `pong`, carry
+only a nonempty `message` string. Replay retains ordered messages and projects
+`control.owner` with its last transfer across messages, submissions,
+acceptances, and terminal events. Each phase's submitted revision is separate
+from its accepted revision. After `abandon`, only `resume` is legal.
+Interaction appends need the local byte precondition but no primary fetch;
+submissions need the exact current world on primary but no human confirmation;
+acceptances additionally require explicit confirmation and the same revision
+already submitted. The CLI cannot authenticate upstream or downstream senders.
+
 ## Experimental JavaScript Package API
 
 The package root export is available for programmatic reuse, but remains
@@ -155,6 +235,84 @@ 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.
 
+### Agent runtime integration
+
+The `silvermoon/agents/copilot` subpath exports `CopilotAdapter` and
+`LocalProjectRegistry` (with TypeScript declarations). This is a separate
+experimental Agent integration, not part of the root export. Register a
+local Git project first with `registry.register(projectUrl, projectRoot)`,
+using its canonical credential-free HTTPS remote URL and a worktree root
+whose `.silvermoon/config.yaml` names that remote. Then construct
+`new CopilotAdapter({ registry, onPermissionRequest })`; callers must
+explicitly decide Copilot tool permissions rather than inheriting blanket
+approval. `start({ projectUrl, ideaId })` creates or reuses a dedicated worktree
+whose branch tracks the project's configured primary, and a durable Copilot
+session. A missing local primary tracking ref blocks creation rather than
+guessing a base. `send`
+returns an asynchronous stream of delivery observations, while `events`
+returns only final Agent replies and `observe` returns session and activity
+observations. Call `close()` to release connections; it does not delete
+session history or worktrees.
+An aborted turn or session error fails the formal reply stream, and a
+shutdown reports the session as `gone`; partial messages and subsequent
+idle notifications do not become final replies. Further sends report
+`unknown` and `start` cannot silently replace the failed session. Reconcile
+the project log and session state before explicit recovery.
+An uncertain SDK send similarly invalidates the current observation and
+reply stream; retrying the same message on that route does not send it again.
+
+The SDK acknowledges *acceptance*, not per-message consumption. Consequently
+the adapter reports `queued` followed by `unknown`; it does not claim
+`processed` without evidence. A final reply is the last user-facing assistant
+message when Copilot reports idle, not each intermediate tool-loop message.
+Consumers must persist their own project event preconditions and avoid
+resending uncertain operations. Registration rejects unknown or conflicting
+local projects; the adapter does not infer a worktree from a route string.
+The registry excludes concurrent owners of the same route. If an owner exits
+without `close()`, explicitly verify it stopped, then call
+`registry.recover(route, { confirmStopped: true })`; recovery refuses a live
+owner, another host, or an unknown lock. It does not replay an uncertain send.
+The registry also persists the route's Copilot session identity before
+creation: a missing SDK listing or an ambiguous creation failure cannot
+silently spawn a replacement. An SDK session listed without workspace metadata
+cannot be adopted without a matching pre-existing local binding. Only after
+verifying that the old session is
+truly lost and no route owner is active, call
+`registry.forgetSession(route, { confirmLost: true })` to permit a new session.
+This does not erase the old session, undo side effects, or authorize retrying
+messages with uncertain delivery.
+
+The `silvermoon/agents/project-runtime` subpath exports `ProjectRuntime`.
+It resolves the registered project's own installed Silvermoon CLI (or this
+source checkout's entrypoint), starts it in a separate process with the
+idea worktree as its working directory, and returns its structured report
+with `exitCode` (0 for success, 1 for a structured invalid/unavailable report).
+Reports with an unexpected command, idea, event operation, or malformed
+event receipt are rejected rather than treated as successful capabilities.
+`next(route)` calls only that project's `whats-next`; it does not reproduce
+Silvermoon's lifecycle rules. `replay(route)` observes the local event log;
+`appendInteraction(route, { type, message, expectedLength, expectedDigest })`
+passes an exact-log-bound `ping` or `pong` to the project's event command.
+For a legacy v1 project, that event command returns a structured unavailable
+report (`exitCode: 1`); no v2 event support is inferred from `next(route)`.
+Unsupported CLI/report versions, missing installations, and process failures
+are explicit errors. The caller still owns the loop, decision authorization,
+and the safe correlation of delivery and reply observations.
+
+For an isolated, opt-in live acceptance run (requires an authenticated
+Copilot CLI), use
+`SILVERMOON_REAL_COPILOT=1 node --test test/integration/copilot-runtime-live.test.ts`.
+The three cases use distinct disposable Git projects and deny unrelated tool
+permissions. They check two sequential `ping`/reply/`pong` handoffs and a
+third after adapter restart; a custom test-only tool with a rejecting Git
+pre-commit hook proves that a diagnostic ping reaches the running session
+without accepting a stale pong. Forcing the SDK process to stop leaves a
+subsequent ping pending instead of blindly resending it. A single adapter also
+isolates two projects. Normal test runs skip the live cases. In-flight
+disconnect recovery, actual production Git repair, and arbitrary tool
+side-effect deduplication are not guaranteed; uncertain work needs operator
+reconciliation.
+
 ## Public Commands
 
 ```sh
@@ -162,6 +320,7 @@ silvermoon list-ideas [--state <state>] [--all] [--query <text>] [--created-sinc
 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>]
+silvermoon event <replay|append> <idea> [--input <request.json>] [--after-length <bytes>] [--after-digest <oid>] [--full-history] [--expected-length <bytes>] [--expected-digest <oid>] [--expected-primary <commit>] [--confirm-decision] [--audience <human|agent>]
 ```
 
 Every valid invocation starts one ordered domain-message stream with
@@ -212,9 +371,80 @@ projections:
 - `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.
+  `validation-result`, and `event-result`. It contains the localized summary
+  and any ordered `nextSteps`, choices, items, validation result, review
+  context, or guidance needed by the caller.
+
+Dialogue observations and responses also carry the same optional `device`
+advisory. `device.runtime` identifies the running package as `global`, `host`,
+or `source-checkout`; `device.skill` reports personal-link health; and
+`device.update` reports `current`, `available`, `unavailable`,
+`managed-by-host`, or `source-checkout` with cache or registry provenance.
+These fields never enter `problems` or change command success. Snapshot-only
+`check` responses omit `device` so their result depends only on the selected
+project snapshot and explicit primary state.
+
+A selected active v2 idea adds a primary-bound `review` object to its
+`next-steps` response only when the exact current phase revision has a matching
+`submit*` event and effective control is upstream:
+
+```json
+{
+  "review": {
+    "phase": "preparing",
+    "decision": "acceptIdeal",
+    "revision": {
+      "field": "idealRevision",
+      "value": "<exact-world-tree-object-id>"
+    },
+    "primaryCommit": "<fetched-primary-commit>",
+    "scopePath": ".silvermoon/ideas/<ULID>/outer/inner/ideal",
+    "canonicalDocuments": [
+      {
+        "role": "current-contract",
+        "path": ".silvermoon/ideas/<ULID>/outer/inner/ideal/Idea.md"
+      }
+    ],
+    "presentation": {
+      "contentLanguage": "zh-CN",
+      "templateLanguage": "zh-CN",
+      "requiresLocalization": false,
+      "gateLabel": "构想验收",
+      "candidateConnector": "位于 primary",
+      "labels": {
+        "idea": "构想",
+        "candidate": "候选版本",
+        "reviewFocus": "审阅重点",
+        "reviewFiles": "审阅文件",
+        "decision": "决定",
+        "local": "本地",
+        "remote": "线上"
+      },
+      "documentLabels": {
+        "current-contract": "构想契约",
+        "ledger": "执行清单"
+      },
+      "decisionQuestion": "是否接受 `idealRevision=<12-character-reference>` 作为该 IDEA 的构想？"
+    }
+  }
+}
+```
+
+Implementation and deployment responses bind `acceptInner` or `acceptOuter`
+to their corresponding revision and list the current contract plus `ledger.md`.
+The field is an authoritative index seed and proves only the event-backed
+submission/control precondition, not a human decision. Callers inspect
+`scopePath` and add only supporting files with substantive review content;
+placeholders are omitted. `presentation.contentLanguage` always follows the
+effective idea content language, not `response.language`. English and Chinese
+content receive complete built-in presentation strings. Other canonical BCP 47
+tags use the explicit English `templateLanguage` fallback with
+`requiresLocalization: true`; the Agent localizes every human-visible
+presentation value before rendering and preserves machine identifiers. JSON
+retains full object IDs. When review is actionable, raw Markdown renders a
+12-character revision reference, primary reference, and the complete
+presentation object in a **Review candidate** section before lifecycle
+instructions.
 
 After readiness, an actionable selected idea or successful creation may add
 content-free `guidance` provenance to the public observation:
@@ -357,11 +587,16 @@ Observations are discriminated by command intent and `state`:
   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 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.
+  (`id`, optional `alias`, lifecycle `state`), including terminal ideas. V2
+  selections also include `control` (`owner`, nullable `lastTransfer`) and
+  `submissions` (`current` plus `ideal`, `inner`, and `outer`). Each phase
+  projection identifies its submit/accept pair, current revision, optional
+  submitted/accepted revisions, and `unsubmitted`, `submitted`, `accepted`, or
+  `stale` state. Active stale submissions project downstream control; completed
+  and abandoned ideas project `none`. 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
@@ -388,12 +623,26 @@ outside navigation; navigation enriches those references after readiness.
 Problems have only stable `type` and natural-language `summary`; remediation
 belongs in `response.nextSteps`.
 
-Project setup is ecosystem-neutral. It checks Git, configuration schema
-compatibility, and canonical skill content at `.agents/skills/silvermoon`.
-CRLF and LF are equivalent for valid UTF-8 skill text so Git checkout settings
-cannot create false drift; filenames and every other content change remain
-exact. The check does not inspect execution source or require a package manager,
-`package.json`, project-local Silvermoon dependency, or `node_modules`.
+Project setup is ecosystem-neutral. It checks Git, configuration schema,
+metadata schema, and layout. It does not inspect execution source, a package
+manager, `package.json`, project-local Silvermoon dependencies, `node_modules`,
+or repository skill paths. Runtime identity, update status, and personal skill
+registration are device facts and do not change a project snapshot result.
+
+Complete project observations expose `schemas`, containing the runtime
+capability-manifest version, its release boundary, and one record for every
+discovered config or idea-state file. Each record keeps `validity`
+(`valid`, `invalid`, or `unsupported`) independent from `readiness`
+(`current`, `migration-required`, `migration-unavailable`,
+`runtime-upgrade-required`, or `unknown`). It also names the schema family,
+declared and target versions, and any migration edge. JSON retains current
+records; human-readable output lists only files needing attention.
+
+`whats-next` and project writes require the current target. Read-only
+`list-ideas` may inspect a valid historical schema. Snapshot `check` treats a
+valid readable historical schema as valid while still returning its readiness
+record; future or malformed schemas fail validation without guessing their
+contents.
 
 `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
@@ -404,8 +653,9 @@ 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, validates optional preparing guidance from the same local `HEAD`,
+`create-idea` requires a local branch whose upstream identifies the configured
+primary repository and branch, plus a clean worktree; the local branch name is
+unrestricted. It validates optional preparing guidance from the same local `HEAD`,
 then creates one canonical scaffold. It does not fetch, compare remote
 ancestry, or require local HEAD to match the remote tip. Its optional
 content-language choice accepts any canonical BCP 47 tag, is normalized before
@@ -421,13 +671,15 @@ 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
+The query validates Git presence, configuration, 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. `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.
+accesses the project remote. Its independent device advisory may query npm
+`latest` only when the successful device cache is at least 24 hours old.
+`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
 
@@ -436,23 +688,36 @@ resolved output language is used.
 - `check --worktree` validates the hypothetical commit formed from `HEAD`, the
   index, unstaged changes, and nonignored untracked files.
 - `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 does not audit the history or provenance of retained
-  revision facts. Unrelated skill or idea findings in local `HEAD` do not block
+- `check --commit <revision>` validates one local commit and its first-parent
+  event boundary, without walking older commits.
+- `check --remote` fetches primary using committed coordinates and validates its
+  tip and its immediate event boundary for v2. 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. `--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,
-branch, merge/cherry-pick path, or retained decision reachability. A canonical
+action. `check` validates the selected snapshot's project contract: Git,
+configuration, idea layout, world revisions, status, and the complete optional
+phase guidance directory. It does not inspect personal skill registration or
+query npm for runtime freshness.
+For v1 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.
+V2 additionally reports `validation.eventHistory`: the fixed primary reference,
+the selected commit's first parent when applicable, and the current
+initialization/migration/append/repair boundary. Local targets use named primary
+tracking refs without fetching; unavailable or conflicting refs fail closed.
+Normal checks do not audit earlier commits; use `check --commit <revision>` to
+inspect a specific historical boundary. History rules depend on each
+base's complete reduction, not the candidate's failure: `ok: true` requires
+its exact byte prefix; definite `ok: false` permits a valid complete repair.
+Missing/invalidly encoded history never grants repair permission.
+The immediate predecessor prevents downgrading a v2 project to v1;
+genuine v1 historical snapshots remain readable without auditing their decisions.
 
 Like every public command, `check --json` contains all four projections:
 
@@ -535,14 +800,18 @@ 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
 guidance structure and content, and lifecycle derivation from the selected
-snapshot. They do not infer newly made decisions from a parent diff or audit
-decision provenance through history.
+snapshot. V2 also checks its state-event transitions and primary history, but
+neither format treats a Git diff as proof of human authorization.
 
 ## Schemas
 
+- [Capability manifest](../schema/capabilities.json)
+- [Capability manifest schema](../schema/capability-manifest.schema.json)
 - [Command report](../schema/v1/command-report.schema.json)
 - [Domain message](../schema/v1/domain-message.schema.json)
 - [Repository configuration](../schema/v1/config.schema.json)
+- [Event project configuration](../schema/v2/config.schema.json)
+- [Idea state event](../schema/v2/idea-event.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)

package/docs/repository-tasks.md

@@ -3,6 +3,12 @@
 This repository uses the local [Silvermoon skill](/skills/silvermoon/SKILL.md)
 and the fixed `.silvermoon/` metadata layout.
 
+This is Silvermoon's own source repository: every `silvermoon` command below
+means `node bin/silvermoon.js` from the current checkout, also available as
+`pnpm silvermoon`. Never use a global or published package here, and never
+add Silvermoon as its own dependency. Refresh the local skill with
+`pnpm sync:skills`.
+
 ## Authority
 
 The shared authority is `https://github.com/shazhou-ww/silvermoon.git` on
@@ -35,7 +41,8 @@ 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,
+requires a local branch whose upstream identifies the configured primary
+repository and branch, plus a clean worktree; the local branch name is unrestricted,
 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
@@ -52,34 +59,67 @@ canonical BCP 47 tag.
 
 `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.
+acceptance, deployment acceptance, and abandonment require an explicit decision.
+For a v1 project, record that decision in the idea's `status.yaml`.
+For a v2 project, including this source repository after its explicitly
+authorized migration, use the controlled
+[event protocol](../skills/silvermoon/references/events.md). Developing v2
+alone does not authorize migration of a checkout.
 
 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.
+For v2, append the current phase's matching `submitIdeal`, `submitInner`, or
+`submitOuter` for that exact synchronized revision, integrate the event through
+the same normal Git path, and reobserve. Do not request the matching acceptance
+while the submission is absent, stale, or effective control is downstream.
+Keep the review message short and follow the latest report's gate instruction.
+Use `response.review.presentation` verbatim when `requiresLocalization` is
+false; when true, localize every human-visible presentation value to its
+`contentLanguage` while preserving machine identifiers. A temporary report
+output language never controls gate prose. 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. Seed the index from `response.review`, including
+its exact primary commit and canonical documents. In v2, its presence confirms
+that the current exact submission is active and control is upstream; it is
+still not the human decision itself. The Agent adds only identity values, a
+one-sentence review focus, selected review-file links, and host-specific link
+targets in the compact order directed by `response.nextSteps`. Keep the
+complete object IDs internally for event recording. Do not add
+repeated gate-policy explanations or inline inventories of test, CI, deployment,
+or SLO evidence; keep those details in the linked artifacts. List only files
+with substantive review content: Ideal uses `Idea.md` and substantive
+same-world support; Implementation and Deployment each use their corresponding
+contract plus `ledger.md`, with other evidence added only when material. Render the index
+as a standalone, completed ordinary assistant Markdown turn. Never open an
+interactive decision in that same turn because the tool surface may hide queued
+prose. If a later turn uses 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. If that tool is unavailable or returns no
+choice, do not retry or repeat the rationale against unchanged state. 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
-`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.
+The required idea-root `ledger.md` is an execution checklist only, not
+operational prose, a decision log, or a discussion record. After repository
+hygiene and lifecycle routing, combine the reported `response.nextSteps`, world
+contracts, and unchecked Implementation or Deployment ledger entries to infer
+the next work. Do not record work notes or explanations in `ledger.md`. 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.
+
+Before the Ideal gate, preparation must replace the Implementation and
+Deployment scaffold placeholders with lightweight first versions of no more
+than three high-level steps and three observable criteria each, mirrored
+unchecked in the ledger. They are required feasibility context but remain
+outside the `acceptIdeal` review and decision scope.
 
 When a successful selected lifecycle report or `create-idea` report includes
 `response.guidance`, consume only that snapshot-bound field.
@@ -116,7 +156,8 @@ branches.
   `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.
+  project's snapshot and v2 primary event history, 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 uses all four projections; only
   `check --remote` normally records an action.