diff --git a/CHANGELOG.md b/CHANGELOG.md index d78020dd..6572f6cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -45,6 +45,18 @@ changed-schemas`, runs schema-scoped matrix jobs, and keeps per-schema report METHOD, CONTRIBUTING, and docs topic routing so the current docs point at the domain-free GraphQL-to-IR platform and the topic map rather than stale backlog or retired command surfaces. +- **Launch signpost honesty**: Refreshed the pre-tag launch wording across + README, GUIDE, ENTRYPOINTS, docs site, BEARING, TECHNICAL_TEARDOWN, release + topics, and docs-maintenance topics so `v0.2.0` install commands are present + without claiming publication before the signed tag workflow completes. + +### Fixed + +- **Docs CLI checker determinism**: The docs command checker now reads the + native command list from the Rust CLI source help text instead of invoking + `cargo run`, so Node-only repository hygiene does not depend on Cargo + registry/network state or cascade help-load failures into false doc command + errors. ### Removed diff --git a/README.md b/README.md index de3f33dd..fa5b2b2f 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ as release-scoped until the project declares a stable `1.0` surface. ## Quick Start -Install the published native CLI: +After the signed `v0.2.0` tag publishes, install the native CLI: ```bash cargo install wesley-cli --version 0.2.0 diff --git a/docs/BEARING.md b/docs/BEARING.md index 4a86b7ae..b005328e 100644 --- a/docs/BEARING.md +++ b/docs/BEARING.md @@ -107,8 +107,13 @@ and evidence, not by absorbing sibling runtime semantics. ### 7. Release Discipline -`v0.1.0` established the Rust-native release floor and the shared LE binary codec -plan. Future releases must be cut from signed tags on synced `main`; do not merge +`v0.1.0` established the Rust-native release floor and shared LE binary codec +plan. `v0.1.1` purged old host, website, playground, backlog, and release +governance residue. `v0.2.0` is the project-manifest platform launch: schema +sets, config commands, HOLMES schema selection, descriptor-only extension +fixtures, and comprehensive `docs/topics/` routing. + +Future releases must be cut from signed tags on synced `main`; do not merge post-release evidence backfills to `main` after a release boundary. Versioned release work is tracked by `Release: ...` milestones and release-gate @@ -152,8 +157,11 @@ Historical closeouts remain useful evidence, but they are not active work queues Use the [Wesley Roadmap Project](https://github.com/users/flyingrobots/projects/18) and GitHub milestones for exact ordering. Product gravity remains: -1. keep the post-`v0.1.0` Rust-native release floor boring and reproducible, -2. harden evidence truth around Holmes and `weslaw`, -3. preserve the domain-empty module boundary while external targets consume +1. tag and publish `v0.2.0` from synced `main` with repo-resident release truth + already in place, +2. keep the Rust-native compiler and project-manifest platform boring and + reproducible, +3. harden evidence truth around Holmes and `weslaw`, +4. preserve the domain-empty module boundary while external targets consume Wesley artifacts, and -4. cut only from tagged `main` once release-gate issues are satisfied. +5. cut only from tagged `main` once release-gate issues are satisfied. diff --git a/docs/ENTRYPOINTS.md b/docs/ENTRYPOINTS.md index 6a993952..39360dda 100644 --- a/docs/ENTRYPOINTS.md +++ b/docs/ENTRYPOINTS.md @@ -9,7 +9,7 @@ cargo run --bin wesley -- --help ``` For published alpha builds, the crates.io package is `wesley-cli` and the -installed command is `wesley`. The current published alpha is `0.2.0`: +installed command is `wesley`. The `v0.2.0` release installs as: ```bash cargo install wesley-cli --version 0.2.0 diff --git a/docs/GUIDE.md b/docs/GUIDE.md index 6c4f6482..dbe97660 100644 --- a/docs/GUIDE.md +++ b/docs/GUIDE.md @@ -20,7 +20,7 @@ artifacts. - **Inspect native CLI**: `cargo run --bin wesley -- --help` - **Read native CLI reference**: [docs/reference/cli.md](./reference/cli.md) - **Doctor native CLI**: `cargo run --bin wesley -- doctor` -- **Install published alpha**: `cargo install wesley-cli --version 0.2.0` +- **Install release alpha after publication**: `cargo install wesley-cli --version 0.2.0` - **Install locally**: `cargo install --locked --path crates/wesley-cli` - **Strict preflight**: `cargo xtask preflight` - **Explicit alias**: `cargo xtask strict-preflight` @@ -40,9 +40,9 @@ Use `wesley doctor` when you need a narrow Rust-native health check for the native CLI, Rust lowerer, normalized SDL hashing, and Rust emitter crates. It does not inspect legacy Node config, plugins, or package state. -Use `cargo install wesley-cli --version 0.2.0` when you want the latest -published alpha `wesley` binary on your PATH. Use -`cargo run --bin wesley -- ...` when working directly from this checkout, or +Use `cargo install wesley-cli --version 0.2.0` for the release alpha once the +signed tag has published to crates.io. Use `cargo run --bin wesley -- ...` when +working directly from this checkout before publication, or `cargo install --locked --path crates/wesley-cli` when you need a local installed binary. Use `cargo xtask preflight` before opening a PR. This is the strict quality gate: it runs `cargo fmt --check`, diff --git a/docs/README.md b/docs/README.md index d1a31969..df888f20 100644 --- a/docs/README.md +++ b/docs/README.md @@ -54,6 +54,13 @@ The completed Rust-native release floor is: - [Rust IR Parity Sentinel](./design/0013-rust-ir-parity-sentinel/rust-ir-parity-sentinel.md) - [Rust Native Front Door And Node Retirement](./design/0017-rust-native-front-door-and-node-retirement/rust-native-front-door-and-node-retirement.md) +The `v0.2.0` launch surface is now: + +- [Wesley v0.2.0 release notes](./releases/v0.2.0.md) +- [Project Manifest](./reference/project-manifest.md) +- [Topics](./topics/README.md) +- [Releases topic](./topics/releases.md) + The old Continuum-heavy `v0.1.0/` lane has been retired to [graveyard/v0.1.0](./method/graveyard/v0.1.0/README.md). Treat those notes as historical extraction context, not as active Wesley release commitments. @@ -67,6 +74,8 @@ The repo already has the important generic building blocks around that direction: - Rust-native schema lowering, hashing, operation catalogs, and selection facts +- JSON/YAML project manifests for schema sets, rebuild selection, bundles, + comment mode, dashboards, and generic target metadata - deterministic Rust and TypeScript projection surfaces - generic operation artifacts whose meaning is assigned by downstream owners - HOLMES assurance foundations over explicit evidence bundles diff --git a/docs/TECHNICAL_TEARDOWN.md b/docs/TECHNICAL_TEARDOWN.md index ae10c7d2..3a94b8c1 100644 --- a/docs/TECHNICAL_TEARDOWN.md +++ b/docs/TECHNICAL_TEARDOWN.md @@ -68,12 +68,13 @@ expansion, release documentation gate, and removal of the old Holmes capability alias. This is a pre-1.0 minor release over the published `v0.1.1` residue-purge baseline. -As of this teardown refresh, the release branch is prepared to run +As of this teardown refresh, release preparation has landed on synced `main`. +The remaining pre-tag sequence must rerun `cargo xtask release-prep-guard --version 0.2.0`, `cargo xtask preflight`, -`cargo xtask release-check`, and `cargo xtask package-crates --version 0.2.0`. -The `v0.2.0` release gate is the only issue scheduled in the `Release: v0.2.0` -milestone, and it remains open until the release commit lands on synced `main` -and the signed tag is cut. +`cargo xtask release-check`, and `cargo xtask package-crates --version 0.2.0` +on the final synced `main` commit before the signed tag is cut. The `v0.2.0` +release gate is the only issue scheduled in the `Release: v0.2.0` milestone, +and it remains open until the signed tag publishes and publication checks pass. The active project direction is to finish the Rust-native compiler spine, preserve the domain-empty boundary, and grow Holmes law-assurance ingestion @@ -297,8 +298,9 @@ intentionally not yet exposed as a public Holmes CLI from Rust. The README now describes `v0.2.0`, aligned with the `Cargo.toml` crate version declared across the workspace. The changelog's dated `0.2.0` section carries the post-`0.1.1` project-manifest, HOLMES schema-selection, and documentation -coverage work. Release preparation is blocked only on the normal release branch, -validation, merge-to-main, signed tag, and publish sequence. +coverage work. Release preparation has landed on synced `main`; the remaining +release gate is the final pre-tag validation, signed tag, publish, and +post-publish verification sequence. ## Package(s) Overview diff --git a/docs/method/releases/v0.2.0/verification.md b/docs/method/releases/v0.2.0/verification.md index 4ece5d24..60c250cb 100644 --- a/docs/method/releases/v0.2.0/verification.md +++ b/docs/method/releases/v0.2.0/verification.md @@ -17,6 +17,8 @@ registry checks; release truth must not depend on a post-publish backfill merge. - Previous release tag: `v0.1.1`. - Release gate: GitHub issue #625, milestone `Release: v0.2.0`. - Release boundary: signed tag from synced `main` only. +- Release-prep merge: PR #655 merged to `main` at + `8bc51a7b86d927ceaefec3630421699d68878242`. ## Discovery @@ -29,16 +31,17 @@ registry checks; release truth must not depend on a post-publish backfill merge. | Node requirement | `>=22.12.0` from root `package.json`. | | Latest prior semver tag | `v0.1.1`. | | Main sync state before release branch | Local `main` matched `origin/main` at merge commit `03d527855e740c456f5f71f9c763ab071a5ddd1b`. | +| Release-prep merge state | PR #655 landed the release-prep commit and docs CLI review fix on synced `main` at `8bc51a7b`. | | Open `v0.2.0` issue lane | Only release gate #625 remained open during prep discovery. | ## Docs Topics Audit -| Item | Result | -| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| Scope | Every tracked file under `docs/topics/`. | -| Accuracy score | 100% for release-relevant topic claims audited during prep. | -| Coverage score | 100% for release-relevant contributor/operator workflows changed by this release. | -| Corrections made | No `docs/topics/` page required content correction after audit. Related stale signposts and command-checker behavior were corrected outside `docs/topics/`: docs site install/quick-start claims, technical teardown command/version claims, release indexes, legacy backlog signpost examples, and `scripts/check-doc-cli-commands.mjs` command-family detection. | +| Item | Result | +| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Scope | Every tracked file under `docs/topics/`. | +| Accuracy score | 100% for release-relevant topic claims audited during prep and the final pre-tag launch pass. | +| Coverage score | 100% for release-relevant contributor/operator workflows changed by this release, including the explicit pre-tag signpost pass. | +| Corrections made | Added pre-tag launch-pass coverage to `docs/topics/releases.md` and `docs/topics/docs-maintenance.md`; added the route to `docs/topics/README.md`; corrected pre-publication install wording in README, GUIDE, ENTRYPOINTS, docs site, and TECHNICAL_TEARDOWN; refreshed BEARING and docs front-door signposts for the `v0.2.0` launch state. | ## Local Evidence @@ -59,12 +62,21 @@ registry checks; release truth must not depend on a post-publish backfill merge. | `pnpm exec prettier --check ...` on changed docs/scripts/metadata | Passed after formatting the new release packet files. | | `cargo run --bin wesley -- --version` | Passed, printing `0.2.0`. | | `cargo test --workspace -- --list` | Passed for discovery; current workspace lists 323 Rust tests. | +| `cargo xtask docs-check` after launch signpost refresh | Passed. | +| `node scripts/check-doc-cli-commands.mjs` after launch signpost refresh | Passed. | +| `cargo xtask release-prep-guard --version 0.2.0` after launch signpost refresh | Passed. | +| `BATS_LIB_PATH=test/vendor bats -t test/release-governance.bats test/docs-planning-boundary.bats` | Passed after launch signpost refresh. | +| `BATS_LIB_PATH=test/vendor bats -t test/technical-teardown.bats` | Passed after removing stale pre-merge release blocker wording. | +| `node --test scripts/check-doc-cli-commands.test.mjs` | Passed after removing Cargo/network dependency from docs CLI command discovery. | +| `node scripts/check-doc-cli-commands.mjs` | Passed after source-backed docs CLI command discovery fix. | +| `git diff --check` after launch signpost refresh | Passed. | +| `cargo xtask preflight` after launch signpost refresh | Passed. | ## Release-Prep Notes -- The release branch updates version-bearing manifests, README, CHANGELOG, - technical teardown, release packet docs, release notes, and stale signpost - commands before tagging. +- The release branch and follow-up launch signpost pass update version-bearing + manifests, README, CHANGELOG, docs topics, technical teardown, release packet + docs, release notes, and stale signpost commands before tagging. - The project-manifest surface stays domain-free: schema sets, rebuild globs, bundle locations, comment mode, dashboards, and generic target descriptors are structure and metadata only. diff --git a/docs/site/index.md b/docs/site/index.md index fbf34a59..cdc890bb 100644 --- a/docs/site/index.md +++ b/docs/site/index.md @@ -32,7 +32,8 @@ Transform → Plan → Rehearse → Ship fit together. ## Getting started quickly -Install the CLI and run the local Quick Start: +After the `v0.2.0` release publishes, install the CLI and run the local Quick +Start: ```bash cargo install wesley-cli --version 0.2.0 diff --git a/docs/topics/README.md b/docs/topics/README.md index 0405ec08..1f607434 100644 --- a/docs/topics/README.md +++ b/docs/topics/README.md @@ -34,13 +34,14 @@ short path to the authoritative surface. ### Assurance, CI, And Release -| Task | Start Here | Authority | -| ------------------------------------------- | --------------------------------------------- | ------------------------------------------------------------ | -| Choose local checks before a PR or release. | [Validation](./validation.md) | `cargo xtask preflight`, `docs/governance/RELEASE_POLICY.md` | -| Interpret GitHub Actions checks. | [CI Workflows](./ci-workflows.md) | `docs/ci.md`, `.github/workflows/` | -| Understand HOLMES CI and PR comments. | [HOLMES CI](./holmes-ci.md) | `.github/workflows/wesley-holmes.yml`, `docs/architecture/` | -| Work with assurance evidence and policies. | [Assurance Evidence](./assurance-evidence.md) | `docs/holmes-policy-spec.md` | -| Prepare or judge a release. | [Releases](./releases.md) | `docs/method/release-runbook.md`, `docs/governance/` | +| Task | Start Here | Authority | +| ------------------------------------------- | --------------------------------------------- | ---------------------------------------------------------------------------------- | +| Choose local checks before a PR or release. | [Validation](./validation.md) | `cargo xtask preflight`, `docs/governance/RELEASE_POLICY.md` | +| Interpret GitHub Actions checks. | [CI Workflows](./ci-workflows.md) | `docs/ci.md`, `.github/workflows/` | +| Understand HOLMES CI and PR comments. | [HOLMES CI](./holmes-ci.md) | `.github/workflows/wesley-holmes.yml`, `docs/architecture/` | +| Work with assurance evidence and policies. | [Assurance Evidence](./assurance-evidence.md) | `docs/holmes-policy-spec.md` | +| Prepare or judge a release. | [Releases](./releases.md) | `docs/method/release-runbook.md`, `docs/governance/` | +| Refresh docs before a release tag. | [Docs Maintenance](./docs-maintenance.md) | `docs/governance/RELEASE_POLICY.md#check-23-docstopics-accuracy-and-coverage-gate` | ### Contributor Process diff --git a/docs/topics/docs-maintenance.md b/docs/topics/docs-maintenance.md index 9e1505d1..beaca3f0 100644 --- a/docs/topics/docs-maintenance.md +++ b/docs/topics/docs-maintenance.md @@ -30,6 +30,25 @@ pnpm exec prettier --check For release prep, also audit `docs/topics/` for accuracy and coverage against the actual release diff. +## Pre-Tag Signpost Pass + +Before a signed release tag is created, audit the docs that most readers use to +decide what Wesley is and what is safe to run: + +- `README.md` +- `docs/README.md` +- `docs/GUIDE.md` +- `docs/ENTRYPOINTS.md` +- `docs/BEARING.md` +- `docs/TECHNICAL_TEARDOWN.md` +- the versioned release notes and verification packet +- every tracked page under `docs/topics/` + +The pass should distinguish release-target facts from publication facts. A +release-prep commit may contain the future install command, but it must not +claim crates.io or GitHub Release publication before the signed tag workflow +has completed. + ## Topic Coverage Standard Every public capability should have an obvious path to: diff --git a/docs/topics/releases.md b/docs/topics/releases.md index eae5ae55..8a954933 100644 --- a/docs/topics/releases.md +++ b/docs/topics/releases.md @@ -40,6 +40,31 @@ That includes: The `docs/topics/` gate means this directory must cover release-relevant contributor and operator workflows or link clearly to the current authority. +## Pre-Tag Launch Pass + +After the release-prep PR lands on `main` but before creating the signed tag, +run one last docs/signpost audit. The goal is not to create a progress tracker; +it is to make sure the tagged commit tells the truth without a post-release +backfill. + +Check these durable surfaces at minimum: + +- `README.md` +- `docs/README.md` +- `docs/GUIDE.md` +- `docs/ENTRYPOINTS.md` +- `docs/BEARING.md` +- `docs/TECHNICAL_TEARDOWN.md` +- `docs/releases/vX.Y.Z.md` +- `docs/method/releases/vX.Y.Z/release.md` +- `docs/method/releases/vX.Y.Z/verification.md` +- every tracked file under `docs/topics/` + +Pre-publication install wording must be honest. It may show the target +`cargo install wesley-cli --version X.Y.Z` command, but it must not claim the +version is already published until the signed tag workflow has actually +published it. + ## Command Sequence The exact abort-fast sequence lives in diff --git a/scripts/check-doc-cli-commands.mjs b/scripts/check-doc-cli-commands.mjs index ccb8d840..b203d558 100644 --- a/scripts/check-doc-cli-commands.mjs +++ b/scripts/check-doc-cli-commands.mjs @@ -1,11 +1,11 @@ #!/usr/bin/env node import { readFileSync } from 'node:fs'; -import { spawnSync } from 'node:child_process'; import { resolve } from 'node:path'; import { fileURLToPath } from 'node:url'; const root = resolve('.'); const docs = ['README.md', 'docs/GUIDE.md', 'docs/ENTRYPOINTS.md', 'docs/END_TO_END.md']; +const cliSourcePath = 'crates/wesley-cli/src/main.rs'; function fail(message) { console.error(`docs-cli: ${message}`); @@ -20,20 +20,10 @@ function normalizeCommandToken(token) { .trim(); } -function loadWesleyCommands() { - const result = spawnSync('cargo', ['run', '--bin', 'wesley', '--', '--help'], { - cwd: root, - encoding: 'utf8', - env: process.env - }); - if (result.status !== 0) { - fail(`failed to read native Wesley CLI help: ${result.stderr || result.stdout}`); - return new Set(); - } - +function parseCommandsFromHelpText(helpText) { const commands = new Set(); let inCommands = false; - for (const line of result.stdout.split(/\r?\n/)) { + for (const line of helpText.split(/\r?\n/)) { if (line.trim() === 'Commands:') { inCommands = true; continue; @@ -47,6 +37,27 @@ function loadWesleyCommands() { return commands; } +export function loadWesleyCommandsFromSource(source) { + const start = source.indexOf('fn print_help()'); + if (start === -1) { + throw new Error(`${cliSourcePath} is missing fn print_help()`); + } + + const nextFunction = source.indexOf('\nfn print_', start + 'fn print_help()'.length); + const helpSource = source.slice(start, nextFunction === -1 ? undefined : nextFunction); + const commands = parseCommandsFromHelpText(helpSource); + if (commands.size === 0) { + throw new Error(`${cliSourcePath} print_help() did not expose any command rows`); + } + + return commands; +} + +function loadWesleyCommands() { + const source = readFileSync(resolve(root, cliSourcePath), 'utf8'); + return loadWesleyCommandsFromSource(source); +} + export function documentedCommandFromParts(parts, commands) { if (parts.length > 1 && !parts[1].startsWith('-')) { const nested = `${parts[0]} ${parts[1]}`; @@ -118,7 +129,14 @@ export function extractCommandSnippets(content) { } function main() { - const commands = loadWesleyCommands(); + let commands; + try { + commands = loadWesleyCommands(); + } catch (error) { + fail(error?.message || error); + process.exit(process.exitCode); + } + for (const doc of docs) { const content = readFileSync(resolve(root, doc), 'utf8'); for (const command of extractDocumentedCommands(content, commands)) { diff --git a/scripts/check-doc-cli-commands.test.mjs b/scripts/check-doc-cli-commands.test.mjs index 097607bc..5e470794 100644 --- a/scripts/check-doc-cli-commands.test.mjs +++ b/scripts/check-doc-cli-commands.test.mjs @@ -1,7 +1,11 @@ import test from 'node:test'; import assert from 'node:assert/strict'; -import { commandOrFamilyExists, documentedCommandFromParts } from './check-doc-cli-commands.mjs'; +import { + commandOrFamilyExists, + documentedCommandFromParts, + loadWesleyCommandsFromSource +} from './check-doc-cli-commands.mjs'; test('documented command parsing preserves unknown nested subcommands for family validation', () => { const commands = new Set(['config validate', 'config inspect', 'schema lower']); @@ -20,3 +24,29 @@ test('documented command parsing still accepts command-family headings', () => { assert.equal(documented, 'config'); assert.equal(commandOrFamilyExists(documented, commands), true); }); + +test('documented command checker loads command names from Rust help source', () => { + const source = String.raw` +fn print_help() { + println!( + "\ +Wesley native CLI + +Usage: + wesley [options] + +Commands: + config validate Validate a Wesley project manifest + schema lower Lower GraphQL SDL to Wesley L1 IR JSON + operation directive-args Extract operation directive arguments as JSON + +Options: + -h, --help Show help" + ); +} +`; + + const commands = loadWesleyCommandsFromSource(source); + + assert.deepEqual([...commands], ['config validate', 'schema lower', 'operation directive-args']); +}); diff --git a/test/technical-teardown.bats b/test/technical-teardown.bats index 178094a4..3ac2d674 100644 --- a/test/technical-teardown.bats +++ b/test/technical-teardown.bats @@ -24,3 +24,11 @@ load 'bats-plugins/bats-assert/load' run grep -F "[BEARING.md](./BEARING.md)" docs/TECHNICAL_TEARDOWN.md assert_success } + +@test "technical teardown does not carry stale pre-merge release blockers" { + run grep -F "Release preparation is blocked only on the normal release branch" docs/TECHNICAL_TEARDOWN.md + assert_failure + + run grep -F "release preparation has landed on synced \`main\`" docs/TECHNICAL_TEARDOWN.md + assert_success +}