jg-plans 0.1.2 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.2.0 — document observations and tooling
+
+- Add pure edit preparation, expected-hash guards, explicit body/core-metadata and milestone-source writes, opt-in UUID assignment, and guarded milestone removal. Return digests and assigned IDs through the library and CLI.
+- Coordinate every filesystem mutation through shared canonical local document locks; preserve explicit crash recovery and truthful uncertain outcomes after failed release.
+
+- Add complete UTF-16 source ranges for unfenced level-two sections, document preambles, milestone headings, and recognized Overview tables without dropping shared or trailing requirements.
+- Share optional frontmatter parsing between plans and milestones; expose exact milestone body and raw extension metadata without requiring plan metadata fields.
+- Return exact-byte SHA-256 values for readable documents. Add pure `fingerprintPlan` and optional inspection/CLI structural fingerprints using explicit caller-selected metadata exclusions and strict deterministic JSON.
+- Use `jg-crypto` and `jg-utilities` as direct runtime dependencies. Protocol 0.1 remains provisional; fingerprints and observations grant no execution authority.
+
 ## 0.1.2 — documentation and examples
 
 - Complete the canonical documentation and consumer integration recipes alongside the visual example explorer, original-source downloads, and verified package availability presentation.

package/README.md

@@ -29,7 +29,7 @@ Protocol 0.1 is provisional. The [website](https://jg-plans.jesusgraterol.dev) p
 
 Users own their documents and can edit or delete them. No history store, metadata field, CLI, or website is required to read Markdown. Optional conformance checks do not authorize execution or become a prerequisite to inspection.
 
-The protocol stays separate from application schemas, approvals, resource allocations, locking and reconciliation. Future jg-skills and HQ adoption are independent integrations.
+The protocol stays separate from application schemas, approvals, resource allocations, coordination journals and reconciliation. Future jg-skills and HQ adoption are independent integrations.
 
 ## Development
 
@@ -44,7 +44,7 @@ pnpm check
 
 The [development guide](https://github.com/jesusgraterol/jg-plans/blob/main/docs/development.md) owns checks and package/site boundaries. Root tests build first, exercise public compiled exports, and install the actual tarball in an isolated consumer. Website tests verify production output in both themes and narrow layouts.
 
-The [runnable library example](examples/library.mjs) creates, inspects, updates, and checks documents in an owned temporary directory. Mutations preserve unrelated bytes and require callers to serialize edits to each document; unsupported edits fail without rewriting it. The [API](api/README.md) describes the exact preservation and concurrency limits.
+The [runnable library example](examples/library.mjs) creates, inspects, updates, and checks documents in an owned temporary directory. Guarded mutations and pure preparation preserve unaffected bytes and share local document locks; unsupported edits fail without rewriting it. The [API](api/README.md) describes the exact preservation and concurrency limits.
 
 ## License
 

package/api/README.md

@@ -7,7 +7,7 @@ The ESM root exports compiled JavaScript and TypeScript declarations. Node.js 24
 ```ts
 import { PROTOCOL_VERSION, parsePlan, parseMilestones, checkPlan, inspectPlan } from 'jg-plans';
 
-const plan = parsePlan('# Useful legacy Markdown');
+const plan = parsePlan('# Useful Markdown');
 const milestones = parseMilestones('## Milestone 1: Work\n**Status:** pending');
 const check = checkPlan({ plan: plan.source, milestones: milestones.source });
 const observation = await inspectPlan('./jg-plans/example', { maxBytes: 1_048_576 });
@@ -17,27 +17,55 @@ const observation = await inspectPlan('./jg-plans/example', { maxBytes: 1_048_57
 
 `parsePlan(source)` retains the exact source and body. Its `metadata` contains independently validated core fields. `rawMetadata` retains the expanded YAML value, including unknown fields and invalid known values. Missing metadata, malformed YAML, unsupported expansion, and incompatible values receive structured diagnostics; they do not discard the body or authorize work.
 
-YAML uses maxAliasCount: 100 for expansion protection. Recursive aliases, unsafe integer expansions, and values JSON cannot represent receive a `YAML_VALUE_UNAVAILABLE` warning; rawMetadata is unavailable (`null`) and the original YAML remains in source. Raw observations use YAML's JavaScript conversion; source remains authoritative for original numeric spelling and presentation. Independently readable core fields are still observed. An unterminated frontmatter block retains the complete source as body because its boundary is unknown.
+YAML uses maxAliasCount: 100 for expansion protection. Recursive aliases, unsafe integer expansions, non-string or ambiguous YAML mapping keys, and values JSON cannot represent receive a `YAML_VALUE_UNAVAILABLE` warning; rawMetadata is unavailable (`null`) and the original YAML remains in source. Raw observations use YAML's JavaScript conversion; source remains authoritative for original numeric spelling and presentation. Independently readable core fields are still observed. An unterminated frontmatter block retains the complete source as body because its boundary is unknown.
 
 `parseMilestones(source)` returns source, recognizable milestones, optional overview rows, overviewPresent, and diagnostics. overviewPresent distinguishes an absent table from an explicitly empty derived table; an existing table that omits observed milestones receives discrepancies. Each entry contains ordinal, title, observed status/ID or null, location, end offset, body, and all recognized status/ID markers. Duplicate markers remain visible and are diagnosed; the first observed marker supplies the convenience status/ID value. Consumers must consider ambiguity diagnostics before acting on it. Fenced examples are ignored. Missing IDs and overview tables are allowed. Gaps are observations, with no reconstructed entries or inferred completion.
 
 `checkPlan({ plan?, milestones? })` checks explicitly supplied strings against preferred writer conformance. Omit absent or deleted documents. It returns `{ conforms, diagnostics }`; error diagnostics make conforms false. It never writes, restores data, or runs as a prerequisite to another operation.
 
+## Source ranges and milestone metadata
+
+Both parsers return a `preamble` span and ordered `sections` for every unfenced level-two heading. Each section has its observed title, a `heading` span including its line ending, and a `body` span extending to the next level-two heading or EOF. `ISourceSpan` has zero-based UTF-16 `start` and exclusive `end`; slice the returned original source with those offsets.
+
+The preamble starts at zero and includes everything before the first observed section, including any BOM, frontmatter, title, and introductory prose. Concatenating the preamble and every heading/body span reproduces the complete original source. Sections keep shared, intervening, and trailing requirements visible even when they are not milestone entries. A milestone's `headingEnd` is the first offset after its heading line; its existing `end` and `body` still stop at the next level-two heading.
+
+Milestones may begin with an optional frontmatter mapping. `frontmatter`, `rawMetadata`, and exact `body` are observed through the same YAML reader as plans, without requiring the five plan fields. Frontmatter is excluded from heading and marker scanning; Markdown-looking YAML never becomes work. Unterminated frontmatter remains ambiguous and retains the whole source as body. `overviewTables` contains only recognized table spans, from header through separator and consecutive rows; adjacent prose and fenced examples are excluded.
+
+## Structural fingerprints
+
+```ts
+import { fingerprintPlan, inspectPlan } from 'jg-plans';
+
+const exclusions = ['created_at', 'updated_at', 'revision', 'status'];
+const fingerprint = fingerprintPlan('# Work', { excludeMetadataKeys: exclusions });
+const inspection = await inspectPlan('./jg-plans/example', {
+  fingerprint: { excludeMetadataKeys: exclusions },
+});
+```
+
+`fingerprintPlan(source, options?)` returns `{ sha256, excludeMetadataKeys, diagnostics }`. It hashes strict deterministic JSON of `{ body, metadata }`, where body is exact parsed body text and metadata is raw top-level metadata after removing only explicitly named keys. The default exclusion list is empty; duplicate requested keys are reported once, in first-occurrence order. There are no implicit administrative exclusions. Unknown metadata, plan identity, nested values, and key/value distinctions remain covered. Nested fields with an excluded key name remain covered.
+
+Metadata key order, YAML quoting, and YAML comments alone do not change this structural digest. Exact body text, including its whitespace and line endings, does. Metadata-free source uses an empty mapping and remains fingerprintable without preferred-field conformance. Unterminated or ambiguous framing, invalid YAML, nonmapping frontmatter, unresolved YAML warnings, or unavailable/non-JSON-safe values return `sha256: null` with safe diagnostics while ordinary inspection remains useful. The implementation uses `jg-utilities` strict deterministic serialization and `jg-crypto` SHA-256.
+
+A structural fingerprint is distinct from an exact file hash and from an application's approval digest. Consumers choose exclusion policy and decide freshness, authorization, and scope coverage. It never grants approval or completion.
+
 ## Selected-directory inspection
 
-`inspectPlan(directory, { maxBytes? }?)` reads only plan.md and milestones.md from that exact directory, concurrently and with a default 1 MiB limit per file. Explicit custom paths and coding-agent-planning/ work as supplied; there is no repository/root/history discovery.
+`inspectPlan(directory, { maxBytes?, fingerprint? }?)` reads only plan.md and milestones.md from that exact directory, concurrently and with a default 1 MiB limit per file. Explicit custom paths and coding-agent-planning/ work as supplied; there is no repository/root/history discovery.
+
+The result includes the resolved directory, each document's path and readable/missing/unreadable state, useful parsed data for readable files, and aggregated diagnostics. Every readable document also has lowercase `sha256` computed from the exact original bytes, including BOM and line endings. A readable empty file differs from a missing file. Orphan milestones remain observable when the plan has been deleted. No predecessor is required or restored.
 
-The result includes the resolved directory, each document's path and readable/missing/unreadable state, useful parsed data for readable files, and aggregated diagnostics. A readable empty file differs from a missing file. Orphan milestones remain observable when the plan has been deleted. No predecessor is required or restored.
+Supplying `fingerprint: { excludeMetadataKeys? }` adds a top-level `fingerprint` result, reusing the already-read and parsed plan. Missing/unreadable plans return an unavailable requested fingerprint rather than fabricated content. Omitting the option omits that result.
 
 Bytes must decode strictly as UTF-8. An existing BOM is retained in source. Invalid bytes receive INVALID_ENCODING, and another readable document still contributes observations. File-size failures and nonregular/unreadable targets receive operational diagnostics. Final-component file symlinks are not followed; the selected directory's ancestors are caller-chosen. The library does not silently transcode content.
 
 ## Types and schemas
 
-Creation and update contracts are described below. A [runnable library example](../examples/library.mjs) exercises creation, sequential updates, inspection, and checking in an owned temporary directory.
+Creation, preparation, updates, guarded writes, removal, and locks are described below. A [runnable library example](../examples/library.mjs) exercises creation, sequential updates, inspection, and checking in an owned temporary directory.
 
-Named public types are IPlanMetadata, IDiagnostic, ISourceLocation, IReadOptions, IPlanDocuments, IParsedPlan, IFrontmatter, IMarker, IMilestone, IOverviewRow, IParsedMilestones, ICheckResult, IDocumentRead, IPlanInspection, ICreatePlanOptions, IPlanCreation, IPlanUpdate, and IPlanUpdateResult.
+Named public types are IPlanMetadata, IDiagnostic, ISourceLocation, ISourceSpan, IHeadingSection, IReadOptions, IPlanFingerprintOptions, IInspectPlanOptions, IPlanFingerprint, IPlanDocuments, IParsedPlan, IFrontmatter, IMarker, IMilestone, IOverviewRow, IParsedMilestones, ICheckResult, IDocumentRead, IPlanInspection, ICreatePlanOptions, IPlanCreation, IPlanUpdate, IPlanUpdateResult, IPlanDocumentWrite, IPlanDocumentWriteResult, IRemoveMilestones, IRemoveMilestonesResult, IPreparedPlanEdit, and IAssignedMilestoneId.
 
-PlanMetadataSchema defines preferred complete metadata and allows project extensions. DiagnosticSchema, SourceLocationSchema, ReadOptionsSchema, and PlanDocumentsSchema own the corresponding boundary contracts. Known fields are validated independently during tolerant reads. PROTOCOL_VERSION is `0.1`; it is independent of the npm package version.
+PlanMetadataSchema defines preferred complete metadata and allows project extensions. DiagnosticSchema, SourceLocationSchema, ReadOptionsSchema, PlanFingerprintOptionsSchema, PlanFingerprintSchema, InspectPlanOptionsSchema, and PlanDocumentsSchema own the corresponding boundary contracts. Fingerprint results and inspection/fingerprint options are closed schemas; only explicit supported keys are accepted. Known metadata fields are validated independently during tolerant reads. PROTOCOL_VERSION is `0.1`; it is independent of the npm package version.
 
 Source offsets count JavaScript UTF-16 code units. Lines and columns start at one. Marker value spans exclude surrounding whitespace and line endings. Entries and overview rows retain ordinalText; ordinal is null for nonpositive or unsafe integer text, avoiding rounded identities. These are observations, not general-purpose rewrite permission.
 
@@ -60,11 +88,11 @@ await updatePlan(created.directory, { document: 'plan', set: { revision: 2 } });
 
 The closed CreatePlanOptionsSchema accepts slug, optional root, body, optional JSON metadata, and optional milestones text. Missing core metadata defaults to the generated name as id, one captured ISO creation time for created_at and updated_at, revision 1, and pending status. Supplied values override defaults, including nonconforming known values; diagnostics describe them without refusing to preserve them. Unknown project metadata is retained. The supplied Markdown body and milestone bytes are preserved; creation emits new UTF-8 frontmatter with LF separators.
 
-The result contains directory, parsed plan, parsed milestones or null, and diagnostics. Existing destinations fail without overwriting. Failed creation attempts remove only recognized files created by that call and the empty owned plan directory. Intervening user content is preserved; incomplete cleanup is reported in error.data.cleanupFailedPaths. An empty selected storage root can remain after failure.
+The result contains directory, parsed plan with its exact-byte sha256, parsed milestones with sha256 or null, and diagnostics. Existing destinations fail without overwriting. Failed creation attempts remove only recognized files created by that call and the empty owned plan directory. Intervening user content is preserved; incomplete cleanup is reported in error.data.cleanupFailedPaths. An empty selected storage root can remain after failure.
 
 ## Targeted updates
 
-`updatePlan(directory, patch, { maxBytes? }?)` edits one existing document and returns `{ directory, document, changed, diagnostics }`. The closed PlanUpdateSchema accepts either:
+`updatePlan(directory, patch, { maxBytes? }?)` edits one existing document and returns `{ directory, document, changed, sha256, diagnostics, assignedMilestoneIds }`. The closed PlanUpdateSchema accepts either variant below, with optional expectedSha256 on either variant. Supply a freshly observed lowercase SHA-256 to reject stale or deleted sources before preparation:
 
 ```json
 { "document": "plan", "set": { "status": "in progress", "revision": 2 } }
@@ -83,12 +111,47 @@ The update reads only the selected document, bounded at 1 MiB by default. A malf
 
 Every byte outside the requested value spans or insertion points is preserved, including BOM, supplementary Unicode, unrelated nested metadata, comments, quotes, whitespace, line endings, and final-newline state. Equal values produce a no-op and skip replacement. Existing single quotes are retained when their style can represent the value; replacements otherwise use quoted YAML scalars.
 
-Unsupported edits fail without writing. These include malformed/unterminated frontmatter, a flow-style root mapping, complex/anchored/tagged root keys, merge keys, duplicate affected keys, and affected aliases, anchors, tags, block/multiline scalars, or implicit empty nulls. Duplicate/missing milestone selectors, repeated targets, duplicate affected markers, and overlapping spans also fail. Unrelated nonconforming fields are not a conformance gate. error.data.reason identifies the unsupported case, with field when relevant; it contains no source snippet. This is a conservative scalar/marker editor, with no general YAML or Markdown rewrite API.
+Unsupported edits fail without writing. These include malformed/unterminated frontmatter, a flow-style root mapping, complex/anchored/tagged root keys, merge keys, duplicate affected keys, and affected aliases, anchors, tags, block/multiline scalars, or implicit empty nulls. Duplicate/missing milestone selectors, repeated targets, duplicate affected markers, and overlapping spans also fail. Unrelated nonconforming fields are not a conformance gate. error.data.reason identifies the unsupported case, with field when relevant; it contains no source snippet. This narrow operation is a conservative scalar/marker editor; use explicit document writes below for body or milestone-source replacement.
 
-Bytes must be valid UTF-8, and replacement strings cannot contain unpaired UTF-16 surrogates. The caller-selected directory and its ancestors are trusted path choices; links below that root are rejected. Replacement preserves file permissions. **Serialize the entire read/edit/write operation for a document, including within one process.** The prior-content comparison detects observed intervening changes, but a comparison-to-rename race remains. No lock, queue, journal, snapshot service, or automatic retry is provided.
+Bytes must be valid UTF-8, and replacement strings cannot contain unpaired UTF-16 surrogates. The caller-selected directory and its ancestors are trusted path choices; links below that root are rejected. Replacement preserves file permissions. All filesystem mutations acquire the shared selected-document lock before reading or preparing. The prior-content comparison detects observed intervening changes, but nonparticipating editors retain a comparison-to-rename race. No journal, snapshot service, or automatic retry is provided.
 
 CreatePlanOptionsSchema and PlanUpdateSchema are public boundary schemas; PlanSetSchema, MilestoneSelectorSchema, and MilestoneSetSchema expose their constituent contracts. New metadata is JSON-compatible; original YAML source remains authoritative on reads.
 
+## Pure preparation and guarded document writes
+
+`preparePlanUpdate(source, patch)` applies the same narrow edit entirely in memory. `preparePlanDocumentWrite(source, input)` prepares the explicit replacement below. Both return `{ source, changed, sha256, diagnostics, assignedMilestoneIds }` (IPreparedPlanEdit). They perform no filesystem access, locks, timestamps, revision increments, or implicit ID assignment. Persist the exact prepared source once in a consumer journal; do not regenerate random IDs during replay. IAssignedMilestoneId contains ordinal and id.
+
+`writePlanDocument(directory, input, { maxBytes? }?)` reads only the selected document, validates its required expectedSha256 before preparation, and persists the prepared output under its shared lock. PlanDocumentWriteSchema is closed and discriminated by document:
+
+```ts
+import { inspectPlan, writePlanDocument } from 'jg-plans';
+const observed = await inspectPlan('./jg-plans/example');
+if (observed.plan.state === 'readable') {
+  await writePlanDocument(observed.directory, {
+    document: 'plan',
+    expectedSha256: observed.plan.sha256,
+    body: '# Revised intent\n',
+    set: { revision: 2 },
+  });
+}
+```
+
+The plan variant requires an existing digest, a replacement body, and optional core metadata set. Body and supplied metadata are changed together, preserving all unaffected frontmatter bytes. Closed malformed YAML permits body-only replacement; ambiguous/unterminated boundaries fail. A needed line separator is inserted after a closing delimiter at EOF. The existing BOM encoding marker is preserved; on metadata-free source, a leading BOM also present in the supplied body is treated as that same marker. A body-only operation cannot introduce frontmatter into metadata-free source. Replacement strings must encode strictly as UTF-8.
+
+The milestones variant accepts `{ document: 'milestones', expectedSha256: string | null, source: string, assignMissingIds?: boolean }`. Null requires an absent file and uses exclusive creation; a digest never recreates deleted files. Source is verbatim unless explicit assignMissingIds is true. That option preserves valid IDs and inserts random UUIDs immediately after unique canonical nonempty status lines. Duplicate/invalid identities, ordinals, or ambiguous insertion targets fail. It returns assigned ordinal/id pairs; without the option, missing IDs remain missing. No timestamps, completion, or approvals are inferred.
+
+Pure preparation accepts null original source only for explicit absent milestone creation. Existing-source expectations are checked against strict UTF-8 bytes. Filesystem guards compare the original bytes before decoding. Writes return `{ directory, document, changed, sha256, diagnostics, assignedMilestoneIds }`; a no-op still checks its expectation and skips replacement. Existing permissions are preserved. maxBytes bounds reads rather than the size of the prepared output.
+
+`removeMilestones(directory, { expectedSha256 }, { maxBytes? }?)` (RemoveMilestonesSchema) removes only an existing regular UTF-8 milestones.md matching that digest. Missing or changed targets fail SOURCE_CHANGED. The result is `{ directory, document: 'milestones', changed: true, sha256: null, diagnostics: [] }`. The plan, selected directory, coordination files, and history are untouched. Links, nonregular targets, unreadable/oversized source, and unsupported encoding fail. Nonparticipating editors retain a check-to-unlink race.
+
+## Shared document locks
+
+`withPlanDocumentLocks(directory, documents, operation)` accepts a nonempty unique selection of plan/milestones and calls operation with the canonical real directory. It acquires `.plan.md.jg-plans.lock` before `.milestones.md.jg-plans.lock` regardless of input order, then releases in reverse order. Every filesystem mutation, including initial creation, uses this namespace. Failed creation releases locks before owned empty-directory cleanup.
+
+Use pure preparation and consumer persistence inside a callback; nesting filesystem mutations reacquires the held lock and fails busy. Keep callbacks bounded to one operation, never across model/agent turns. Locks use jg-fs ownership checks, support local filesystems, and fail immediately for busy or dead owners. There is no TTL, polling, or automatic takeover. After a crash, inspect the owner and affected documents before explicit operator recovery through jg-fs; never remove an unfamiliar lock.
+
+LOCK_BUSY and acquisition LOCK_FAILED report phase/document/reason and mutationOutcome not-applied. Release LOCK_FAILED reports operationCompleted and mutationOutcome uncertain when the callback started, even if all writes landed; inspect/reconcile durable state before retrying. Callback and release failures are retained in its internal AggregateError cause. These locks coordinate participants, not every editor. They provide neither a cross-document transaction nor an HQ journal.
+
 ## Failures
 
 Invalid operation arguments throw JG_PLANS_INVALID_INPUT: Invalid jg-plans input. File absence, formatting defects, encoding failures, and read failures are returned as inspection diagnostics. Mutations throw operational errors for unsupported text/edits, existing destinations, detected source changes, and read/write failures. See the [error reference](../errors/README.md) for exact codes/messages and per-operation mapping. ERRORS exposes the stable operational codes.

package/cli/README.md

@@ -5,6 +5,7 @@ The executable is tested from the packed archive. Check the [website's availabil
 ```sh
 jg-plans inspect --directory ./jg-plans/example
 jg-plans inspect --directory ./custom-root/example --json
+jg-plans inspect --directory ./jg-plans/example --fingerprint-exclude '["created_at","updated_at","revision","status"]' --json
 jg-plans inspect --directory ./coding-agent-planning/example --include-body --json
 jg-plans check --directory ./jg-plans/example --json
 jg-plans --help
@@ -15,7 +16,9 @@ jg-plans --version
 
 Inspect reads only the selected plan.md and optional milestones.md. It reports readable, missing, or unreadable files, recognized metadata and progress, and useful partial observations. Unknown metadata and custom status strings remain visible. It does not read history, discover other plans, restore deleted files, or infer permission or completion from absence.
 
-Bodies and complete document sources are excluded by default. `--include-body` explicitly includes them for inspect. Metadata, titles, markers, and locations remain part of ordinary observations.
+Bodies and complete document sources are excluded by default. `--include-body` explicitly includes them for inspect, including the whole milestone document body. Raw metadata for both documents, titles, markers, locations, source ranges, and exact-byte SHA-256 values for readable files remain part of ordinary observations.
+
+`--fingerprint-exclude <JSON-array>` requests a structural plan fingerprint and supplies its explicit top-level metadata exclusions. Pass `[]` to cover every key. The array must contain strings; duplicate keys are applied once. This flag is accepted only by inspect. The result includes `data.fingerprint` with sha256, the unique applied keys, and diagnostics. Invalid framing/YAML or unavailable structure yields a null fingerprint without hiding useful observations. It is an observation, never permission or a conformance gate. See [structural fingerprints](../api/README.md#structural-fingerprints).
 
 ## Check
 
@@ -39,9 +42,9 @@ Create input is a closed JSON object with body, optional metadata, and optional
 }
 ```
 
-Slug and root are command flags, not JSON fields. Creation uses ./jg-plans relative to the working directory by default, without root discovery or migration. It creates an exclusive timestamp_slug directory, defaults missing metadata, preserves supplied body/milestones, and never overwrites. Slugs use lowercase ASCII kebab case; the generated component must fit 64 characters. Returned create data contains directory, plan metadata/rawMetadata, and milestone summaries or null. No body is emitted.
+Slug and root are command flags, not JSON fields. Creation uses ./jg-plans relative to the working directory by default, without root discovery or migration. It creates an exclusive timestamp_slug directory, defaults missing metadata, preserves supplied body/milestones, and never overwrites. Slugs use lowercase ASCII kebab case; the generated component must fit 64 characters. Returned create data contains directory, plan metadata/rawMetadata/sha256, and milestones as { sha256, milestones: summaries } or null. No body is emitted.
 
-Update input selects one document. For a plan, use `{ "document": "plan", "set": { "status": "done", "revision": 2 } }`. The only allowed fields are id, created_at, updated_at, revision, and status. For milestones:
+Update input selects one document and optionally expectedSha256 from a fresh inspection; a stale or deleted guarded target fails before preparation. For a plan, use `{ "document": "plan", "set": { "status": "done", "revision": 2 } }`. The only allowed fields are id, created_at, updated_at, revision, and status. For milestones:
 
 ```json
 {
@@ -50,11 +53,26 @@ Update input selects one document. For a plan, use `{ "document": "plan", "set":
 }
 ```
 
-Select by ordinal or UUID id, with one change per target. Set status and/or UUID id. The result contains directory, document, and changed. Equal values skip the write. Revision/timestamps never advance implicitly. Overview rows, prose, and extension metadata remain byte-identical. Missing selected files are not recreated. Existing misplaced markers remain in place with diagnostics; new markers require canonical insertion points.
+Select by ordinal or UUID id, with one change per target. Set status and/or UUID id. The result contains directory, document, changed, sha256, and assignedMilestoneIds (empty for narrow updates). Equal values skip the write. Revision/timestamps never advance implicitly. Overview rows, prose, and extension metadata remain byte-identical. Missing selected files are not recreated. Existing misplaced markers remain in place with diagnostics; new markers require canonical insertion points.
 
 Input comes from a file or `-` for stdin and must be valid UTF-8 JSON, at most 1 MiB by default. `--max-bytes` overrides both mutation-input and selected-document limits. Unknown JSON fields, nonconforming requested core values, invalid encoding, unsupported YAML, ambiguous edits, destination collisions, detected source changes, and I/O failures exit 2. Unsupported edits explain the case in error.data.reason; cleanup failures report owned paths. See [the API](../api/README.md) for precise preservation and unsupported-edit limits.
 
-Serialize commands that edit the same document, including the whole read/edit/write operation. A prior-content check detects observed intervening changes, but the comparison-to-rename race remains. The CLI supplies no lock, queue, retry, or history service.
+All mutations share local document locks with library/HQ consumers. Busy and dead owners fail immediately; recovery requires explicit operator inspection. A prior-content check detects observed intervening changes, but nonparticipating writers retain a comparison-to-rename race. Release failures report uncertain mutation outcomes even when bytes were written. There is no cross-document transaction, automatic retry, or history service.
+
+## Write and remove milestones
+
+```sh
+jg-plans write --directory ./jg-plans/example --input write.json --json
+jg-plans remove-milestones --directory ./jg-plans/example --input remove.json --json
+```
+
+Write accepts PlanDocumentWriteSchema. For plan bodies, use `{ "document": "plan", "expectedSha256": "<observed 64-character lowercase hash>", "body": "# Revised intent\n", "set": { "revision": 2 } }`. Set is optional and changes only core metadata. Body-only writes can preserve closed malformed YAML; unterminated framing fails. Unaffected frontmatter, BOM, and permissions are retained.
+
+For complete milestone replacement use `{ "document": "milestones", "expectedSha256": "<observed hash>", "source": "## Milestone 1: Work\n**Status:** pending\n", "assignMissingIds": true }`. Null expectedSha256 explicitly creates an absent milestone file exclusively. Existing expectations never recreate deleted targets. UUID assignment is opt-in, preserves valid IDs, and rejects ambiguous identities/insertion points. Write output includes directory, document, changed, sha256, and assignedMilestoneIds, never full source.
+
+Remove input is `{ "expectedSha256": "<observed milestone hash>" }`. Only matching regular UTF-8 milestones.md is removed; absent/stale targets fail SOURCE_CHANGED. Successful data contains directory, document milestones, changed true, and sha256 null. No plan, directory, or coordination file is removed.
+
+The placeholders above must be replaced with actual hashes returned by inspect/create or a preceding mutation. Every command uses the same input limits, safe errors, envelope, and exits. See [the API](../api/README.md#pure-preparation-and-guarded-document-writes) for source preservation and [shared document locks](../api/README.md#shared-document-locks).
 
 ## Limits and output
 

package/dist/cli/arguments.js

@@ -1,6 +1,6 @@
 import { parseStrictArgs } from 'jg-process';
 import { planErrors } from "../errors/index.js";
-import { ReadOptionsSchema } from "../protocol/index.js";
+import { PlanFingerprintOptionsSchema, ReadOptionsSchema, } from "../protocol/index.js";
 /**
  * Validate a single CLI request before reading documents.
  * @throws
@@ -18,6 +18,7 @@ export const parseArguments = (args) => {
             root: { type: 'string' },
             'max-bytes': { type: 'string' },
             'include-body': { type: 'boolean' },
+            'fingerprint-exclude': { type: 'string' },
             json: { type: 'boolean' },
             help: { type: 'boolean', short: 'h' },
             version: { type: 'boolean', short: 'v' },
@@ -33,8 +34,21 @@ export const parseArguments = (args) => {
         return { command: 'help', json: flags.json, includeBody: false };
     if (flags.version)
         return { command: 'version', json: flags.json, includeBody: false };
-    if (first !== 'inspect' && first !== 'check' && first !== 'create' && first !== 'update')
+    if (!['inspect', 'check', 'create', 'update', 'write', 'remove-milestones'].includes(first))
         throw planErrors.create('invalidInput');
+    let fingerprint;
+    if (flags['fingerprint-exclude'] !== undefined) {
+        if (first !== 'inspect')
+            throw planErrors.create('invalidInput');
+        try {
+            fingerprint = PlanFingerprintOptionsSchema.parse({
+                excludeMetadataKeys: JSON.parse(flags['fingerprint-exclude']),
+            });
+        }
+        catch {
+            throw planErrors.create('invalidInput');
+        }
+    }
     if (first === 'create') {
         if (!flags.slug || !flags.input || flags.directory || flags['include-body'])
             throw planErrors.create('invalidInput');
@@ -42,7 +56,7 @@ export const parseArguments = (args) => {
     else {
         if (!flags.directory || flags.root || flags.slug)
             throw planErrors.create('invalidInput');
-        if (first === 'update'
+        if (first === 'update' || first === 'write' || first === 'remove-milestones'
             ? !flags.input || flags['include-body']
             : Boolean(flags.input) || (first === 'check' && flags['include-body']))
             throw planErrors.create('invalidInput');
@@ -60,6 +74,7 @@ export const parseArguments = (args) => {
         ...(flags.slug ? { slug: flags.slug } : {}),
         ...(flags.root ? { root: flags.root } : {}),
         includeBody: flags['include-body'],
+        ...(fingerprint ? { fingerprint } : {}),
         json: flags.json,
         ...(maxBytes === undefined ? {} : { maxBytes }),
     };

package/dist/cli/commands.js

@@ -6,22 +6,24 @@ import { z } from 'zod';
 import { checkPlan } from "../documents/index.js";
 import { decodeSource } from "../edits/index.js";
 import { planErrors } from "../errors/index.js";
-import { createPlan, inspectPlan, updatePlan } from "../files/index.js";
-import { CreatePlanOptionsSchema, DEFAULT_MAX_BYTES, PlanUpdateSchema, } from "../protocol/index.js";
+import { createPlan, inspectPlan, updatePlan, writePlanDocument, removeMilestones, } from "../files/index.js";
+import { CreatePlanOptionsSchema, DEFAULT_MAX_BYTES, PlanUpdateSchema, PlanDocumentWriteSchema, RemoveMilestonesSchema, } from "../protocol/index.js";
 import { parseArguments } from "./arguments.js";
-const HELP = `jg-plans — inspect Markdown plans without enforcing a workflow
+const HELP = `jg-plans — read and edit Markdown plans without enforcing a workflow
 
 Commands:
-  inspect --directory <path> [--include-body] [--json] [--max-bytes <bytes>]
+  inspect --directory <path> [--fingerprint-exclude <JSON-array>] [--include-body] [--json] [--max-bytes <bytes>]
   check   --directory <path> [--json] [--max-bytes <bytes>]
   create  --slug <slug> --input <file-or-dash> [--root <path>] [--json] [--max-bytes <bytes>]
   update  --directory <path> --input <file-or-dash> [--json] [--max-bytes <bytes>]
+  write   --directory <path> --input <file-or-dash> [--json] [--max-bytes <bytes>]
+  remove-milestones --directory <path> --input <file-or-dash> [--json] [--max-bytes <bytes>]
   --help, -h
   --version, -v
 
 Only the selected plan.md and optional milestones.md are read.
 The default bound is 1048576 bytes per file. Checks are optional.
-Updates to the same document must run sequentially. No history is required.
+Mutations share local document locks. Busy owners require explicit recovery. No history is required.
 Exit 0: completed inspection, successful mutation, or conforming check; 1: conformance errors;
 2: invalid command or operational failure. Missing files do not imply completion.`;
 const projectInspection = (inspection, includeBody) => {
@@ -31,14 +33,18 @@ const projectInspection = (inspection, includeBody) => {
     const milestoneValue = milestones.state === 'readable' ? milestones.value : undefined;
     return {
         directory: inspection.directory,
+        ...(inspection.fingerprint ? { fingerprint: inspection.fingerprint } : {}),
         plan: {
             state: plan.state,
             path: plan.path,
             ...(planValue
                 ? {
                     metadata: planValue.metadata,
+                    sha256: plan.state === 'readable' ? plan.sha256 : undefined,
                     rawMetadata: planValue.rawMetadata,
                     frontmatter: planValue.frontmatter,
+                    preamble: planValue.preamble,
+                    sections: planValue.sections,
                     ...(includeBody ? { source: planValue.source, body: planValue.body } : {}),
                 }
                 : {}),
@@ -49,12 +55,18 @@ const projectInspection = (inspection, includeBody) => {
             ...(milestoneValue
                 ? {
                     overview: milestoneValue.overview,
+                    sha256: milestones.state === 'readable' ? milestones.sha256 : undefined,
+                    rawMetadata: milestoneValue.rawMetadata,
+                    frontmatter: milestoneValue.frontmatter,
+                    preamble: milestoneValue.preamble,
+                    sections: milestoneValue.sections,
+                    overviewTables: milestoneValue.overviewTables,
                     overviewPresent: milestoneValue.overviewPresent,
                     milestones: milestoneValue.milestones.map(({ body, ...entry }) => ({
                         ...entry,
                         ...(includeBody ? { body } : {}),
                     })),
-                    ...(includeBody ? { source: milestoneValue.source } : {}),
+                    ...(includeBody ? { source: milestoneValue.source, body: milestoneValue.body } : {}),
                 }
                 : {}),
         },
@@ -118,15 +130,24 @@ export const runCli = async (args) => {
             diagnostics = result.diagnostics;
             data = {
                 directory: result.directory,
-                plan: { metadata: result.plan.metadata, rawMetadata: result.plan.rawMetadata },
-                milestones: result.milestones?.milestones.map((entry) => ({
-                    ordinal: entry.ordinal,
-                    ordinalText: entry.ordinalText,
-                    title: entry.title,
-                    id: entry.id,
-                    status: entry.status,
-                    location: entry.location,
-                })) ?? null,
+                plan: {
+                    sha256: result.plan.sha256,
+                    metadata: result.plan.metadata,
+                    rawMetadata: result.plan.rawMetadata,
+                },
+                milestones: result.milestones
+                    ? {
+                        sha256: result.milestones.sha256,
+                        milestones: result.milestones.milestones.map((entry) => ({
+                            ordinal: entry.ordinal,
+                            ordinalText: entry.ordinalText,
+                            title: entry.title,
+                            id: entry.id,
+                            status: entry.status,
+                            location: entry.location,
+                        })),
+                    }
+                    : null,
             };
         }
         else if (options.command === 'update') {
@@ -136,10 +157,48 @@ export const runCli = async (args) => {
                 throw planErrors.create('invalidInput');
             const result = await updatePlan(options.directory, parsed.data, options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes });
             diagnostics = result.diagnostics;
-            data = { directory: result.directory, document: result.document, changed: result.changed };
+            data = {
+                directory: result.directory,
+                document: result.document,
+                changed: result.changed,
+                sha256: result.sha256,
+                ...('assignedMilestoneIds' in result
+                    ? { assignedMilestoneIds: result.assignedMilestoneIds }
+                    : {}),
+            };
+        }
+        else if (options.command === 'write' || options.command === 'remove-milestones') {
+            const raw = await readMutationInput(options.input, options.maxBytes ?? DEFAULT_MAX_BYTES);
+            const readOptions = options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes };
+            let result;
+            if (options.command === 'write') {
+                const parsed = PlanDocumentWriteSchema.safeParse(raw);
+                if (!parsed.success)
+                    throw planErrors.create('invalidInput');
+                result = await writePlanDocument(options.directory, parsed.data, readOptions);
+            }
+            else {
+                const parsed = RemoveMilestonesSchema.safeParse(raw);
+                if (!parsed.success)
+                    throw planErrors.create('invalidInput');
+                result = await removeMilestones(options.directory, parsed.data, readOptions);
+            }
+            diagnostics = result.diagnostics;
+            data = {
+                directory: result.directory,
+                document: result.document,
+                changed: result.changed,
+                sha256: result.sha256,
+                ...('assignedMilestoneIds' in result
+                    ? { assignedMilestoneIds: result.assignedMilestoneIds }
+                    : {}),
+            };
         }
         else {
-            const inspection = await inspectPlan(options.directory, options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes });
+            const inspection = await inspectPlan(options.directory, {
+                ...(options.maxBytes === undefined ? {} : { maxBytes: options.maxBytes }),
+                ...(options.fingerprint ? { fingerprint: options.fingerprint } : {}),
+            });
             diagnostics = inspection.diagnostics;
             const operationalFailure = diagnostics.some((item) => item.code === 'UNREADABLE_DOCUMENT' || item.code === 'FILE_TOO_LARGE');
             if (options.command === 'check') {

package/dist/cli/types.d.ts

@@ -1,11 +1,13 @@
+import type { IPlanFingerprintOptions } from '../protocol/index.ts';
 /** Validated CLI requests; file paths stay explicit. */
 export type IArguments = {
-    command: 'inspect' | 'check' | 'create' | 'update' | 'help' | 'version';
+    command: 'inspect' | 'check' | 'create' | 'update' | 'write' | 'remove-milestones' | 'help' | 'version';
     directory?: string;
     maxBytes?: number;
     input?: string;
     slug?: string;
     root?: string;
     includeBody: boolean;
+    fingerprint?: IPlanFingerprintOptions;
     json: boolean;
 };

package/dist/documents/fingerprints.d.ts

@@ -0,0 +1,19 @@
+import { type IPlanFingerprintOptions } from '../protocol/index.ts';
+import type { IParsedPlan, IPlanFingerprint } from './types.ts';
+/** Package-private reuse of an existing observation, including absent/unreadable plans. */
+export declare const fingerprintObservation: (plan: IParsedPlan | null, options: IPlanFingerprintOptions) => IPlanFingerprint;
+/**
+ * Hash strict deterministic JSON of the exact body and raw metadata after explicit exclusions.
+ * Missing preferred metadata does not prevent hashing. Ambiguous/non-JSON-safe YAML does.
+ * The digest is an observation, never an approval or completion decision.
+ * @param source Original plan Markdown.
+ * @param options Metadata keys to omit; defaults to none and reports unique applied keys.
+ * @returns Lowercase SHA-256, or null with diagnostics when the structure is unavailable.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * @example
+ * import { fingerprintPlan } from 'jg-plans';
+ * const fingerprint = fingerprintPlan('# Work', { excludeMetadataKeys: ['status'] });
+ * console.log(fingerprint.sha256);
+ */
+export declare const fingerprintPlan: (source: string, options?: IPlanFingerprintOptions) => IPlanFingerprint;

package/dist/documents/fingerprints.js

@@ -0,0 +1,56 @@
+import { hashValue } from 'jg-crypto';
+import { stringifyJsonDeterministically } from 'jg-utilities';
+import { planErrors } from "../errors/index.js";
+import { PlanFingerprintOptionsSchema } from "../protocol/index.js";
+import { parsePlan } from "./plan.js";
+import { diagnostic } from "./utilities.js";
+const UNAVAILABLE_CODES = new Set([
+    'UNTERMINATED_FRONTMATTER',
+    'INVALID_YAML',
+    'YAML_WARNING',
+    'METADATA_NOT_MAPPING',
+    'YAML_VALUE_UNAVAILABLE',
+]);
+/** Package-private reuse of an existing observation, including absent/unreadable plans. */
+export const fingerprintObservation = (plan, options) => {
+    const parsed = PlanFingerprintOptionsSchema.safeParse(options);
+    if (!parsed.success)
+        throw planErrors.create('invalidInput');
+    const excludeMetadataKeys = [...new Set(parsed.data.excludeMetadataKeys ?? [])];
+    const diagnostics = plan?.diagnostics.filter((item) => UNAVAILABLE_CODES.has(item.code)) ?? [];
+    if (plan && !diagnostics.length) {
+        try {
+            const excluded = new Set(excludeMetadataKeys);
+            const metadata = Object.fromEntries(Object.entries(plan.frontmatter ? plan.rawMetadata : {}).filter(([key]) => !excluded.has(key)));
+            const payload = stringifyJsonDeterministically({ body: plan.body, metadata }, { strict: true });
+            return { sha256: hashValue(payload), excludeMetadataKeys, diagnostics: [] };
+        }
+        catch {
+            // Serialization failures may include source values; expose only a safe observation.
+        }
+    }
+    return {
+        sha256: null,
+        excludeMetadataKeys,
+        diagnostics: diagnostics.length
+            ? diagnostics
+            : [
+                diagnostic('plan', 'FINGERPRINT_UNAVAILABLE', 'A structural fingerprint is unavailable for this document.'),
+            ],
+    };
+};
+/**
+ * Hash strict deterministic JSON of the exact body and raw metadata after explicit exclusions.
+ * Missing preferred metadata does not prevent hashing. Ambiguous/non-JSON-safe YAML does.
+ * The digest is an observation, never an approval or completion decision.
+ * @param source Original plan Markdown.
+ * @param options Metadata keys to omit; defaults to none and reports unique applied keys.
+ * @returns Lowercase SHA-256, or null with diagnostics when the structure is unavailable.
+ * @throws
+ * - JG_PLANS_INVALID_INPUT: Invalid jg-plans input
+ * @example
+ * import { fingerprintPlan } from 'jg-plans';
+ * const fingerprint = fingerprintPlan('# Work', { excludeMetadataKeys: ['status'] });
+ * console.log(fingerprint.sha256);
+ */
+export const fingerprintPlan = (source, options = {}) => fingerprintObservation(parsePlan(source), options);

package/dist/documents/index.d.ts

@@ -1,5 +1,6 @@
 export { checkPlan } from './check.ts';
 export { parseMilestones } from './milestones.ts';
 export { parsePlan } from './plan.ts';
+export { fingerprintPlan } from './fingerprints.ts';
 export { sourceLines } from './utilities.ts';
-export type { ICheckResult, IFrontmatter, IMarker, IMilestone, IOverviewRow, IParsedMilestones, IParsedPlan, } from './types.ts';
+export type { ICheckResult, IFrontmatter, IMarker, IMilestone, IOverviewRow, IParsedMilestones, IParsedPlan, ISourceSpan, IHeadingSection, IPlanFingerprint, } from './types.ts';

package/dist/documents/index.js

@@ -1,5 +1,6 @@
 export { checkPlan } from "./check.js";
 export { parseMilestones } from "./milestones.js";
 export { parsePlan } from "./plan.js";
+export { fingerprintPlan } from "./fingerprints.js";
 // Package-private lexical support; omitted from the package's public root exports.
 export { sourceLines } from "./utilities.js";