silvermoon 0.0.2 → 0.1.0

package/skills/silvermoon/SKILL.md

@@ -1,111 +1,106 @@
 ---
 name: silvermoon
-description: "Navigate or create repository-owned ideas, execute one safe action, and reobserve only after an observable delta."
+description: "Navigate or create repository-owned ideas from layered observations and ordered safe instructions."
 argument-hint: "[new | idea ULID or alias]"
 user-invocable: true
 ---
 
 # Silvermoon
 
-Use Silvermoon to navigate or explicitly create ideas against the configured
-remote primary. The CLI derives idea state and checks repository hygiene; the
-Agent performs suggested repository or external actions through ordinary tools
-and Git.
-
-## Start From Primary
-
-1. Preserve the user's intent when choosing the entry command:
-   - For `/silvermoon new` or any other explicit request to create a new idea,
-     run `silvermoon create-idea --json`.
-   - Otherwise run `silvermoon whats-next [idea] --json`. Pass the selector only
-     when the user supplied or previously selected one.
-2. Treat the command, request, `observedPrimaryCommit`, `selectedIdea`,
-   effective `language`, and action or created idea as one immutable
-   observation. Do not combine guidance from different reports. Use the
-   reported language for natural-language world content, supporting artifacts,
-   ledger text, and user-facing explanations; preserve commands, identifiers,
-   schema fields, protocol markers, and verbatim tool output.
-3. Read the complete `onboarding` doctor report. It lists every requirement,
-   status, blocking flag, dependency, structured remediation, recommended
-   action, and recheck command. For `adopt-silvermoon`, execute only the
-   recommended explicit remediation (or safely resolve its conflict), then
-   recheck; do not route idea work while blocking findings remain.
-4. Execute only the highest-priority action. Do not skip worktree, conflict,
-   sync, or selection guidance to reach a later idea-state action. An explicit
-   create request is not idea selection: after resolving a blocking hygiene
-   action, retry `create-idea`, not selector-less `whats-next`.
-
-`whats-next` may fetch and inspect. It never checkout, merges, edits, commits,
-stashes, deletes, resets, fast-forwards, or pushes. `create-idea` runs the same
-hygiene preflight and, only when it passes, creates the structured idea scaffold.
-Dependency installation and skill registration are separate explicit
-operations. The packaged skill is canonical, while registration and updates
-belong to the supported `npx skills add` interface. Silvermoon reports
-configuration and skill findings but owns no onboarding mutation command.
+Use Silvermoon to navigate or create ideas against the configured primary.
+The CLI observes repository and lifecycle state; the Agent performs instructed
+repository or external actions with ordinary tools and Git.
+
+## Choose And Run The Command
+
+- `/silvermoon new` and other explicit new-idea requests use
+  `silvermoon create-idea`. Otherwise use `silvermoon whats-next [idea]`, passing
+  a selector only when the user supplied or previously selected it.
+- Bare `whats-next` lists active ideas and offers creation, even when exactly one idea is active.
+  Never infer selection; require an explicit ULID or alias.
+- Use `--json` only when a programmatic consumer needs the envelope.
+- Treat each command's `intention`, `observation`, `outcomes`, and `instructions`
+  as one report. Read every problem and all ordered instructions; never combine
+  reports.
+  `project-setup-required` blocks repository work, `repository-sync-required`
+  blocks idea routing, and `repository-preparation-required` blocks creation.
+  Reobserve after resolving a blocker or making an expected change.
+- Markdown is a rendering of the report, not a second decision model. A
+  selected idea reports its lifecycle state; creation reports its new identity.
+
+`whats-next` may fetch and inspect but never changes files, branches, index, or
+refs. `create-idea` requires the configured primary branch and upstream plus a
+clean worktree; it does not fetch or compare ancestry. The target does not need
+a package manifest, package manager, Silvermoon dependency, or `node_modules`.
+The packaged skill is canonical; register it at `.agents/skills/silvermoon`
+with the supported `npx skills add` universal target. Silvermoon reports setup
+problems but does not repair them.
+
+`check` validates only a project snapshot; it does not navigate ideas or check
+repository synchronization. Default `check` validates committed `HEAD`;
+`--worktree` validates the full candidate and `--staged` the index. Its JSON
+contains `intention` and `observation` only. Exit `0` means valid, `1` invalid
+or unavailable, and `2` invalid usage. Never commit unless the relevant check
+exits `0`.
 
 ## Preserve Work
 
-- Read exact staged, unstaged, and untracked diffs before deciding ownership.
-- Preserve unknown, unrelated, or user-authored changes. Isolate them in
-  another worktree or use an explicitly described stash only when needed.
-- Delete only paths created by the current operation or paths the user names
-  after reviewing the current diff.
-- Never use force-push, `reset --hard`, broad clean commands, or silent history
-  rewrites to satisfy guidance.
-- Publish with the observed primary tip as the expected remote tip. On rejection
-  or concurrent movement, fetch and call `whats-next` again; never replay a stale
-  approval or acceptance automatically.
-
-## Execute Actions
-
-- `select-active-idea`: show the ordered candidates and obtain one explicit
-  ULID or alias selection.
-- `continue-active-idea`: call `whats-next <id>` to obtain state guidance.
-- `create-idea`: this action is internal to the explicit `create-idea` command's
-  preflight; do not replace the user's create intent with active-idea
-  selection. After hygiene passes, the command creates one self-contained idea
-  with structured `Idea.md`, `Implementation.md`, `Deployment.md`, and
-  `ledger.md` entries plus alias-less `status.yaml`. It never stages, commits,
-  pushes, or records a decision. Review every generated path before
-  publication. During initial preparation, replace the `Idea.md` guidance with
-  the requested Ideal World contract, but keep the Implementation, Deployment,
-  and matching ledger placeholders synchronized until their lifecycle actions.
-  An Agent may add a concise, unique alias derived from the user's request;
-  do not interrupt the user only to ask them to name it.
-  When the user explicitly requests a stable language for the new idea, pass
-  `--language <tag>`; otherwise omit it so the idea dynamically inherits the
-  project, user, or `en-US` default. Never add a language override to
-  `whats-next` or `check`.
-- `switch-to-primary`, `resolve-conflicts`, `inspect-worktree-changes`,
-  `fast-forward-primary`, `integrate-primary`, `publish-primary`: perform the
-  exact Git hygiene step without discarding either history or unknown work.
-- `prepare-idea`: edit `Idea.md` and supporting files in the Ideal World
-  (道心). Supporting files must serve `Idea.md`, never replace it as a second
-  contract. After lifecycle hygiene, use the reported `ledgerPath` to resume
-  relevant unfinished work. After explicit approval, write the reported
-  `idealRevision` to `approvedRevision`.
-- `implement-idea`: edit `Implementation.md`, its supporting Inner World
-  (内景) files, and repository deliverables. Do not change the nested Ideal
-  World unless the ideal truly changed and should return to preparing. After
-  lifecycle hygiene, use the reported `ledgerPath` to resume relevant
-  unfinished work. After explicit acceptance, write the reported
-  `implementationRevision` to `implementationAcceptedRevision`.
-- `deploy-idea`: use `Deployment.md` and its supporting Outer World (现世)
-  files to drive and verify the external world. Do not change repository
-  deliverables as deployment work or modify a nested world unless that earlier
-  contract truly changed. Publish a newly authored or materially changed
-  deployment contract first, reobserve its stable `deploymentRevision`, then
-  execute external checks against that revision and record their completion in
-  the ledger. After lifecycle hygiene, use the reported `ledgerPath` to resume
-  relevant unfinished work. After explicit acceptance, write the reported
-  `deploymentRevision` to `deploymentAcceptedRevision`.
-- `review-abandoned`: keep `abandoned: true`, remove it after an explicit human
-  decision, or create a different idea.
-- `review-completed`: revise the existing idea definition or create a new idea.
-
-## Author The Three Worlds
-
-Every idea uses this fixed structure:
+- Inspect all staged, unstaged, and untracked changes before acting. Preserve
+  unknown, unrelated, or user-authored work; isolate it or use only an
+  explicitly described stash when necessary.
+- Never use force-push, reset, broad clean, or silent history rewrites. Delete
+  only operation-owned paths or paths the user explicitly names.
+- Follow reported synchronization steps in order and use the reported primary
+  tip as the expected remote tip. On rejection or concurrent movement, preserve
+  both histories and reobserve; never replay a stale decision.
+
+## Create And Publish An Idea
+
+`create-idea` creates only the scaffold: `Idea.md`, `Implementation.md`,
+`Deployment.md`, `ledger.md`, and `status.yaml`. It never stages, commits,
+pushes, or records a decision. Preserve explicit creation intent through
+hygiene retries: retry `create-idea`, not bare `whats-next`.
+
+During preparation, complete the `Idea.md` ideal contract. Keep the
+Implementation, Deployment, and matching ledger placeholders synchronized
+until their lifecycle actions. Review every generated path and validate the
+candidate, then commit and publish it to configured primary through the normal
+non-force path before asking the user to review or approve it. Verify the commit
+is reachable from refreshed primary and reobserve the exact `idealRevision`.
+If publication requires a pull request, wait until it reaches primary. If
+publication is blocked, say the candidate is not yet available for cross-device
+review; never ask for approval of unpublished content. Publication is not
+approval and must not change `status.yaml`.
+
+An Agent may derive a concise, unique alias; do not ask for a name solely for
+the alias. Pass `--language <tag>` only when the user explicitly requests a
+stable language override. Do not use that option with `whats-next` or `check`.
+
+## Continue The Selected Idea
+
+Use the reported `ledgerPath` after lifecycle hygiene and continue only the
+selected world's unfinished work:
+
+- **Preparing:** Edit `Idea.md` and supporting Ideal World (理想世界) files.
+  Supporting files serve the contract, not replace it. After explicit approval,
+  record the reported `idealRevision` as `approvedRevision`.
+- **Implementing:** Edit `Implementation.md`, supporting Inner World (主体世界)
+  files, and repository deliverables. Change the ideal only if it truly changed
+  and the idea must return to preparing. After explicit acceptance, record the
+  reported `implementationRevision` as `implementationAcceptedRevision`.
+- **Deploying:** Use `Deployment.md` and supporting Outer World (现实世界) files
+  to drive and verify external outcomes; do not change repository deliverables.
+  Publish a new or materially changed deployment contract first, reobserve its
+  stable `deploymentRevision`, then run checks against it and record evidence
+  in the ledger. After explicit acceptance, record the reported
+  `deploymentRevision` as `deploymentAcceptedRevision`.
+- **Abandoned:** Keep canonical `abandoned: true`, remove it only after an
+  explicit reversal, or choose another idea.
+- **Completed:** Revise its definition or create a different idea.
+
+## Author Contracts And Continue From The Ledger
+
+Each idea has three canonical entries:
 
 ```text
 .silvermoon/ideas/<ULID>/
@@ -119,98 +114,58 @@ Every idea uses this fixed structure:
             └── Idea.md
 ```
 
-`Idea.md` is the canonical Ideal World (道心) entry, `Implementation.md` is the
-canonical Inner World (内景) entry, and `Deployment.md` is the canonical Outer
-World (现世) entry: 道心立意，内景成形，现世验真. Each world may contain
-additional files and nested directories, but those artifacts support their
-same-world entry and do not define a second contract.
+`Idea.md` is the Ideal World (理想世界) ideal contract, `Implementation.md` is
+the Inner World (主体世界) inner implementation contract, and `Deployment.md`
+is the Outer World (现实世界) real-world deployment contract. Each world may
+contain supporting files, but those artifacts serve the same-world entry and
+never define a second contract.
 
 In `Implementation.md` and `Deployment.md`, put plans under `## Steps` and
-outcome contracts under `## Acceptance criteria`. Give every step and criterion
-a stable level-three heading: `I-Sxx`, `I-ACxx`, `D-Sxx`, or `D-ACxx`. A
-criterion must describe both its observable outcome and the method that proves
-it; do not add a separate validation section. Keep checkboxes out of world
-contracts. World content changes its world revision and every containing world
-revision; `status.yaml` and `ledger.md` stay outside all three world trees.
-
-## Continue From The Ledger
-
-Every idea has an Agent-owned `ledger.md` at the path reported by `whats-next`.
-It is operational state, not a fourth world, normative contract, or human
-decision. Silvermoon requires the regular file but does not parse its body or
-derive lifecycle state from it.
-
-Mirror stable IDs and short titles from both world contracts:
-
-```markdown
-# Ledger
-
-## Implementation
-
-### Implementation steps
-
-- [x] **I-S01:** Completed step
-- [ ] **I-S02:** Remaining step
-
-### Implementation acceptance criteria
-
-- [x] **I-AC01:** Proven criterion
-- [ ] **I-AC02:** Unproven criterion
-
-## Deployment
-
-### Deployment steps
-
-- [ ] **D-S01:** Deployment step
-
-### Deployment acceptance criteria
-
-- [ ] **D-AC01:** Deployment criterion
-```
-
-When adding or removing a world step or criterion, update the matching ledger
-entry in the same change. Keep its stable ID when only the title or details are
-refined. Add new entries unchecked. If a completed item's requirement or proof
-method changes materially, reset its checkbox and re-run the work or proof.
-Infer the next action from `whats-next`, the world contracts, and unchecked
-ledger entries; do not maintain duplicate Current or Next summaries.
-If relevant ledger entries remain unchecked, continue the reported world
-action. If all relevant entries are checked, their evidence remains valid, and
-the candidate is published, stop editing and request explicit acceptance for
-the exact revision reported by `whats-next`.
-
-`[x]` means only that the Agent recorded work or a check as complete. It never
-approves an Ideal World, accepts implementation or deployment, changes
-`status.yaml`, or authorizes publication. Record test names, commands,
-artifacts, and results in the corresponding world criterion or concise ledger
-notes without creating a separate evidence schema or public API contract.
-
-## Write Status Facts
-
-Silvermoon has no approval, acceptance, or abandonment mutation commands.
-Update the idea's `status.yaml` with ordinary file editing:
-
-1. Reconfirm the decision applies to the selected idea and current
-   world revision reported by `whats-next`.
-2. Add or update only the corresponding revision field, or add/remove canonical
-   `abandoned: true` after an explicit human decision.
-3. Run `silvermoon check --worktree --json` while reviewing the complete
-  candidate, then stage it and run `silvermoon check --staged --json`.
-4. Commit the status decision separately when practical, then non-force push
-   with the observation's `observedPrimaryCommit` as expected tip.
-
-Never infer a human decision from silence, prose, Git activity, or an outer
-command. Old revision values remain as history and become inactive naturally
-when the idea folder changes.
-
-## Advance The Loop
-
-Re-run the intent-preserving entry command only after an expected repository
-delta, an unexpected input change, or a newly arrived external result: use
-`create-idea` for a pending explicit creation and `whats-next` otherwise. End
-the current turn when waiting for human/external input. Report an actionable
-error with its recovery condition, or report no progress and stop if guidance
-completed without a delta. Never poll the same observation.
+outcomes under `## Acceptance criteria`. Use stable level-three IDs: `I-Sxx`,
+`I-ACxx`, `D-Sxx`, and `D-ACxx`. Each criterion states an observable outcome
+and how to prove it. Do not put checkboxes in world contracts. World content
+changes its world revision and containing revisions; `status.yaml` and
+`ledger.md` are outside those trees.
+
+The required idea-root `ledger.md` is operational memory, not a fourth world,
+contract, or human decision. Mirror the stable IDs and short titles for
+Implementation and Deployment steps and criteria. Update ledger entries with
+their contract changes; add new items unchecked and reset completed items when
+requirements or proof change materially. If relevant entries remain unchecked,
+continue the reported work. If they are all checked, evidence remains valid,
+and the candidate is published, stop and request the appropriate explicit
+acceptance. A checked box records Agent work only; it never approves, accepts,
+changes status, or authorizes publication.
+
+## Record Decisions And Request Review
+
+Silvermoon has no approval, acceptance, or abandonment mutation commands. After
+an explicit human decision, reconfirm it applies to the selected idea and exact
+revision from `whats-next`; change only the corresponding status fact. Never
+infer a decision from silence, prose, Git activity, ledger checkboxes, or an
+outer command.
+
+Before requesting approval or acceptance, identify the idea by alias and ULID,
+state the decision and exact reported world revision, and include a clickable
+permalink to the canonical entry at the published primary commit: `Idea.md`
+for ideal approval, `Implementation.md` for implementation acceptance, or
+`Deployment.md` for deployment acceptance. Prefer a commit-pinned web URL (for
+GitHub, `/blob/<commit>/<path>`), not a local path or moving branch link.
+Confirm the commit is reachable from refreshed primary. If no reliable
+permalink can be formed, give the commit and repository-relative path and
+explain why; never provide a misleading link. Publication and links enable
+review but do not constitute the user's decision.
+
+For status changes, validate with `silvermoon check --worktree`, stage the
+candidate, then run `silvermoon check --staged`. Commit separately when
+practical and publish non-force using the latest reported primary tip.
+
+## Advance Safely
+
+Rerun the intent-preserving command only after an expected repository change,
+unexpected input, or new external result. Stop when waiting for a human or
+external result; do not poll an unchanged observation. Report actionable
+blockers and their recovery condition.
 
 Follow [adoption.md](./references/adoption.md) when creating or explicitly
 converting a repository to Silvermoon.

package/skills/silvermoon/references/adoption.md

@@ -2,28 +2,33 @@
 
 ## New repositories
 
-Start with a complete, read-only diagnosis, even in an unfamiliar repository:
+Start with a complete diagnosis, even in an unfamiliar repository:
 
 ```sh
-npx silvermoon@<version> whats-next --json
+npx silvermoon@<version> whats-next
 ```
 
-The report distinguishes source checkout, project-local, temporary, global,
-and unknown execution; lists all requirements and findings with dependencies;
-and provides structured remediation plus a recheck command. Temporary
-execution is only a bootstrap authority. Adopt its exact version, install it
-project-locally, and thereafter use `npx --no-install silvermoon`.
+The dialogue uses lightweight Markdown headings for intention, observation,
+and ordered instructions. It includes actions and outcomes only if side
+effects were attempted. Add `--json` only when a programmatic consumer needs
+the `intention / observation / outcomes / instructions` envelope (including
+`outcomes: []` when none were attempted).
+The command may fetch after local readiness passes, but it does not move the
+worktree, index, branches, or named refs.
 
-Install and synchronize explicitly:
+The target repository may use any language or build ecosystem. It does not
+need `package.json`, a package manager, a Silvermoon dependency, or
+`node_modules`. Use any compatible Silvermoon installation, and register the
+canonical skill bundled with that running installation:
 
 ```sh
-npm install --save-dev --save-exact silvermoon@<version>
-npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent github-copilot --yes --copy
+npx skills add <path-to-running-silvermoon>/skills --skill silvermoon --agent universal --yes --copy
 ```
 
-The npm package ships the canonical skill. Installation never writes tracked
-skill files. Registration and updates belong to `npx skills`; Silvermoon
-diagnoses the resulting repository-local content but never overwrites it.
+This writes the single repository-local registration at
+`.agents/skills/silvermoon`. Registration and updates belong to `npx skills`;
+Silvermoon compares that path with its bundled canonical skill but never
+overwrites it.
 
 Create `.silvermoon/config.yaml` with the fixed version 1 contract:
 
@@ -41,10 +46,18 @@ Commit the configuration, then run:
 ```sh
 silvermoon check --commit HEAD
 silvermoon check --remote
-silvermoon create-idea --json
-silvermoon whats-next <ULID> --json
+silvermoon create-idea
+silvermoon whats-next <ULID>
 ```
 
+`check` validates the selected project snapshot only; it does not navigate
+ideas or check worktree hygiene and upstream. Default `check` validates
+committed `HEAD`, whereas `check --staged` validates the index for pre-commit
+hooks. Its JSON contains only `intention` and `observation`; it does not
+include dialogue `outcomes` or `instructions`. Exit code `0` means valid,
+`1` means invalid or unavailable, and `2` means invalid CLI usage. A failed
+or unavailable check must not allow a commit.
+
 Create or repair configuration through ordinary reviewed file editing.
 Silvermoon reports every configuration finding but has no init or setup command.
 
@@ -64,10 +77,11 @@ Each idea is self-contained:
             `-- Idea.md
 ```
 
-Ideal World (道心) uses `Idea.md`, Inner World (内景) uses
-`Implementation.md`, and Outer World (现世) uses `Deployment.md`: 道心立意，
-内景成形，现世验真. Each world may have supporting files and directories,
-but they serve rather than replace the canonical same-world entry.
+Ideal World (理想世界) uses the `Idea.md` ideal contract.
+Inner World (主体世界) uses the `Implementation.md` inner implementation
+contract. Outer World (现实世界) uses the `Deployment.md` real-world
+deployment contract. Each world may have supporting files and directories, but
+they serve rather than replace the canonical same-world entry.
 
 The nested opaque Git trees produce `idealRevision`,
 `implementationRevision`, and `deploymentRevision`. Inner World includes Ideal
@@ -98,7 +112,7 @@ Status may additionally contain canonical `abandoned: true`,
 `deploymentAcceptedRevision` in that order. Decisions must bind to their
 corresponding current world revision.
 
-For a new scaffold, run `silvermoon create-idea --json`. It generates the ULID,
+For a new scaffold, run `silvermoon create-idea`. It generates the ULID,
 four structured documents and alias-less status; it does not stage, commit,
 push, approve, or accept. During initial preparation, complete `Idea.md` while
 keeping the Implementation, Deployment, and ledger placeholders synchronized