silvermoon 0.0.1

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "silvermoon",
+  "version": "0.0.1",
+  "description": "The project spirit that checks repository state and answers what's next.",
+  "packageManager": "pnpm@11.22.0",
+  "type": "module",
+  "bin": {
+    "silvermoon": "bin/silvermoon.js"
+  },
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "assets/silvermoon.svg",
+    "bin",
+    "skills/silvermoon",
+    "src",
+    "README.md",
+    "README.zh-CN.md",
+    "schema"
+  ],
+  "scripts": {
+    "check": "npm run check:quick && npm run test:integration && npm run pack:check && npm run test:e2e && npm run check:skills",
+    "check:quick": "node --check bin/silvermoon.js && npm test",
+    "check:skills": "npx skills add . --list",
+    "pack:check": "node scripts/check-pack.js",
+    "prepare:npm-release": "node scripts/prepare-npm-release.mjs",
+    "test": "npm run test:unit && npm run test:contract",
+    "test:contract": "node --test \"test/contract/*.test.*\"",
+    "test:e2e": "node --test \"test/e2e/*.test.*\"",
+    "test:integration": "node --test \"test/integration/*.test.*\"",
+    "test:unit": "node --test \"test/unit/*.test.*\""
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "keywords": [
+    "agent-skills",
+    "cli",
+    "project-state",
+    "repository",
+    "validation",
+    "whats-next"
+  ],
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/shazhou-ww/silvermoon.git"
+  },
+  "devDependencies": {
+    "ajv": "^8.20.0",
+    "semver": "^7.8.5"
+  },
+  "dependencies": {
+    "commander": "^14.0.3",
+    "marked": "^18.0.13",
+    "mdast-util-from-markdown": "^2.0.3",
+    "mdast-util-to-markdown": "^2.1.2",
+    "yaml": "^2.9.1"
+  }
+}

package/schema/v1/config.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/shazhou-ww/silvermoon/raw/refs/heads/main/schema/v1/config.schema.json",
+  "title": "Silvermoon repository configuration v1",
+  "description": "The repository-owned .silvermoon/config.yaml contract.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "primaryRepository",
+    "primaryBranch"
+  ],
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "primaryRepository": {
+      "$ref": "definitions.schema.json#/$defs/repository"
+    },
+    "primaryBranch": {
+      "$ref": "definitions.schema.json#/$defs/branch"
+    }
+  }
+}

package/schema/v1/definitions.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/shazhou-ww/silvermoon/raw/refs/heads/main/schema/v1/definitions.schema.json",
+  "title": "Silvermoon shared definitions v1",
+  "description": "Shared value definitions for Silvermoon version 1 storage contracts.",
+  "$defs": {
+    "branch": {
+      "type": "string",
+      "pattern": "^(?!-)(?!/)(?!@$)(?!refs/)(?!remotes/)(?!.*\\.\\.)(?!.*@\\{)(?!.*[ ~^:?*\\[\\\\])(?!.*(?:^|/)\\.)(?!.*(?:^|/)[^/]*\\.lock(?:/|$))(?!.*//$)(?!.*//)(?!.*\\.$)(?!.*\/$).+$"
+    },
+    "repository": {
+      "type": "string",
+      "format": "uri",
+      "pattern": "^https://(?:[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?|\\[[0-9a-f:.]+\\])(?::(?!443(?:/|$))[0-9]+)?/(?!/)(?!.*//)(?!.*\\\\)(?!.*(?:/\\.{1,2})(?:/|$))(?!.*%(?:2[eEfF]|5[cC]))(?!.*[?#])[^/](?:.*[^/])?$"
+    },
+    "ulid": {
+      "type": "string",
+      "pattern": "^[0-7][0-9A-HJKMNP-TV-Z]{25}$"
+    },
+    "objectId": {
+      "type": "string",
+      "pattern": "^(?:[0-9a-f]{40}|[0-9a-f]{64})$"
+    }
+  }
+}

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

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/shazhou-ww/silvermoon/raw/refs/heads/main/schema/v1/idea-status.schema.json",
+  "title": "Silvermoon idea status v1",
+  "description": "The repository-owned .silvermoon/ideas/<IDEA_ID>/status.yaml contract.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "version",
+    "id"
+  ],
+  "properties": {
+    "version": {
+      "const": 1
+    },
+    "id": {
+      "$ref": "definitions.schema.json#/$defs/ulid"
+    },
+    "alias": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 120,
+      "pattern": "^(?!\\s)(?!.*\\s$)[^\\u0000-\\u001f\\u007f-\\u009f]+$"
+    },
+    "abandoned": {
+      "const": true
+    },
+    "approvedRevision": {
+      "description": "Accepted Ideal World (道心) tree object ID.",
+      "$ref": "definitions.schema.json#/$defs/objectId"
+    },
+    "implementationAcceptedRevision": {
+      "description": "Accepted Inner World (内景) tree object ID.",
+      "$ref": "definitions.schema.json#/$defs/objectId"
+    },
+    "deploymentAcceptedRevision": {
+      "description": "Accepted Outer World (现世) tree object ID.",
+      "$ref": "definitions.schema.json#/$defs/objectId"
+    }
+  }
+}

package/skills/silvermoon/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: silvermoon
+description: "Navigate or create repository-owned ideas, execute one safe action, and reobserve only after an observable delta."
+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`, and
+   action or created idea as one immutable observation. Do not combine guidance
+   from different reports.
+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.
+
+## 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.
+- `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:
+
+```text
+.silvermoon/ideas/<ULID>/
+├── status.yaml
+├── ledger.md
+└── outer/
+    ├── Deployment.md
+    └── inner/
+        ├── Implementation.md
+        └── ideal/
+            └── 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.
+
+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
+
+### Steps
+
+- [x] **I-S01:** Completed step
+- [ ] **I-S02:** Remaining step
+
+### Acceptance criteria
+
+- [x] **I-AC01:** Proven criterion
+- [ ] **I-AC02:** Unproven criterion
+
+## Deployment
+
+### Steps
+
+- [ ] **D-S01:** Deployment step
+
+### 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.
+
+Follow [adoption.md](./references/adoption.md) when creating or explicitly
+converting a repository to Silvermoon.

package/skills/silvermoon/references/adoption.md

@@ -0,0 +1,122 @@
+# Silvermoon adoption
+
+## New repositories
+
+Start with a complete, read-only diagnosis, even in an unfamiliar repository:
+
+```sh
+npx silvermoon@<version> whats-next --json
+```
+
+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`.
+
+Install and synchronize explicitly:
+
+```sh
+npm install --save-dev --save-exact silvermoon@<version>
+npx skills add ./node_modules/silvermoon/skills --skill silvermoon --agent github-copilot --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.
+
+Create `.silvermoon/config.yaml` with the fixed version 1 contract:
+
+```yaml
+version: 1
+primaryRepository: https://example.com/owner/repository.git
+primaryBranch: main
+```
+
+The URL is credential-free canonical HTTPS shared state; local Git credentials
+and URL rewrites remain machine-local. Metadata and idea paths are fixed.
+
+Commit the configuration, then run:
+
+```sh
+silvermoon check --commit HEAD
+silvermoon check --remote
+silvermoon create-idea --json
+silvermoon whats-next <ULID> --json
+```
+
+Create or repair configuration through ordinary reviewed file editing.
+Silvermoon reports every configuration finding but has no init or setup command.
+
+## Idea storage
+
+Each idea is self-contained:
+
+```text
+.silvermoon/ideas/<ULID>/
+|-- status.yaml
+|-- ledger.md
+`-- outer/
+    |-- Deployment.md
+    `-- inner/
+        |-- Implementation.md
+        `-- ideal/
+            `-- 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.
+
+The nested opaque Git trees produce `idealRevision`,
+`implementationRevision`, and `deploymentRevision`. Inner World includes Ideal
+World; Outer World includes both nested worlds. `status.yaml` and required
+`ledger.md` are outside all three revisions. Silvermoon requires ledger as a
+regular file but does not parse its body.
+
+Write implementation and deployment plans under `## Steps` and their outcome
+contracts under `## Acceptance criteria`. Give every item a stable level-three
+`I-Sxx`, `I-ACxx`, `D-Sxx`, or `D-ACxx` heading. Each criterion describes both
+the observable outcome and how to prove it. Keep task-list checkboxes out of
+world contracts.
+
+Agents mirror those stable IDs and short titles into the required `ledger.md`
+under Implementation and Deployment Steps and Acceptance criteria checklists.
+Update both files together, and reset a checked item when its requirement or
+proof changes materially. Checkboxes record Agent work only, never human
+approval or acceptance.
+
+```yaml
+version: 1
+id: 01M36QGPNTXEPP61DA4KP4AVZF
+alias: publish-documentation
+```
+
+Status may additionally contain canonical `abandoned: true`,
+`approvedRevision`, `implementationAcceptedRevision`, and
+`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,
+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
+until their lifecycle actions. An Agent may add a concise, unique alias derived
+from the user's request without asking the user to choose a name.
+
+## Adopting from another layout
+
+Silvermoon deliberately has no runtime compatibility mode or in-place migration
+command. It recognizes only `.silvermoon/config.yaml` and the fixed nested
+world layout. A repository containing only another configuration or idea layout
+is unconfigured.
+
+Prepare one reviewed cutover commit with ordinary repository tools. Preserve
+old Git history, inspect every retained outcome, and record only decisions that
+have explicit evidence for the exact corresponding world revision. Silvermoon
+does not read, merge, move, delete, diagnose, or infer facts from old layouts.
+
+Run `silvermoon check --worktree`, stage the candidate, run the staged and
+commit checks, publish non-force, then run the remote check against complete
+primary history.