diff --git a/docs/plans/implementation.md b/docs/plans/implementation.md index 634f7cb..8d9a7c8 100644 --- a/docs/plans/implementation.md +++ b/docs/plans/implementation.md @@ -2,7 +2,8 @@ status: open last_updated: 2026-11-06 (created at the start of implementation; wave 1 decomposed and its gate passed the same day; wave 2 - decomposed immediately after) + decomposed immediately after; wave 3 decomposed 2026-11-07 after + the wave-2 gate) --- # alkgen: Implementation plan @@ -86,7 +87,7 @@ Dependency logic in one line: core foundations (consumer-shaped proofs |---|---|---|---| | [1](#wave-1-the-core) | The core: manifest landing (dep pins, alktype removal, feature graph); the public error model; registry construction (strict mode, escaper policy, typed registration, helper seam); the render entry point (two sinks); engine fixture doubles | none | decomposed | | [2](#wave-2-consumer-shaped-proofs) | The generality proofs on shipped code: the full ssr-shaped (posture-B) fixture through the public API; the code-shaped (posture-A/C) fixture with ordering and determinism invariants; the conformance battery (strict-mode matrix, error surface, two-sink correctness, wasm, feature matrix) | wave 1 | decomposed | -| [3](#wave-3-validation--release) | Release readiness (README, CHANGELOG, rustdoc, dry-run, freeze inventory); the release gate; the publish | waves 1 + 2 | planned | +| [3](#wave-3-validation--release) | Release readiness (README, CHANGELOG, rustdoc, dry-run, freeze inventory); the release gate; the publish | waves 1 + 2 | decomposed | ## Wave 1: The core @@ -286,6 +287,44 @@ and never silently absorbs it (ADR-001's falsifiability discipline). Wave 3 decomposes after the wave-2 gate, absorbing whatever it corrects. +**Decomposition record** (2026-11-07, after the wave-2 gate closed +green with no booked findings; nothing above changes, except that +reminder (a) from the wave-1 gate, the freeze inventory's +`#[non_exhaustive]` decision, lands inside `w3-release-readiness` +as the plan already assigns it, and reminder (c) stays unassigned +because `bast-codegen` still gates nothing): wave 3 decomposes into +one readiness task, the gate, and the publish, in that order: the +gate is a pure review over the readiness artifacts and everything +before them, and the publish executes only over a green verdict +(the alkgit/alkssh pattern: never one task reviewing and publishing +itself). + +- `w3-release-readiness`: the README rewrite on the shipped engine + framing (the current README still carries the pre-plan codegen + framing and the alktype dependency as a status line, both stale); + CHANGELOG 0.1.0 (Keep a Changelog shape, the alkssh precedent); + public-API rustdoc warning-free with usage examples compile-checked + as doctests; the package dry-run with a `cargo package --list` + check (the current `exclude` list omits `docs/plans/` and + `tasks/`, which are working documents, not crate payload; the task + fixes the list rather than shipping them); the freeze inventory + for the gate, explicitly disposing of the carried `#[non_exhaustive]` + reminder. +- `review-wave-3`: the release gate, a pure review. Closes green + only when the crate is honestly shippable. +- `w3-publish`: the publish checklist over the green verdict: + manifest sanity, the full verification set (wasm build standing), + the dry-run re-checked at the publish commit, the crate-qualified + `alkgen-v0.1.0` tag (the family convention), `cargo publish`, and + the plan-closure records (the wave-3 row, the freeze inventory's + one-way surfaces) riding the publish commit. + +The chain is sequential by construction: each step consumes the +previous one's product. The publish credential posture follows the +alkssh sibling convention: if the credential were unavailable the +task stops and books it, never a silent skip; the credential is +present in this environment, so the publish can execute live. + ## Plan closure The plan closes at the publish of **`alkgen 0.1.0`**: the publish diff --git a/tasks/implementation/review-wave-3.md b/tasks/implementation/review-wave-3.md new file mode 100644 index 0000000..f050aab --- /dev/null +++ b/tasks/implementation/review-wave-3.md @@ -0,0 +1,55 @@ +--- +id: review-wave-3 +name: "Wave 3 gate: the release review" +status: pending +depends_on: [w3-release-readiness] +scope: narrow +risk: low +impact: phase +level: review +--- + +## Description + +The wave-3 gate: the release gate, a pure review over the readiness +task and everything before it (waves 1 and 2 plus their gates). It +closes green only when the crate is honestly shippable: the +published artifacts say what the code does, the package carries what +it should and nothing it should not, and the freeze inventory +records the one-way surfaces the publish creates. + +## Acceptance Criteria + +- [ ] README checked against the shipped code line by line: every + claim matches the actual surface; no stale framing, no + overclaim (the engine-owned-set absence stated plainly) +- [ ] CHANGELOG checked against the actual 0.1.0 surface +- [ ] rustdoc + doctests verified: `cargo doc --no-deps` + warning-free, examples compile-checked and consistent with the + README +- [ ] package posture verified: `cargo package --list` against the + package policy (no SDD/plans/research/tasks payload; the + architecture docs present), dry-run clean +- [ ] freeze inventory reviewed: every listed surface is real (each + one traceable to code or a pinned test), the + `#[non_exhaustive]` decision reviewed against ADR-001/008 and + the wave-1 interpretation record, the evolution policy written +- [ ] conventions audit re-run (no unwrap/expect/panics in non-test + src, no unsafe, no async, no filesystem, no em dashes in prose + surfaces) +- [ ] full verification set re-run clean on the final readiness + tree +- [ ] gate verdict recorded in Notes: publish unblocked, or blockers + listed + +## References + +- docs/plans/implementation.md (wave 3, the release-gate bullet) +- docs/architecture/ (the whole index; the gate reads the release + artifacts against the recorded decisions) +- tasks/implementation/w3-release-readiness.md +- tasks/implementation/review-wave-2.md (the gate this follows) + +## Notes + +Filled by the review agent. diff --git a/tasks/implementation/w3-publish.md b/tasks/implementation/w3-publish.md new file mode 100644 index 0000000..57a849e --- /dev/null +++ b/tasks/implementation/w3-publish.md @@ -0,0 +1,69 @@ +--- +id: w3-publish +name: "Wave 3: the publish of alkgen 0.1.0" +status: pending +depends_on: [review-wave-3] +scope: narrow +risk: medium +impact: project +level: implementation +--- + +## Description + +The publish, which is the plan's closing act (`docs/plans/ +implementation.md` §Plan closure): executes only over the green +`review-wave-3` verdict (the gate stays a pure review; the publish +is its own task). The checklist: + +- **Manifest sanity**: version 0.1.0 (verify, no bump), the + `rust-version`/edition posture, license files present, the dep + pins as ADR-002 records them (handlebars 6.4 on default features + off the crate's `default = []`), the feature graph (`bast-codegen` + declared, gating nothing), the fixed `exclude` list. +- **The full verification set** at the publish commit: `cargo test`, + `cargo test --all-features`, clippy × 2 (`--all-targets -D + warnings`), `cargo fmt --check`, `cargo doc --no-deps`, the wasm + release build (standing), `taskgraph validate`, plus the ADR-002 + tree inspection (no `dir_source`, no `script_helper`). +- **The dry-run**: `cargo publish --dry-run --allow-dirty` clean at + the publish commit, the package file list spot-checked once more. +- **The tag**: the crate-qualified `alkgen-v0.1.0` on the publish + commit (the family convention: a bare `v0.1.0` would be ambiguous + across the family). +- **The publish**: `cargo publish`; the published version verified + resolvable on crates.io afterward. **If the publish credential is + unavailable, the task stops and books it, never silently + skipping**; everything before the credential step still lands (tag + + records). +- **The plan's closure recorded** in + `docs/plans/implementation.md`: the wave-3 row, the status flip to + `closed` at the publish, and the closure note (the freeze + inventory's surfaces are one-way from the publish: the public API + shape, the strict-mode and determinism postures, the error model's + evolution policy, the handlebars pin's behavior). + +## Acceptance Criteria + +- [ ] Manifest sanity verified and recorded +- [ ] The full verification set green at the publish commit +- [ ] The dry-run clean at the publish commit, file list checked +- [ ] The `alkgen-v0.1.0` tag on the publish commit +- [ ] `cargo publish` executed; the published 0.1.0 verified on + crates.io (or the credential absence booked, never a silent + skip) +- [ ] The plan's closure recorded (wave-3 row, status `closed`, the + freeze surfaces noted one-way) + +## References + +- docs/plans/implementation.md (§Wave 3 the publish bullet, + §Plan closure, §Scope authority: v0.1.0 publishes the crate) +- tasks/implementation/review-wave-3.md (the verdict this executes + over) +- /workspace/@alkdev/alkssh tasks/implementation/w5-publish.md + (the sibling publish shape this mirrors) + +## Notes + +Filled by the implementation agent. diff --git a/tasks/implementation/w3-release-readiness.md b/tasks/implementation/w3-release-readiness.md new file mode 100644 index 0000000..aa8afc6 --- /dev/null +++ b/tasks/implementation/w3-release-readiness.md @@ -0,0 +1,95 @@ +--- +id: w3-release-readiness +name: "Wave 3: release readiness (README, CHANGELOG, rustdoc, package posture, freeze inventory)" +status: pending +depends_on: [] +scope: moderate +risk: low +impact: phase +level: implementation +--- + +## Description + +Everything v0.1.0 needs to be publish-honest except the publish +itself. The crate's code surface is frozen (waves 1 and 2 landed it +and the reviews passed clean); this task is the surface a reader, +a downloader, and the gate meet. + +- **README rewrite** (the plan's wave-3 bullet; the current README + still carries the pre-plan framing: the codegen-engine status line + and the alktype dependency reference, both stale since the + consumer steer and `w1-manifest`): the engine framing (ADR-001: + handlebars templates over serde-serializable contexts, strict, + deterministic, synchronous, wasm-clean, library-only ADR-010), the + one-registry-per-set surface (`TemplateSet`, `EscapePolicy`, + `Error`) with usage examples (kept honest with the crate docs: + compile-checked doctests in `src/lib.rs`), the integration-pattern + section (emit.md: posture-B usage for alkforge's SSR, the + documented posture-A build-script pattern per ADR-010, the + posture-C note), and the consumer-owned-template-set statement + (ADR-008: v0.1.0 ships no engine-owned sets; the ssr-html target + is proven in-crate by fixtures, `targets.md`). +- **CHANGELOG 0.1.0**: Keep a Changelog shape (the alkssh + precedent), listing the shipped public surface and postures. +- **Public-API rustdoc warning-free**: `cargo doc --no-deps` clean, + with the usage examples compile-checked as doctests so the README + and the crate docs say the same thing. +- **The package posture**: `cargo publish --dry-run --allow-dirty` + plus a `cargo package --list` check; the `exclude` list verified + against what actually ships (SDD process docs, research, plans, + and tasks are working documents, not crate payload: the current + list omits `docs/plans/` and `tasks/`; the task fixes the list). + The architecture docs ship (the alkssh precedent: they are the + crate's design record, not scratch work). +- **The freeze inventory for the gate** (the plan's wave-3 bullet; + carries wave-1 gate reminder (a)): the public API shape + (`TemplateSet`, `EscapePolicy`, `Error`), the strict-mode and + determinism postures, the error enum's evolution policy, the + handlebars 6.4 pin's behavior; the `#[non_exhaustive]` question + decided explicitly with written rationale, landing as the decision + itself in `src/error.rs` if the decision is to adopt it. + +No new engine surface; a freeze decision that touches `src/` lands +in this task and is re-verified by the full set. + +## Acceptance Criteria + +- [ ] README rewritten on the shipped framing (no stale codegen + status, no alktype dependency reference); the integration + postures (A documented build-script pattern, B for alkforge, + C note) present per the plan +- [ ] CHANGELOG 0.1.0 in place, Keep a Changelog shape +- [ ] `cargo doc --no-deps` warning-free; usage examples + compile-checked as doctests (`cargo test` runs them) +- [ ] `exclude` list fixed (`docs/plans/`, `tasks/` added); + `cargo package --list` checked against the package policy and + recorded +- [ ] `cargo publish --dry-run --allow-dirty` clean +- [ ] the freeze inventory recorded for the gate, with the + `#[non_exhaustive]` posture decided explicitly (the decision + landed in `src/error.rs` if adopted) and the evolution policy + written down +- [ ] full verification set green: `cargo test`, + `cargo test --all-features`, `cargo clippy --all-targets -- -D + warnings`, `cargo fmt --check`, `cargo doc --no-deps`, + `cargo build --target wasm32-unknown-unknown --release`, + `taskgraph validate` + +## References + +- docs/plans/implementation.md (wave 3, the release-readiness bullet) +- docs/architecture/core.md, emit.md (the postures the README + documents), targets.md (the activation queue the README reports) +- docs/architecture/decisions/001-one-core-template-set-targets.md +- docs/architecture/decisions/003-core-posture-sync-wasm-deterministic.md +- docs/architecture/decisions/008-template-set-ownership.md +- docs/architecture/decisions/010-library-only-no-cli.md +- tasks/implementation/review-wave-1.md (reminder (a): the freeze + inventory decides `#[non_exhaustive]`) +- /workspace/@alkdev/alkssh README.md + CHANGELOG.md (the sibling + release-artifact shape this mirrors) + +## Notes + +Filled by the implementation agent.