docs(voyage): CLAUDE.md + README + CHANGELOG + annotation-quickstart + late doc-consistency pins — v4.2 Step 13
This commit is contained in:
parent
6d57314937
commit
de160d7da1
6 changed files with 296 additions and 9 deletions
|
|
@ -4,6 +4,122 @@ All notable changes to this project will be documented in this file.
|
|||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
|
||||
|
||||
## v4.2.0 — 2026-05-09 — Annotation pipeline + first voyage playground
|
||||
|
||||
**Additive. No breaking changes. Forward-compat with every brief / plan / review written before v4.2.**
|
||||
|
||||
Voyage's first interactive playground. The `/trekrevise` command and the
|
||||
annotation pipeline (Handover 8) close the operator-feedback loop: render an
|
||||
artifact in the browser, anchor comments at block boundaries, export a batch,
|
||||
paste back as `/trekrevise --apply` for in-place revision with audit trail.
|
||||
|
||||
### Added
|
||||
|
||||
- **`/trekrevise` command** (`commands/trekrevise.md`) — seventh pipeline
|
||||
command. Phase 1 parse/validate, Phase 2 read source + rollback hygiene,
|
||||
Phase 3 parse anchors + validate placement, Phase 4 compute revision
|
||||
diff + digest, Phase 5 atomic apply, Phase 6 post-write integrity check,
|
||||
Phase 7 optional review-gate, Phase 8 stats + report. Accepts
|
||||
`--profile`, `--gates`, `--reason`, `--from-file`, `--target`.
|
||||
- **Handover 8 (annotation → revision)** documented in
|
||||
`docs/HANDOVER-CONTRACTS.md` (~100 lines). Producer/consumer contract,
|
||||
schema for the four additive frontmatter fields (`revision`,
|
||||
`source_annotations`, `annotation_digest`, `revision_reason`), block-level
|
||||
anchor format, lifecycle, single-iteration MVP rationale.
|
||||
- **`playground/voyage-playground.html`** — single self-contained HTML file
|
||||
with vendored `markdown-it` v14.1+ + `highlight.js` (no `marked` per Issue
|
||||
#3515). Three annotation creation gestures (drag-select, hover-anchor,
|
||||
click-anchor), modal form with intent taxonomy (change/add/remove/
|
||||
clarify/risk), sidebar with critique-card-list, export flow with
|
||||
one-click clipboard copy, A11Y baseline (keyboard nav, ARIA roles,
|
||||
focus traps).
|
||||
- **`playground/lib/`** vendored markdown-it + highlight.js + front-matter
|
||||
plugin, with `VENDOR-MANIFEST.json` recording version + license + sha.
|
||||
Locked at minimum versions per research-03.
|
||||
- **`scripts/render-artifact.mjs`** server-side render CLI — emits the same
|
||||
HTML the playground produces. Used by the SC11 pipeline-self-eat gate
|
||||
(rendering `.claude/projects/*/brief.md` + `plan.md` exits 0 with
|
||||
non-empty output).
|
||||
- **`scripts/vendor-playground-libs.mjs`** vendor-refresh helper — fetches
|
||||
pinned versions and updates the manifest.
|
||||
- **`lib/parsers/anchor-parser.mjs`** — pure-function anchor parser:
|
||||
`parseAnchors`, `addAnchors`, `stripAnchors`, `validateAnchorPlacement`.
|
||||
Block-boundary discipline (no in-list, no mid-paragraph, no line-start
|
||||
collisions). Round-trip tested with byte-identical fixture
|
||||
(`tests/fixtures/annotation/annotation-example.md`).
|
||||
- **`lib/parsers/annotation-digest.mjs`** — pure-function deterministic
|
||||
SHA-256 over canonical-sorted `source_annotations`. First 16 hex chars.
|
||||
Idempotent: same batch → same digest.
|
||||
- **`lib/util/markdown-write.mjs`** — `serializeFrontmatter` +
|
||||
`atomicWriteMarkdown` (tmp-file + rename, same crash-safety as
|
||||
`atomic-write.mjs`).
|
||||
- **`lib/util/revision-guard.mjs`** — atomic-write rollback guard for
|
||||
`/trekrevise` Phase 6 round-trip integrity check (plan-critic M4).
|
||||
Restores byte-identical pre-write file from `*.local.bak` on failure.
|
||||
- **`docs/annotation-quickstart.md`** — operator-facing 7-step
|
||||
walkthrough, references `tests/fixtures/annotation/annotation-example.md`
|
||||
for hands-on verification.
|
||||
- **`tests/fixtures/annotation/`** — 5 fixtures covering `brief`, `plan`,
|
||||
`plan-large`, `review`, and the canonical `annotation-example.md`.
|
||||
- **9 new test files** + extension to `tests/lib/doc-consistency.test.mjs`:
|
||||
- `tests/lib/markdown-write.test.mjs` (round-trip)
|
||||
- `tests/parsers/anchor-parser.test.mjs` (parse/add/strip/validate)
|
||||
- `tests/parsers/annotation-digest.test.mjs` (determinism)
|
||||
- `tests/validators/{brief,plan,review}-validator-annotation-fields.test.mjs`
|
||||
(forward-compat: validators tolerate the four optional fields)
|
||||
- `tests/integration/annotation-roundtrip.test.mjs` (SC2/SC3/SC7
|
||||
byte-identical + scale)
|
||||
- `tests/integration/schema-rollback.test.mjs` (SC5b validator-FAIL
|
||||
rollback)
|
||||
- `tests/integration/source-annotations.test.mjs` (frontmatter
|
||||
audit trail)
|
||||
|
||||
### Changed
|
||||
|
||||
- **Forward-compat policy** documented in `lib/validators/{brief,plan,
|
||||
review}-validator.mjs` headers — validators silently accept the four
|
||||
optional annotation fields without bumping `*_version`.
|
||||
- **`tests/lib/doc-consistency.test.mjs`** extended with ~16 new pins:
|
||||
Handover 8 section, templates' annotation-field comment blocks,
|
||||
`playground/` directory, `marked`-ban, `scripts/render-artifact.mjs`,
|
||||
`lib/util/revision-guard.mjs`, `parseAnchors` round-trip on the example
|
||||
fixture, `/trekrevise` in CLAUDE.md / plugin README / marketplace root
|
||||
README, `## v4.2.0` in CHANGELOG, `docs/annotation-quickstart.md`
|
||||
existence + ≤7 numbered steps + `annotation-example.md` literal
|
||||
reference.
|
||||
- **`PIPELINE_COMMANDS` constant** in doc-consistency tests — was 6
|
||||
(brief/research/plan/execute/review/continue), now 7 (+ revise). Pin
|
||||
test renamed from "all six pipeline commands" to "all seven pipeline
|
||||
commands".
|
||||
- **`settings.json` known-scopes allowlist** — `'trekrevise'` added to
|
||||
the recognized top-level scope list (was added in Wave 2 Step 6 to
|
||||
keep tests green pre-Step 12).
|
||||
- **Templates** (`templates/{plan,trekbrief,trekreview}-template.md`)
|
||||
prefixed with comment-only documentation block of the four optional
|
||||
annotation fields. No `*_version` change; existing templates still
|
||||
parse and validate identically.
|
||||
|
||||
### Notes
|
||||
|
||||
- **`marked` is banned** from `playground/*` (risk-assessor H1 +
|
||||
doc-consistency pin). Issue #3515 corrupts content silently after
|
||||
HTML comments in lists — voyage anchors after step-list would be
|
||||
invisible. `markdown-it` v14.1+ is the locked renderer.
|
||||
- **Single-iteration MVP** per research-05. Each operator batch produces
|
||||
one `revision:` increment. Multi-iteration loops (revise → re-review
|
||||
→ revise again) are deferred indefinitely; the brief's SC4 wording is
|
||||
single-revision.
|
||||
- **No `*_version` bump** for v4.2 — the four new fields are additive.
|
||||
Brief/plan/review artifacts written before v4.2 validate as
|
||||
`revision: 0` without migration.
|
||||
- **Atomic-write contract** for `/trekrevise` — single
|
||||
`writeFileSync`+`renameSync` (research-05 Option B). Option C
|
||||
(`atomicWriteJson + Edit-tool` split-write) was inadmissible per
|
||||
risk-assessor C2: no crash-safe window between frontmatter patch and
|
||||
body Edit.
|
||||
- **608 tests pass** (606 → 0 fail → 2 skipped Docker) — baseline
|
||||
before v4.2 was 490; this release adds ~118 tests.
|
||||
|
||||
## v4.1.0 — 2026-05-09
|
||||
|
||||
**Additive. No breaking changes. Forward-compat with all v4.0.0 plans.**
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue