silvermoon 0.0.1 → 0.0.3

package/docs/npm-package-releases.md

@@ -0,0 +1,139 @@
+# npm package releases
+
+This repository publishes an allowlisted package when an authorized
+tag under `npm/` reaches GitHub. The tag is a release instruction; the package
+manifest at the tagged commit remains authoritative for the package name and
+version.
+
+The current release mapping is:
+
+| Release key | Package | Directory |
+| --- | --- | --- |
+| `silvermoon` | `silvermoon` | `.` |
+
+A stable tag such as `npm/silvermoon/v0.1.1` publishes with the npm `latest`
+dist-tag. A named prerelease such as `npm/silvermoon/v0.2.0-beta.1` publishes
+with the `beta` dist-tag. Numeric-only prerelease channels are intentionally
+rejected.
+
+## One-time configuration
+
+### npm trusted publisher
+
+In the npm package settings, add a GitHub Actions trusted publisher with these
+exact values:
+
+- Organization or user: `shazhou-ww`
+- Repository: `silvermoon`
+- Workflow filename: `publish-npm.yml`
+- Environment: `npm`
+- Allowed action: direct `npm publish`
+
+The workflow filename is identity-sensitive on npm. If it changes, update the
+npm trusted-publisher configuration before attempting another release. Do not
+create an npm automation token or store `NPM_TOKEN` or `NODE_AUTH_TOKEN` in
+GitHub secrets; the workflow uses GitHub OIDC with `id-token: write`.
+
+### GitHub environment
+
+Create an environment named `npm`. Limit deployments to protected tags in the
+`npm/**` namespace. Add required reviewers when the repository needs a manual
+release approval; the workflow itself does not require a repository secret.
+
+The npm trusted publisher and the workflow environment name must remain the
+same. A mismatch prevents npm from accepting the OIDC identity.
+
+The workflow uses a GitHub-hosted runner, `id-token: write`, Node 24,
+`actions/setup-node` with `registry-url: https://registry.npmjs.org`, and a
+pinned npm CLI version at or above `11.5.1`. These are source-controlled OIDC
+preconditions; do not replace them with a write token.
+
+### Tag ruleset
+
+Create an active GitHub tag ruleset targeting `npm/**`. Restrict tag creation,
+update, and deletion to the release maintainers or a dedicated release team.
+Do not allow release tags to be moved after creation. The workflow independently
+fetches `origin/main` and rejects a tagged commit that is not reachable from
+that refreshed branch.
+
+Tag protection is part of the trust boundary: GitHub loads a workflow from the
+tagged commit, so only authorized maintainers should be able to create tags in
+the release namespace.
+
+## Publish a version
+
+1. Update the selected package's `version` in its committed `package.json`.
+2. Run `pnpm install --frozen-lockfile` and `pnpm check`. The complete check
+   includes unit, contract, integration, package contents, installed-package
+   E2E, and skill discovery.
+3. Merge the version change to `main`; do not tag an unmerged branch or local
+   working tree.
+4. When the release is a deployment criterion of an active Silvermoon idea,
+   record implementation acceptance for the approved current idea revision,
+   publish that status-only commit, and require `silvermoon whats-next <idea>` to
+   return `deploy-idea`. Never create the release tag while the idea still
+   derives `implementing`.
+5. Fetch the current primary branch and tags.
+6. Create the package-specific tag at `origin/main` and push that exact tag.
+
+For `silvermoon@0.1.1`:
+
+```sh
+git fetch origin main --tags
+git tag npm/silvermoon/v0.1.1 origin/main
+git push origin refs/tags/npm/silvermoon/v0.1.1
+```
+
+The tag version must exactly equal [`package.json`](../package.json). The
+workflow never edits a manifest or chooses a version.
+
+The [`publish-npm.yml`](../.github/workflows/publish-npm.yml) workflow then:
+
+1. verifies the tagged commit is reachable from refreshed `origin/main`;
+2. installs the frozen pnpm dependencies;
+3. runs the allowlisted release planner and confirms the version is absent
+   from npm;
+4. runs `pnpm test:unit`, `pnpm test:contract`, `pnpm test:integration`, and
+   `pnpm check:skills`;
+5. runs the selected package's `npm run pack:check` and
+   `npm run test:e2e`; and
+6. publishes only the selected directory with provenance and the derived npm
+   dist-tag.
+
+Release runs are serialized within this repository. The registry preflight and
+`npm publish` cannot form one cross-system transaction, so an external
+publisher could still win that interval; npm then atomically rejects the
+duplicate publication without replacing the existing version.
+
+## Failure behavior
+
+Publication stops before `npm publish` when the tag is malformed, the release
+key is unknown, the package is private, the package name or version differs
+from the mapping and tag, the npm publish configuration is not public npmjs,
+the commit is outside `origin/main`, the version already exists, registry state
+cannot be verified, or validation fails.
+
+For a transient GitHub or registry failure before publication, rerun the same
+workflow run. Do not move or recreate the tag. For a source, manifest, or
+validation failure, make a new commit on `main`, choose a new version, and push
+a new tag after the fix is merged. npm versions and release tags are immutable.
+
+## Add another package
+
+1. Give the package a committed canonical `name`, SemVer `version`, and
+   `publishConfig` with `access: public` and registry
+   `https://registry.npmjs.org/`.
+2. Add a fixed release-key entry to `RELEASE_PACKAGES` in
+   [`prepare-npm-release.mjs`](../scripts/prepare-npm-release.mjs). Never derive
+   a filesystem path directly from tag text.
+3. Extend the release tests with the package selection, identity, version, and
+   dist-tag cases.
+4. Add the same `publish-npm.yml` trusted publisher to that npm package, using
+   the `npm` environment.
+5. Keep its tags under the protected `npm/<release-key>/v<semver>` convention.
+
+Run `node --test test/unit/prepare-npm-release.test.mjs
+test/integration/prepare-npm-release.test.mjs
+test/contract/npm-release.test.mjs` for focused release validation and
+`pnpm check` for the complete repository suite before merging the mapping
+change.

package/docs/operations.md

@@ -0,0 +1,110 @@
+# Operating Silvermoon
+
+This guide is the authoritative routine workflow for navigating, changing, and
+publishing Silvermoon ideas.
+
+## Navigate
+
+```sh
+npx silvermoon whats-next
+npx silvermoon whats-next 01M36QGPNTXEPP61DA4KP4AVZF
+npx silvermoon whats-next publish-documentation --json
+```
+
+Without a selector, Silvermoon asks for a choice among multiple active ideas,
+continues a single active idea, or reports that a new idea can be created. A
+selector is either a canonical uppercase ULID or an exact, unique,
+case-sensitive alias.
+
+Each successful report includes the effective `language` tag and its `idea`,
+`project`, `global`, or `default` source. Its action guidance requires the
+Agent to use that language for world entries, same-world supporting artifacts,
+the ledger, and user-facing explanations. Commands, identifiers, schema fields,
+protocol markers, and verbatim tool output retain their original form.
+
+Every invocation first checks the configured primary branch, merge conflicts,
+worktree changes, and local/remote primary ancestry. It may fetch and inspect,
+but it never edits, checks out, merges, commits, stashes, deletes, resets,
+fast-forwards, or pushes.
+
+## Create An Idea
+
+Explicit creation uses:
+
+```sh
+npx silvermoon create-idea --json
+npx silvermoon create-idea --language zh-cn --json
+```
+
+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.
+
+`--language` is the only command-level language override. It normalizes a valid
+BCP 47 tag and writes it to the new idea's `status.yaml`. Without the option,
+creation writes no language field and the idea dynamically inherits project,
+user, or `en-US` defaults. `whats-next` and `check` do not accept the option.
+
+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.
+
+## Execute One Action
+
+Treat the command, request, `observedPrimaryCommit`, selected idea, and action
+as one immutable observation. Execute only the highest-priority action.
+
+Repository hygiene actions take precedence over lifecycle work. Inspect exact
+staged, unstaged, untracked, and conflicted paths; preserve unknown and
+concurrent work. Never force-push, use `reset --hard`, broadly clean the
+worktree, or silently rewrite history to satisfy guidance.
+
+After an observable change, run `whats-next` again. Do not poll an unchanged
+observation.
+
+## Author World Contracts
+
+`Idea.md` is the Ideal World entry. `Implementation.md` and `Deployment.md`
+contain `## Steps` and `## Acceptance criteria`. Every item uses a stable
+level-three heading:
+
+- implementation steps: `I-Sxx`
+- implementation criteria: `I-ACxx`
+- deployment steps: `D-Sxx`
+- deployment criteria: `D-ACxx`
+
+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.
+
+## Record A Human Decision
+
+After an explicit decision, reconfirm that it applies to the selected idea and
+the current reported world revision. Edit only the corresponding status fact:
+
+- `approvedRevision`
+- `implementationAcceptedRevision`
+- `deploymentAcceptedRevision`
+- canonical `abandoned: true`, or remove it after an explicit reversal
+
+Validate the complete candidate:
+
+```sh
+npx silvermoon check --worktree --json
+git add .silvermoon/ideas/<ULID>/status.yaml
+npx silvermoon check --staged --json
+```
+
+Prefer a status-only decision commit, publish through the repository's normal
+non-force path, and verify the commit is reachable from refreshed primary.
+
+## 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.

package/docs/reference.md

@@ -0,0 +1,138 @@
+# Technical Reference
+
+This page is the authoritative reference for Silvermoon storage, revisions,
+derived state, CLI reports, and validation.
+
+## Fixed Storage Layout
+
+Each idea is self-contained under one canonical uppercase ULID:
+
+```text
+.silvermoon/
+|-- config.yaml
+`-- ideas/
+    `-- 01M36QGPNTXEPP61DA4KP4AVZF/
+        |-- status.yaml
+        |-- ledger.md
+        `-- outer/
+            |-- Deployment.md
+            `-- inner/
+                |-- Implementation.md
+                `-- ideal/
+                    `-- Idea.md
+```
+
+Every world may contain supporting files and directories, but they serve the
+canonical same-world entry and never define another contract. Metadata paths
+are fixed regular files and directories.
+
+The optional user configuration is always
+`~/.config/silvermoon/config.yaml`, on every platform. It is outside the
+repository and contains version 1 plus an optional `preferredLanguage`.
+Missing user configuration means no user preference; an invalid or unreadable
+explicit file is an error rather than a silent fallback.
+
+The repository configuration accepts optional `preferredLanguage` after
+`primaryBranch`. Stored language values are canonical BCP 47 tags.
+
+## World Revisions
+
+Each world is an opaque Git tree:
+
+- `idealRevision` identifies `ideal/`.
+- `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
+object format in use determines revision shape; Silvermoon validates object
+types and candidate bindings rather than interpreting world contents.
+
+## Status File
+
+```yaml
+version: 1
+id: 01M36QGPNTXEPP61DA4KP4AVZF
+alias: publish-documentation
+language: zh-CN
+approvedRevision: 0123456789abcdef0123456789abcdef01234567
+implementationAcceptedRevision: 0123456789abcdef0123456789abcdef01234567
+deploymentAcceptedRevision: 0123456789abcdef0123456789abcdef01234567
+```
+
+`version` and `id` are required. `alias` and canonical BCP 47 `language` are
+optional. Other optional keys, in canonical order, are `abandoned: true` and
+the three revision fields shown above. `language` is status outside every
+world revision and does not change lifecycle decisions. Explicit
+`abandoned: false`, derived state, criteria mirrors, source locators, unknown
+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.
+
+State is derived in order:
+
+1. `abandoned` when `abandoned: true`.
+2. `preparing` when `approvedRevision` differs from `idealRevision`.
+3. `implementing` when `implementationAcceptedRevision` differs from
+   `implementationRevision`.
+4. `deploying` when `deploymentAcceptedRevision` differs from
+   `deploymentRevision`.
+5. `completed` when all three revisions match.
+
+## Public Commands
+
+```sh
+silvermoon whats-next [idea]
+silvermoon create-idea [--language <tag>]
+silvermoon check [--remote | --commit <revision> | --staged | --worktree]
+```
+
+`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.
+
+## Validation Targets
+
+- `check` validates only the committed `HEAD` snapshot and reads primary
+  coordinates from that snapshot.
+- `check --worktree` validates the hypothetical commit formed from `HEAD`, the
+  index, unstaged changes, and nonignored untracked files.
+- `check --staged` validates the index snapshot.
+- `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.
+
+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.
+
+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.
+
+## Schemas
+
+- [Repository configuration](../schema/v1/config.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

@@ -0,0 +1,61 @@
+# Repository idea workflow
+
+This repository uses the local [Silvermoon skill](/skills/silvermoon/SKILL.md)
+and the fixed `.silvermoon/` metadata layout.
+
+## Authority
+
+The shared authority is `https://github.com/shazhou-ww/silvermoon.git` on
+`main`. Fetch and observe that primary before idea work. Feature branches are
+optional transport and are not protocol state.
+
+```sh
+silvermoon whats-next [idea] --json
+silvermoon create-idea --json
+silvermoon check
+silvermoon check --worktree
+silvermoon check --staged
+silvermoon check --commit HEAD
+silvermoon check --remote
+```
+
+Use the report's `observedPrimaryCommit` 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.
+
+## 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.
+
+The required idea-root `ledger.md` is the Agent continuation surface. After
+repository hygiene and lifecycle routing, combine the reported action, 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.
+
+Preserve unknown changes, concurrent history, and previous revision facts.
+Never force-push, reset, broadly clean, or automatically delete feature
+branches.
+
+## Repository Checks
+
+- Run `pnpm test` for the fast unit-and-contract developer suite.
+- Run `pnpm test:integration` for real filesystem and Git behavior, and
+  `pnpm test:e2e` for the installed package.
+- Run `pnpm check` after CLI, schema, repository model, release, or skill
+  changes; it remains the complete release-grade validation entrypoint.
+- Run `pnpm check:skills` after skill changes.
+- Validate package contents, installed-package smoke behavior, Markdown links,
+  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.

package/package.json

@@ -1,65 +1,69 @@
-{
-  "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"
-  }
-}
+{
+  "name": "silvermoon",
+  "version": "0.0.3",
+  "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",
+    "bin",
+    "docs",
+    "skills/silvermoon",
+    "src",
+    "README.md",
+    "README.zh-CN.md",
+    "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:quick": "node --check bin/silvermoon.js && npm test",
+    "check:skills": "node scripts/sync-skills.mjs --check && npx skills add . --list",
+    "lint:markdown": "markdownlint-cli2",
+    "pack:check": "node scripts/check-pack.js",
+    "prepare:npm-release": "node scripts/prepare-npm-release.mjs",
+    "sync:skills": "node scripts/sync-skills.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",
+    "markdownlint-cli2": "^0.23.3",
+    "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

@@ -1,24 +1,27 @@
-{
-  "$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"
-    }
-  }
-}
+{
+  "$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"
+    },
+    "preferredLanguage": {
+      "$ref": "definitions.schema.json#/$defs/languageTag"
+    }
+  }
+}