Generated Reference Signposts (Cycle 0027)

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ## Unreleased
 
+- OSS Release Scaffolding (0026-oss-release-scaffolding)
 - Configurable Workspace Paths (0025-configurable-workspace-paths)
 - Method Consistency Fixes (0022-method-consistency-fixes)
 - Drift Near-Miss Hints (0023-drift-near-miss-hints)

docs/BEARING.md

@@ -14,9 +14,9 @@ Current priority: pull TBD to continue the system's maturity.
 
 ## What just shipped?
 
+- `0026-oss-release-scaffolding`: OSS Release Scaffolding
 - `0025-configurable-workspace-paths`: Configurable Workspace Paths
 - `0024-async-exec-refactor`: Async Exec Refactor
-- `0023-drift-near-miss-hints`: Drift Near-Miss Hints
 
 ## What feels wrong?
 

docs/CLI.md

@@ -1,6 +1,6 @@
 ---
 title: "CLI Reference"
-generated_from_commit: "c877c709503f635519d00f99311805a094591534"
+generated_from_commit: "fe47f5bb944a4035cfd2c0692e438a2174206103"
 ---
 
 # CLI Reference
@@ -13,125 +13,39 @@ operations. Run `method help` for a quick summary or
 
 ### `method init [path]`
 
-Scaffold a METHOD workspace in the given directory. Creates all
-backlog lanes, design/retro directories, legends, graveyard, release
-surfaces, and placeholder docs (process.md, release.md, CHANGELOG.md).
-
-If a `.method.json` file exists at the target path with a `paths`
-section, the scaffolding uses those custom paths instead of the
-defaults.
-
-```bash
-method init                 # scaffold in current directory
-method init ~/projects/foo  # scaffold in a specific directory
-```
+Scaffold a METHOD workspace in the given directory.
 
 ### `method inbox <idea> [--legend CODE] [--title TITLE]`
 
-Capture a raw idea into the inbox. The idea text becomes the file
-body. An optional legend code prefixes the filename. An optional title
-overrides the heading (and slug) derived from the idea text.
-
-```bash
-method inbox "Support GitLab sync"
-method inbox "Extract hardcoded strings" --legend PROCESS
-method inbox "Braille rendering" --legend VIZ --title "Braille Renderer"
-```
+Capture a raw idea in docs/method/backlog/inbox/.
 
 ### `method pull <item>`
 
-Promote a backlog item into the next numbered design cycle. The
-backlog file is removed and a design doc is created under
-`docs/design/<cycle>/`. Matches by filename, stem, or
-case-insensitive stem.
-
-```bash
-method pull PROCESS_drift-near-miss-hints
-method pull drift-near-miss-hints
-```
+Promote a backlog item into the next numbered design cycle.
 
 ### `method close [cycle] [--drift-check yes|no] [--outcome hill-met|partial|not-met]`
 
-Close an active cycle. Generates a retro doc and a verification
-witness (test output + drift results). If `--drift-check` is omitted,
-the CLI prompts interactively.
+Close an active cycle into docs/method/retro/.
 
-The cycle argument is optional when exactly one cycle is active. It
-matches by full name, slug, or suffix.
+### `method status`
 
-```bash
-method close --drift-check yes --outcome hill-met
-method close 0025-configurable-workspace-paths --drift-check yes --outcome partial
-```
+Show backlog lanes, active cycles, and legend health.
 
 ### `method drift [cycle]`
 
-Check active cycle playback questions against test descriptions in
-`tests/`. Uses exact normalized matching. When a question has no exact
-match but a test description is close (Jaccard token similarity
->= 0.7), a near-miss hint is shown.
-
-- Exit 0: no drift found.
-- Exit 2: drift found.
-
-```bash
-method drift
-method drift 0025-configurable-workspace-paths
-```
-
-### `method status`
-
-Show backlog lanes, active cycles, and legend health. This is the
-"what is going on?" query.
-
-```bash
-method status
-```
+Check active cycle playback questions against test descriptions in tests/.
+First cut scans tests/**/*.test.* and tests/**/*.spec.* only.
 
 ### `method mcp`
 
-Start a Model Context Protocol server on stdio. The server exposes
-all METHOD operations as tools. See `docs/MCP.md` for the tool
-reference.
-
-```bash
-method mcp
-```
-
-### `method sync github [--push] [--pull]`
-
-Synchronize backlog items with GitHub Issues. Requires `github_token`
-and `github_repo` in `.method.json` or environment variables.
-
-- `--push` (default): Create or update GitHub issues from local
-  backlog files.
-- `--pull`: Update local files with remote labels, comments, and
-  status. Moves closed issues to the graveyard.
-- Both flags: push first, then pull.
-
-```bash
-method sync github              # push only (default)
-method sync github --push --pull # both directions
-method sync github --pull        # pull only
-```
-
-### `method sync ship`
-
-Perform the Ship Sync maneuver after merging a cycle to `main`.
-Updates `CHANGELOG.md` with newly shipped cycles and refreshes
-`docs/BEARING.md` with current direction and recent ships.
-
-```bash
-method sync ship
-```
-
-## Configuration
+Start an MCP (Model Context Protocol) server on stdio.
 
-The CLI reads `.method.json` from the workspace root for:
+### `method sync github|ship [options]`
 
-- `paths` — custom directory layout (see `ARCHITECTURE.md`)
-- `github_token` / `github_repo` — GitHub adapter credentials
-- Environment overrides: `GITHUB_TOKEN`, `GITHUB_REPO`
+GitHub Options:
+  --push                      Update GitHub issues with local changes (default).
+  --pull                      Update local backlog with GitHub changes (labels, comments, status).
+Perform Ship Sync or synchronize the backlog with GitHub Issues.
 
 ## Exit Codes
 

docs/MCP.md

@@ -1,6 +1,6 @@
 ---
 title: "MCP Reference"
-generated_from_commit: "c877c709503f635519d00f99311805a094591534"
+generated_from_commit: "fe47f5bb944a4035cfd2c0692e438a2174206103"
 ---
 
 # MCP Reference
@@ -9,130 +9,71 @@ METHOD exposes its workspace operations through a Model Context
 Protocol (MCP) server. Start it with `method mcp` — it communicates
 over stdio using JSON-RPC.
 
-## Connection
-
-```bash
-method mcp
-```
-
-The server speaks MCP protocol version `2024-11-05`. Configure it in
-your MCP client (e.g., `.mcp.json` for Claude Code):
-
-```json
-{
-  "mcpServers": {
-    "method": {
-      "command": "node",
-      "args": ["dist/cli.js", "mcp"]
-    }
-  }
-}
-```
-
 ## Workspace Parameter
 
 Every tool requires a `workspace` parameter: the absolute path to the
 METHOD workspace root directory. This makes the server
 workspace-agnostic — a single instance can serve multiple projects.
 
-```json
-{ "workspace": "/Users/you/git/your-project" }
-```
-
 ## Tools
 
 ### `method_status`
 
-Get the current workspace status as structured JSON.
-
-**Parameters:** `workspace` (required)
-
-**Returns:** JSON with `root`, `backlog` (items per lane),
-`activeCycles`, and `legendHealth`.
+Get the current status of the METHOD workspace (backlog lanes, active cycles, legend health)
 
 ### `method_inbox`
 
-Capture a new raw idea into the inbox.
+Capture a new raw idea into the inbox
 
 **Parameters:**
-- `workspace` (required) — workspace root path
-- `idea` (required) — the idea text (becomes file body)
-- `legend` (optional) — legend code to prefix the filename
-- `title` (optional) — override heading and slug
 
-**Returns:** relative path to the created file.
+- `idea` (required) `string`
+- `legend` (optional) `string`
+- `title` (optional) `string`
 
 ### `method_pull`
 
-Promote a backlog item into the next numbered cycle.
+Promote a backlog item into the next numbered cycle
 
 **Parameters:**
-- `workspace` (required) — workspace root path
-- `item` (required) — backlog item name (filename, stem, or
-  case-insensitive match)
 
-**Returns:** cycle name and design doc path.
+- `item` (required) `string`
 
 ### `method_drift`
 
-Check active cycle playback questions against test descriptions.
+Check active cycle playback questions against tests
 
 **Parameters:**
-- `workspace` (required) — workspace root path
-- `cycle` (optional) — specific cycle name
 
-**Returns:** drift report text. `isError: true` if drift is found.
+- `cycle` (optional) `string`
 
 ### `method_close`
 
-Close an active cycle into a retro with witness capture.
+Close an active cycle into a retro
 
 **Parameters:**
-- `workspace` (required) — workspace root path
-- `driftCheck` (required) — boolean, must be true
-- `outcome` (required) — `"hill-met"`, `"partial"`, or `"not-met"`
-- `cycle` (optional) — specific cycle name
 
-**Returns:** cycle name and retro doc path.
+- `cycle` (optional) `string`
+- `driftCheck` (required) `boolean`
+- `outcome` (required) `string` (hill-met, partial, not-met)
 
 ### `method_sync_ship`
 
-Perform the Ship Sync maneuver (update CHANGELOG.md and BEARING.md).
-
-**Parameters:** `workspace` (required)
-
-**Returns:** list of updated files and newly shipped cycles.
+Perform the Ship Sync maneuver (update CHANGELOG.md and BEARING.md)
 
 ### `method_sync_github`
 
-Synchronize backlog with GitHub Issues. Requires `github_token` and
-`github_repo` in `.method.json`.
+Synchronize backlog with GitHub Issues
 
 **Parameters:**
-- `workspace` (required) — workspace root path
-- `push` (optional) — update remote from local (default: true)
-- `pull` (optional) — update local from remote
 
-**Returns:** per-item sync results.
+- `push` (optional) `boolean` — Update GitHub issues with local changes (default: true)
+- `pull` (optional) `boolean` — Update local backlog with GitHub changes
 
 ### `method_capture_witness`
 
-Capture a verification witness for a cycle (test output + drift
-results).
+Automate terminal evidence capture for a cycle
 
 **Parameters:**
-- `workspace` (required) — workspace root path
-- `cycle` (optional) — specific cycle name
-
-**Returns:** path to the generated witness file.
-
-## Error Handling
-
-All tools return `isError: true` with a text message on failure.
-Common errors:
 
-- `workspace is required` — missing workspace parameter
-- `not a METHOD workspace` — path doesn't contain METHOD structure
-- `No active cycles found` — no open design docs without retros
-- `Cannot close a cycle without completing the drift check` —
-  `driftCheck` must be true
+- `cycle` (optional) `string`

docs/design/0027-generated-reference-signposts/generated-reference-signposts.md

@@ -0,0 +1,54 @@
+---
+title: "Generated Reference Signposts"
+legend: PROCESS
+---
+
+# Generated Reference Signposts
+
+Source: dogfood discovery — CLI.md and MCP.md are hand-authored
+copies of data that already exists in code.
+Legend: PROCESS
+
+## Sponsors
+
+- Human: Process Steward
+- Agent: Signpost Generator
+
+## Hill
+
+Generate `docs/CLI.md` and `docs/MCP.md` from source code so they
+never drift from the implementation.
+
+## Playback Questions
+
+### Human
+
+- [ ] `method sync ship` regenerates CLI.md and MCP.md alongside
+  BEARING and CHANGELOG.
+- [ ] The generated docs match the actual CLI usage and MCP tool schemas.
+
+### Agent
+
+- [ ] A `generateCliReference` function produces CLI.md from the
+  usage() output in cli-args.ts.
+- [ ] A `generateMcpReference` function produces MCP.md from the tool
+  schemas in mcp.ts.
+- [ ] Both carry `generated_from_commit` in frontmatter.
+- [ ] Tests prove the generated content names every command and tool.
+
+## Accessibility and Assistive Reading
+
+Not in scope.
+
+## Localization and Directionality
+
+Not in scope.
+
+## Agent Inspectability and Explainability
+
+Generated docs carry commit SHA provenance.
+
+## Non-goals
+
+- [ ] Generating ARCHITECTURE.md (prose, not mechanical).
+- [ ] Generating README.md (doctrine, not reference).