tools-update-process

Sync canonical versioned managed blocks from the source-of-truth process document into every real repo's docs/PROCESS.md (only). Replace-never-append; strict markers; --check exits nonzero on drift; byte-verified. v0.2 BREAKING: no longer writes .claude/CLAUDE.md.

What it is for

tools-update-process — sync canonical versioned managed blocks from the source-of-truth process document into every ecosystem repo's docs/PROCESS.md.

A managed block is delimited by a versioned sentinel pair: <!-- canonical:<name> v<N> --> … <!-- /canonical:<name> v<N> --> The tool extracts each registered block from the canonical file and, in every target docs/PROCESS.md, replaces the entire prior-version block with the canonical bytes. It is idempotent: a re-run with no canonical change is a no-op.

Guarantees (each has a direct test):

• Replace, never append. A target that lacks the marker is *skipped or

failed* per --on-missing, never silently appended to.

• Strict markers. Duplicate, unbalanced, overlapping, malformed, or

version-mismatched markers make that repo FAILED, never mangled.

• Byte-verified. After writing, the file is re-read and the block region

is compared byte-for-byte to the canonical block; a mismatch is FAILED.

• Real roots only. Worktrees (*-wt, wt-*), frozen snapshots

(rp-frozen-*, plus FROZEN_ROOTS for frozen roots whose directory name predates that convention, matched exactly), git linked worktrees, vendored trees, and repos whose docs/PROCESS.md is dirty are skipped with a reason.

• One file. Touches docs/PROCESS.md and nothing else.
• --check writes nothing and exits nonzero on drift; --apply/--commit

exit nonzero on any failure.

BREAKING CHANGE (v0.2.0): this tool no longer writes .claude/CLAUDE.md. A propagation tool with a hidden second file target is wrong; if CLAUDE.md managed-block sync is still needed, add a separate command for it. Do not reintroduce a --include-claude flag — that recreates the mixed responsibility this change removed. The pre-v0.2 <!-- BEGIN managed-block --> (unversioned) convention is no longer managed here; legacy blocks are frozen until migrated to the versioned convention.

House-style: every external command is an explicit argument vector (Command::new(bin).arg(..)), never a shell string (PROCESS.md §4).

Capabilities

MarkerError

tools-update-process — sync canonical versioned managed blocks from the

How to use it

No examples/ target and no doctest in this crate's rustdoc. The tests listed under Verification are the closest executable usage.

Module structure

No public modules: the crate root is its whole surface.

Public surface

`crate root`

No pub use re-exports: every item above is declared in this crate.

Boundary

Depends on no other workspace tier.

Shares tier tools with 84 other crates: tools-advisory-reach, tools-archive-guard, tools-artifact-scaffold, tools-ask-ai-core, tools-ask-ais, tools-ask-gemini, tools-book, tools-book-report, … (84 total).

_What this crate deliberately does NOT own is a judgment. No committed registry records one for it, so none is stated here._

Where it sits

Dependencies

Runtime, from outside the workspace.

Development, in this workspace.

Build. None.

Depended on by. Nothing in this workspace.

Signal flow — what reaches this crate, and what it reaches.

flowchart LR
  SELF["tools-update-process"]
  SELF -->|development| n_tools_cli_conformance["tools-cli-conformance"]
  classDef self fill:#1f883d,stroke:#1f883d,color:#fff;
  class SELF self;

Feature flags

No Cargo features are defined: every capability is unconditional, so no consumer can receive a half-wired crate.

Targets

Error model

No public error type was detected: no public item declares a type named *Error, and no public signature returns one.

Operational characteristics

No unsafe block, unsafe fn, unsafe impl or unsafe trait was found by the parser anywhere in this crate's source.

Configuration

Related capabilities

No workspace crate depends on this one.

Verification

What the tests establish, by name:

• a_frozen_root_without_the_prefix_is_still_excluded — src/main.rs
• clean_target_is_unaffected_by_the_new_path — src/main.rs
• cli_definition_conforms — src/main.rs
• dirty_target_is_skipped_clean_proceeds — src/main.rs
• dirty_with_differing_block_is_never_clobbered — src/main.rs
• dirty_with_matching_block_is_ours_uncommitted_not_a_skip — src/main.rs
• duplicate_open_markers_rejected — src/main.rs
• extract_canonical_roundtrips_and_rejects_bad — src/main.rs
• freezing_does_not_catch_the_project_that_replaced_it — src/main.rs
• identical_block_is_unchanged — src/main.rs
• locate_missing_is_none — src/main.rs
• locate_wellformed_returns_span — src/main.rs
• malformed_missing_version_rejected — src/main.rs
• missing_marker_plans_missing_never_appends — src/main.rs
• name_filter_skips_worktrees_and_frozen — src/main.rs
• name_prefix_is_not_confused — src/main.rs
• overlapping_close_before_open_rejected — src/main.rs
• prior_version_block_is_fully_replaced — src/main.rs
• second_run_is_noop — src/main.rs
• seed_end_appends_at_eof_for_anchorless_targets — src/main.rs
• seed_inserts_after_anchor_and_is_idempotent — src/main.rs
• seed_with_block_already_present_is_noop — src/main.rs
• seed_without_anchor_reports_no_anchor_never_guesses — src/main.rs
• unbalanced_marker_rejected — src/main.rs
• vendored_paths_detected — src/main.rs
• version_mismatch_rejected — src/main.rs

Documentation coverage

pie showData
    title Public items with rustdoc
    "Documented" : 0
    "No rustdoc detected" : 1

Metrics

pie showData
    title Public API by kind
    "method" : 1

pie showData
    title Rust source composition
    "Code" : 860
    "Blank or comment" : 277

Generation

Rendered by tools-corpus corpus readme from repository evidence alone, renderer schema 2, lexicon current. No model, network service or database was consulted. Regenerate with tools-corpus corpus readme --write; verify with --check.