Skip to content

feat: developer CLI and provenance payload spec (PP-1) #289

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
flyingrobots wants to merge 13 commits into
base: main
Choose a base branch
from
Open

feat: developer CLI and provenance payload spec (PP-1) #289

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
7aab434
refactor!: remove warp-ffi crate and close C ABI path
flyingrobots Mar 4, 2026
d21c111
feat(cli): implement developer CLI and provenance payload spec
flyingrobots Mar 4, 2026
4c1f95a
fix(warp-cli): pass bench filter as Criterion regex, not cargo target
flyingrobots Mar 4, 2026
d17a790
fix(warp-cli): document --expected warp-0 limitation, warn on multi-warp
flyingrobots Mar 4, 2026
1d6ce82
fix(warp-cli): remove unused colored dep, harden emit and signal repo…
flyingrobots Mar 4, 2026
e9ba2ee
fix(docs): correct TASKS-DAG spec path and SPEC-0005 byte counts
flyingrobots Mar 4, 2026
9b56db2
fix(xtask): prefix subcommand names in man page .TH headers
flyingrobots Mar 4, 2026
c167b5e
fix(warp-cli): improve error handling, add constants, harden edge cases
flyingrobots Mar 4, 2026
e407a6e
docs: update project tour, fix CI blank line
flyingrobots Mar 4, 2026
0450063
refactor(warp-cli): narrow pub visibility, idiomatic cleanups
flyingrobots Mar 4, 2026
88ebaee
docs: complete CHANGELOG entries and README for PP-1 review fixes
flyingrobots Mar 4, 2026
314e515
fix: resolve PR feedback — cargo-deny wildcard, bench README, man cle…
flyingrobots Mar 4, 2026
4ff9961
fix: address remaining CodeRabbit findings — spec, tests, robustness
flyingrobots Mar 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 1 addition & 4 deletions .github/workflows/ci.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,7 +93,7 @@ jobs:
workspaces: |
.
# Intentionally test only warp-core under MUSL; warp-wasm targets wasm32
# (wasm-bindgen/js-sys) and warp-ffi has separate cross-compilation concerns.
# (wasm-bindgen/js-sys) and has separate cross-compilation concerns.
- name: cargo test (warp-core, musl)
run: cargo test -p warp-core --target x86_64-unknown-linux-musl

Expand Down Expand Up @@ -344,9 +344,6 @@ jobs:
run: RUSTDOCFLAGS="-D warnings" cargo doc -p warp-core --no-deps
- name: rustdoc warnings gate (warp-geom)
run: RUSTDOCFLAGS="-D warnings" cargo doc -p warp-geom --no-deps
- name: rustdoc warnings gate (warp-ffi)
run: |
if [ -f crates/warp-ffi/Cargo.toml ]; then RUSTDOCFLAGS="-D warnings" cargo doc -p warp-ffi --no-deps; fi
- name: rustdoc warnings gate (warp-wasm)
run: |
if [ -f crates/warp-wasm/Cargo.toml ]; then RUSTDOCFLAGS="-D warnings" cargo doc -p warp-wasm --no-deps; fi
Expand Down
116 changes: 116 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,122 @@

## Unreleased

### Fixed — Developer CLI (`echo-cli`)

- **Bench Filter:** `echo-cli bench --filter <pattern>` now passes the filter
as a Criterion regex (`-- <pattern>`) instead of a `--bench` cargo target
selector. Previous behavior would look for a bench _target_ named after the
pattern rather than filtering benchmarks by regex.
- **Verify Expected Hash:** `--expected` now correctly reports "unchecked" for
warps 1+ instead of silently claiming "pass". Emits a stderr warning when
`--expected` is used with multi-warp snapshots. Text and JSON output now
use consistent lowercase status values.
- **Unused Dependency:** Removed `colored = "2"` from `warp-cli` (declared but
never imported).
- **Output Hardening:** `emit()` no longer panics on JSON serialization failure;
falls back to stderr. Bench exit status now reports Unix signal numbers
instead of a misleading `-1`.
- **Error Handling:** `collect_criterion_results` now logs a warning on
unparseable `estimates.json` instead of silently skipping. `format_duration`
returns "N/A" for NaN/negative values. `att_row_to_value` warns on missing
blob data instead of silent fallback.
- **Dead Code:** Replaced blanket `#![allow(dead_code)]` on `lib.rs` with
targeted `#[allow(dead_code)]` on the `output` module only.
- **Man Page Headers:** Subcommand man pages now use prefixed names
(`echo-cli-bench`, `echo-cli-verify`, `echo-cli-inspect`) in `.TH` headers
instead of bare subcommand names.
- **Visibility:** Narrowed all non-API structs and functions from `pub` to
`pub(crate)` in bench, verify, inspect, and wsc_loader modules. Only
`cli.rs` types remain `pub` (required by xtask man page generation).
- **cargo-deny:** Fixed wildcard dependency error for `warp-cli` in
`xtask/Cargo.toml` by adding explicit `version = "0.1.0"` alongside
the path override.
- **Man Page Cleanup:** `cargo xtask man-pages` now removes stale
`echo-cli*.1` files before regeneration so the output directory is an
exact snapshot.

### Fixed — Code Review (PR #289, Round 2)

- **Inspect Tree Warp Identity:** Multi-warp snapshots now label each tree
section with its warp index (`Tree (warp 0):`, `Tree (warp 1):`) instead of
flattening all trees into a single unlabeled `Tree:` section.
- **WSC Loader Attachment Checks:** Replaced `debug_assert!` with runtime
warnings for attachment multiplicity violations. Previously, release builds
silently dropped extra attachments; now emits a warning to stderr.
- **Test Naming:** Renamed `tampered_wsc_fails` to `tampered_wsc_does_not_panic`
to accurately reflect the test's behavior (no assertion, just no-panic guard).
- **Test Coverage:** Added `roundtrip_with_edge_attachments` and
`roundtrip_with_descend_attachment` tests to `wsc_loader.rs`, covering
previously untested code paths.
- **SPEC-0005 `global_tick` Invariant:** Reworded from `patches[i].global_tick == i`
to correctly state contiguity relative to the payload's start tick, since
payloads can begin at any absolute tick via `from_store(store, wl, 5..10)`.
- **SPEC-0005 BTR Verification:** Fixed step 5 of the verification algorithm
to reference the actual hash formula from §5.4 instead of a nonexistent
`parents` field.
- **SPEC-0005 Derivation Algorithm:** Fixed backward-cone traversal that dropped
transitive dependencies. The original filter checked the root query slot at
every hop; now accepts all frontier nodes unconditionally (they are already
known-causal) and traces all `in_slots` backward.
- **Stale `warp-ffi` References:** Removed dead `warp-ffi` entry from
`det-policy.yaml`, C ABI text from `phase1-plan.md`, and stale CLI names
from `rust-rhai-ts-division.md`.

Comment on lines +42 to +68
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

PR review archaeology doesn't belong in a user-facing changelog.

Lines 42-68 document the iterative code review process ("Round 2"), including test renames, internal test coverage additions, and reviewer-requested fixes. This is PR implementation minutiae, not user-facing release documentation.

Violations:

  1. Test naming (line 50-51): Renaming tampered_wsc_fails → tampered_wsc_does_not_panic is internal—users never see test names in releases.
  2. Test coverage (lines 52-54): Adding roundtrip_with_edge_attachments tests is implementation QA, not a deliverable.
  3. Forward reference landmine (lines 55-64): SPEC-0005 fixes appear before SPEC-0005 is introduced (lines 114-123), forcing readers to parse fixes for something they haven't encountered yet.
  4. Stale reference claims (lines 65-67): Per learning, claims about "removed stale warp-ffi references" require verification via git show <sha>, not working-tree inspection—but the changelog provides no commit SHA for readers to verify.

What belongs in a changelog:

  • User-visible bug fixes from prior releases
  • Breaking changes with migration paths
  • New features with usage examples
  • Deprecation warnings

What doesn't:

  • PR review iterations
  • Test suite internals
  • Commit-by-commit fix enumeration
🗑️ Proposed deletion

Delete lines 42-68 entirely. If any fixes have genuine user impact (e.g., inspect multi-warp tree labeling), migrate them to the relevant "Added" or "Fixed" section with user-facing descriptions:

 ### Added — Developer CLI (`echo-cli`)
 
 ...
 - **Inspect Subcommand:** `echo-cli inspect <snapshot.wsc> [--tree]` displays
   WSC metadata (tick, schema hash, warp count), graph statistics (node/edge
   counts, type breakdown, connected components via BFS), and optional ASCII
-  tree rendering depth-limited to 5 levels.
+  tree rendering depth-limited to 5 levels. Multi-warp snapshots label each
+  tree with its warp index (`Tree (warp 0):`, `Tree (warp 1):`).

Based on learnings: Retrieved learnings instruct that claims about stale reference removal in CHANGELOG.md must be verified via commit diff inspection (git show <sha>), not current working tree state, to avoid false negatives. This section provides no commit references for verification.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CHANGELOG.md` around lines 42 - 68, Remove the PR-iteration noise in lines
42-68: delete the “Round 2” block and do not list internal test renames or added
tests (remove references to tampered_wsc_does_not_panic and
roundtrip_with_edge_attachments / roundtrip_with_descend_attachment); instead,
if any item is genuinely user-facing (e.g., "Inspect Tree Warp Identity" or the
runtime behavior change described in "WSC Loader Attachment Checks" or the
SPEC-0005 verification/derivation fixes), move a single concise user-facing
bullet into the appropriate "Fixed" or "Changed" section with clear behavior
description and include a commit SHA (via git show <sha>) to verify the removal
of stale references (the "warp-ffi" claim) rather than relying on working-tree
inspection; do not mention review rounds or internal QA steps.

### Fixed — Docs & CI

- **TASKS-DAG Spec Path:** `SPEC-PROVENANCE-PAYLOAD.md` →
`SPEC-0005-provenance-payload.md` in sub-task title and AC1 (two
occurrences). Same stale path fixed in ROADMAP backlog `security.md`.
- **SPEC-0005 Byte Counts:** Domain separation tag sizes corrected:
`echo:provenance_payload:v1\0` = 27 bytes (was 28),
`echo:provenance_edge:v1\0` = 24 bytes (was 25).
- **Project Tour:** Updated `warp-cli` description from "Placeholder CLI home"
to list actual subcommands (verify, bench, inspect).
- **CI Formatting:** Removed stray blank line between warp-geom and warp-wasm
rustdoc steps in `ci.yml`.

Comment on lines +69 to +81
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Changelog fragmentation: Third "Fixed" section dilutes focus.

The changelog now has three separate "Fixed" subsections under "Unreleased" (lines 8, 42, 69), creating cognitive overhead and violating the "keep a changelog" convention of consolidating changes by type.

Additional issues:

  1. Microscopic formatting trivia (lines 79-80): "Removed stray blank line between warp-geom and warp-wasm rustdoc steps" is a one-character diff with zero functional impact. User-facing changelogs document what changed, not how the CI YAML was formatted.

  2. Forward reference recurrence (lines 74-76): SPEC-0005 byte count fixes appear before SPEC-0005 is introduced (lines 114-123), creating the same forward-reference problem flagged in lines 42-68.

  3. Mixing severity levels: TASKS-DAG spec path fix (user-impacting doc correction) sits next to blank-line removal (non-impacting formatting).

🔨 Consolidation strategy
  1. Merge all "Fixed" subsections into a single "Fixed" section (after "Added", before historical releases per conventional ordering).
  2. Delete formatting trivia (line 79-80).
  3. Move SPEC-0005 fixes to appear after SPEC-0005 introduction, or merge them inline:
 ### Added — Provenance Payload Spec (PP-1)
 
 - **SPEC-0005:** Published `docs/spec/SPEC-0005-provenance-payload.md` mapping
   Paper III (AION Foundations) formalism to concrete Echo types. Defines four
   new types (`ProvenancePayload`, `BoundaryTransitionRecord`, `ProvenanceNode`,
   `DerivationGraph`), wire format with CBOR encoding and domain separation tags,
   two worked examples (3-tick accumulator, branching fork), bridge to existing
   `ProvenanceStore`/`PlaybackCursor` APIs, and attestation envelope with SLSA
-  alignment.
+  alignment.
+  ✓ Domain separation tag sizes corrected: `echo:provenance_payload:v1\0` = 27 bytes,
+    `echo:provenance_edge:v1\0` = 24 bytes.

### Added — Developer CLI (`echo-cli`)

- **CLI Scaffold (`warp-cli`):** Replaced placeholder with full `clap` 4 derive
subcommand dispatch. Three subcommands: `verify`, `bench`, `inspect`. Global
`--format text|json` flag for machine-readable output.
- **Verify Subcommand:** `echo-cli verify <snapshot.wsc>` loads a WSC snapshot,
validates structural integrity via `validate_wsc`, reconstructs the in-memory
`GraphStore` from columnar data, and computes the state root hash. Optional
`--expected <hex>` flag compares against a known hash.
- **WSC Loader:** New `wsc_loader` module bridges WSC columnar format to
`GraphStore` — the inverse of `warp_core::wsc::build_one_warp_input`.
Reconstructs nodes, edges, and attachments from `WarpView`.
- **Bench Subcommand:** `echo-cli bench [--filter <pattern>]` shells out to
`cargo bench -p warp-benches`, parses Criterion JSON from
`target/criterion/*/new/estimates.json`, and renders an ASCII table via
`comfy-table`. Supports `--format json` for CI integration.
- **Inspect Subcommand:** `echo-cli inspect <snapshot.wsc> [--tree]` displays
WSC metadata (tick, schema hash, warp count), graph statistics (node/edge
counts, type breakdown, connected components via BFS), and optional ASCII
tree rendering depth-limited to 5 levels.
- **Man Pages:** Added `clap_mangen`-based man page generation to `xtask`.
`cargo xtask man-pages` generates `docs/man/echo-cli.1`,
`echo-cli-verify.1`, `echo-cli-bench.1`, `echo-cli-inspect.1`.

Comment on lines +82 to +105
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Section ordering: "Added" should precede "Fixed" to establish context.

Lines 82-105 document the addition of echo-cli, but appear after lines 8-41 which document fixes to the same CLI. This violates conventional changelog ordering (Added → Changed → Deprecated → Removed → Fixed → Security) and forces readers to parse fixes before understanding what was added.

Additional observations:

  1. Command discoverability (line 103): "cargo xtask man-pages" is referenced without context. Users encountering this in the changelog won't know:

    • That xtask is a repo-specific convention (per learning: "Use cargo xtask … for repo maintenance")
    • How to discover available xtask commands

  2. Prose density: The bullet points pack multiple concepts into single sentences, harming scannability. Compare:

    • Current: "Optional --expected <hex> flag compares against a known hash."
    • Scannable: "Optional --expected <hex>: Compare reconstructed hash against known value."
📐 Ordering fix
  1. Move this section to line 8, before all "Fixed" sections
  2. Add xtask context for external readers:
 - **Man Pages:** Added `clap_mangen`-based man page generation to `xtask`.
-  `cargo xtask man-pages` generates `docs/man/echo-cli.1`,
+  Run `cargo xtask man-pages` (see `.cargo/config.toml` for xtask setup) to generate
+  `docs/man/echo-cli.1`,
   `echo-cli-verify.1`, `echo-cli-bench.1`, `echo-cli-inspect.1`.
  1. Break dense bullets into sub-bullets for arguments/flags.

Based on learnings: The learning states "Use cargo xtask … for repo maintenance (see xtask/ and .cargo/config.toml)"—the changelog should help external users discover this convention.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CHANGELOG.md` around lines 82 - 105, Move the "Added — Developer CLI
(echo-cli)" section so it appears before any "Fixed" sections (i.e., place this
Added section before the existing Fixed entries), add one clarifying sentence
about the xtask convention and how to discover available xtask commands
(mentioning that `xtask/` and `.cargo/config.toml` define repo-specific xtask
commands and that `cargo xtask --help` lists them) and update the bullets under
"Verify", "Bench", and "Inspect" to split flags/arguments from behavior (e.g.,
"Optional `--expected <hex>`: Compare reconstructed hash against known value",
"`--format text|json`: Choose output format", "`--filter <pattern>`: Limit
benchmarks") so each flag is its own sub-bullet for scannability; also expand
the "Man Pages" bullet to explicitly note the command `cargo xtask man-pages`
generates docs/man/echo-cli.1 and related man pages.

### Removed

- **`warp-ffi` crate deleted:** The C ABI integration path (`crates/warp-ffi`)
has been removed. The C ABI approach was abandoned in favor of Rust plugin
extension via `RewriteRule` trait registration and Rhai scripting. See
TASKS-DAG.md #26 (Graveyard). This is a **BREAKING CHANGE** for any
downstream code that depended on the C FFI surface.

Comment on lines +106 to +113
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟠 Major

Breaking change lacks actionable migration path for affected users.

Lines 106-113 correctly document the warp-ffi removal as a BREAKING CHANGE (addressing past review comment), but the migration guidance is insufficient for downstream C FFI consumers.

Issues:

  1. Section placement: "Removed" appears between two "Added" sections (lines 82-105, 114-123), violating conventional ordering. Standard format: Added → Changed → Deprecated → Removed → Fixed → Security.

  2. Internal reference leak (line 111): "See TASKS-DAG.md #26 (Graveyard)" assumes readers have repo access. External users won't find this reference—it's internal task tracking, not public documentation.

  3. Migration guidance is vague:

    • ✓ States what was removed (C ABI path)
    • ✓ Names replacement path (RewriteRule/Rhai)
    • ✗ No concrete steps: How do C FFI users migrate? Are there docs? Examples? Is this even feasible for their use case, or is this an abandonment?

For a breaking removal, users need:

  • What scenarios were C FFI used for?
  • How to achieve those scenarios with the new approach
  • Link to migration guide or examples
  • Statement if some use cases are now unsupported (honest triage)
🔧 Improved migration guidance 
 ### Removed
 
 - **`warp-ffi` crate deleted:** The C ABI integration path (`crates/warp-ffi`)
   has been removed. The C ABI approach was abandoned in favor of Rust plugin
-  extension via `RewriteRule` trait registration and Rhai scripting. See
-  TASKS-DAG.md `#26` (Graveyard). This is a **BREAKING CHANGE** for any
-  downstream code that depended on the C FFI surface.
+  extension via `RewriteRule` trait registration and Rhai scripting.
+  
+  **Migration:** If you were using `warp-ffi` for external rule engines:
+  - Use the Rust-native `RewriteRule` trait (see `crates/warp-core/src/rules.rs`)
+  - For non-Rust environments, evaluate the developer CLI (`echo-cli`) for
+    out-of-process integration via WSC snapshots
+  - Rhai scripting support is planned but not yet available
+  
+  This is a **BREAKING CHANGE**. If your use case is blocked, open a GitHub
+  discussion with your integration requirements.

Move this section to appear after "Added — Provenance Payload Spec" (line 123).

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CHANGELOG.md` around lines 106 - 113, Move the "Removed" block about the
warp-ffi crate so it sits after the "Added — Provenance Payload Spec" section to
follow standard changelog ordering, remove the internal-only reference "See
TASKS-DAG.md `#26` (Graveyard)" and replace it with a public doc link or remove it
entirely, and expand the item for the breaking change (referencing warp-ffi,
RewriteRule, and Rhai) to include concrete migration guidance: list common C-FFI
use cases that were supported, provide step-by-step migration options to the
RewriteRule/Rhai path (or explicitly state which scenarios are unsupported), and
add links to any migration guide, examples or sample code that demonstrate the
equivalent workflow and API mappings for downstream consumers.

### Added — Provenance Payload Spec (PP-1)

- **SPEC-0005:** Published `docs/spec/SPEC-0005-provenance-payload.md` mapping
Paper III (AION Foundations) formalism to concrete Echo types. Defines four
new types (`ProvenancePayload`, `BoundaryTransitionRecord`, `ProvenanceNode`,
`DerivationGraph`), wire format with CBOR encoding and domain separation tags,
two worked examples (3-tick accumulator, branching fork), bridge to existing
`ProvenanceStore`/`PlaybackCursor` APIs, and attestation envelope with SLSA
alignment.

Comment on lines +8 to +123
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify SPEC-0005 file and check changelog claims

# Check SPEC-0005 exists
echo "=== Verifying SPEC-0005 file ==="
if [ -f "docs/spec/SPEC-0005-provenance-payload.md" ]; then
  echo "✓ SPEC-0005 file exists"
  wc -l docs/spec/SPEC-0005-provenance-payload.md
else
  echo "✗ SPEC-0005 file NOT FOUND at claimed path"
fi

# Verify cargo xtask man-pages command exists
echo -e "\n=== Checking xtask man-pages command ==="
if [ -f "xtask/src/main.rs" ]; then
  if grep -q "man-pages" xtask/src/main.rs 2>/dev/null; then
    echo "✓ man-pages command found in xtask"
    grep -A5 "man-pages" xtask/src/main.rs | head -10
  else
    echo "✗ man-pages command not found in xtask"
  fi
else
  echo "xtask/src/main.rs not found"
fi

# Check for remaining warp-ffi references (should be minimal after removal)
echo -e "\n=== Scanning for remaining warp-ffi references ==="
echo "Changelog claims: 'Removed dead warp-ffi entry from det-policy.yaml, C ABI text from phase1-plan.md'"
rg -i "warp-ffi" --type md --type yaml 2>/dev/null | head -20 || echo "No rg output"

# Check if colored dependency was actually removed from warp-cli
echo -e "\n=== Verifying colored dependency removal claim ==="
if [ -f "crates/warp-cli/Cargo.toml" ]; then
  if grep -q "colored" crates/warp-cli/Cargo.toml; then
    echo "✗ 'colored' still present in warp-cli/Cargo.toml"
    grep "colored" crates/warp-cli/Cargo.toml
  else
    echo "✓ 'colored' not found in warp-cli/Cargo.toml"
  fi
else
  echo "crates/warp-cli/Cargo.toml not found"
fi

# Check for det-policy.yaml
echo -e "\n=== Checking det-policy.yaml for warp-ffi entry ==="
if [ -f "det-policy.yaml" ]; then
  if grep -q "warp-ffi" det-policy.yaml; then
    echo "✗ warp-ffi entry still in det-policy.yaml"
    grep -n "warp-ffi" det-policy.yaml
  else
    echo "✓ No warp-ffi in det-policy.yaml"
  fi
fi

# Check for phase1-plan.md
echo -e "\n=== Checking phase1-plan.md for C ABI references ==="
if [ -f "phase1-plan.md" ]; then
  if grep -qi "C ABI\|FFI\|warp-ffi" phase1-plan.md; then
    echo "✗ C ABI or warp-ffi references still in phase1-plan.md"
    grep -ni "C ABI\|FFI\|warp-ffi" phase1-plan.md
  else
    echo "✓ No C ABI/warp-ffi references in phase1-plan.md"
  fi
fi

Repository: flyingrobots/echo

Length of output: 1241

🏁 Script executed:

#!/bin/bash
# Deeper xtask investigation and git history check

echo "=== Searching entire xtask directory for 'man' or 'mangen' ==="
find xtask -type f -name "*.rs" -o -name "*.toml" | xargs grep -l "man\|mangen" 2>/dev/null || echo "No man-page related code found"

echo -e "\n=== Full xtask file structure ==="
ls -la xtask/src/ 2>/dev/null || echo "xtask/src not found"

echo -e "\n=== Checking xtask Cargo.toml dependencies ==="
if [ -f "xtask/Cargo.toml" ]; then
  grep -i "clap\|mangen\|man" xtask/Cargo.toml || echo "No man-page deps found"
fi

echo -e "\n=== Verifying git history for warp-ffi removal ==="
# Check if warp-ffi crate directory was deleted
git log --oneline --all -- crates/warp-ffi 2>/dev/null | head -5 || echo "Cannot access git history"

echo -e "\n=== Check for recent commits touching CHANGELOG or warp-ffi references ==="
git log --oneline -20 2>/dev/null | head -10 || echo "Cannot access git log"

echo -e "\n=== Verify AGENTS.md still references warp-ffi ==="
grep -n "warp-ffi" AGENTS.md 2>/dev/null || echo "warp-ffi not found in AGENTS.md"

Repository: flyingrobots/echo

Length of output: 1272

🏁 Script executed:

#!/bin/bash

echo "=== Searching xtask/src/main.rs for man-pages or mangen usage ==="
rg "man|mangen" xtask/src/main.rs -A 3 | head -30

echo -e "\n=== Git show for warp-ffi deletion commit (12feebb) ==="
git show 12feebb --stat 2>/dev/null | head -20

echo -e "\n=== Check if crates/warp-ffi directory exists ==="
if [ -d "crates/warp-ffi" ]; then
  echo "✗ crates/warp-ffi STILL EXISTS"
  ls -la crates/warp-ffi
else
  echo "✓ crates/warp-ffi directory has been deleted"
fi

echo -e "\n=== Verify all warp-ffi references in public docs ==="
rg "warp-ffi" docs/ AGENTS.md CONTRIBUTING.md 2>/dev/null || echo "Checked docs"

echo -e "\n=== Check if warp-cli crate exists and is properly structured ==="
if [ -d "crates/warp-cli" ]; then
  echo "✓ warp-cli crate exists"
  ls -la crates/warp-cli/
  echo -e "\n=== warp-cli/Cargo.toml (first 30 lines) ==="
  head -30 crates/warp-cli/Cargo.toml
else
  echo "✗ crates/warp-cli not found"
fi

Repository: flyingrobots/echo

Length of output: 3406

Changelog refactoring + AGENTS.md blocking issue before release.

The "Unreleased" section violates changelog conventions (triple "Fixed" fragmentation, section ordering chaos, forward references to SPEC-0005 before introduction, PR archaeology, formatting trivia). These require structural refactoring per the original assessment.

Critical blocking issue: AGENTS.md line 12 still claims warp-ffi is an active crate requiring documentation, directly contradicting the CHANGELOG claim of deletion. This creates an enforced policy document that is false—update AGENTS.md to remove the warp-ffi reference immediately.

Additional structural flaws:

  • Lines 8, 42, 69 fragment fixes across three sections (consolidate)
  • Lines 55-64, 74-76 reference SPEC-0005 before its introduction (lines 114-123)
  • Lines 42-68 document PR review iterations and test naming (remove from user-facing notes)
  • Line 79-80 documents a single blank-line removal (zero functional value)
  • Breaking change (warp-ffi removal, lines 106-113) lacks migration guidance for C FFI users

Refactor before release: merge three "Fixed" sections, reorder per convention (Added → Removed → Fixed), promote SPEC-0005 addition above its fixes, delete internal review iterations and formatting trivia, strengthen migration guidance for breaking changes.

🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CHANGELOG.md` around lines 8 - 123, Update AGENTS.md to remove any reference
to the deleted crate "warp-ffi" (ensure no statement at line ~12 claims it is
active), then refactor CHANGELOG.md: merge the three "Fixed" subsections under
"Unreleased" into a single "Fixed" list, reorder top-level sections to Added →
Removed → Fixed, move the SPEC-0005 "Added" entry above any fixes that reference
it (so references to SPEC-0005 no longer precede its introduction), strip
PR-review/internal notes (entries about test renames, round 2 details, and
trivial CI formatting) from user-facing changelog, and expand the "Removed —
warp-ffi crate deleted" breaking-change entry to include clear migration
guidance for former C FFI users; locate sections by the headings "Unreleased",
"Fixed — Developer CLI (`echo-cli`)", "Fixed — Code Review (PR `#289`, Round 2)",
"Added — Provenance Payload Spec (PP-1)", and the "warp-ffi" removal paragraph
to perform edits.

Comment on lines +114 to +123
Copy link
Contributor

@coderabbitai coderabbitai bot Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Forward reference problem: SPEC-0005 fixes precede its introduction.

Lines 114-123 introduce SPEC-0005, but fixes to SPEC-0005 already appeared in:

  • Lines 55-64: "SPEC-0005 global_tick Invariant", "SPEC-0005 BTR Verification", "SPEC-0005 Derivation Algorithm"
  • Lines 74-76: "SPEC-0005 Byte Counts"

This forces readers to parse corrections to a spec they haven't encountered yet, creating cognitive dissonance.

Additional issues:

  1. Unexplained identifier: "(PP-1)" in the heading lacks context. Is this:

    • A milestone code?
    • A feature flag?
    • A paper reference?
    • Internal project tracking?

    External readers won't know.

  2. Dense enumeration (lines 117-122): One bullet point lists four types, CBOR format, two examples, API bridges, and attestation envelopes. This is a 5-in-1 bullet that forces readers to parse a nested hierarchy inline.

  3. Path verification gap: The changelog claims docs/spec/SPEC-0005-provenance-payload.md was published but doesn't verify the file exists or matches the description. (Cannot verify without file access, but worth flagging.)

📖 Improved structure
  1. Move this section before lines 55-64 so the introduction precedes fixes
  2. Expand dense bullet into sub-bullets:
 ### Added — Provenance Payload Spec (PP-1)
 
-- **SPEC-0005:** Published `docs/spec/SPEC-0005-provenance-payload.md` mapping
-  Paper III (AION Foundations) formalism to concrete Echo types. Defines four
-  new types (`ProvenancePayload`, `BoundaryTransitionRecord`, `ProvenanceNode`,
-  `DerivationGraph`), wire format with CBOR encoding and domain separation tags,
-  two worked examples (3-tick accumulator, branching fork), bridge to existing
-  `ProvenanceStore`/`PlaybackCursor` APIs, and attestation envelope with SLSA
-  alignment.
+- **SPEC-0005 (Provenance Payload):** Published formal spec at
+  `docs/spec/SPEC-0005-provenance-payload.md`, mapping Paper III (AION Foundations)
+  formalism to concrete Echo types.
+  - **Types:** `ProvenancePayload`, `BoundaryTransitionRecord`, `ProvenanceNode`,
+    `DerivationGraph`
+  - **Wire format:** CBOR encoding with domain separation tags
+  - **Examples:** 3-tick accumulator, branching fork scenarios
+  - **Integration:** Bridges to `ProvenanceStore`/`PlaybackCursor` APIs
+  - **Attestation:** Envelope aligned with SLSA provenance spec
+  
+  *(PP-1 refers to feature tracking ID in internal roadmap.)*
  1. Reorder sections: Added (this) → Added (CLI) → Removed → Fixed (consolidated).
🤖 Prompt for AI Agents 
Verify each finding against the current code and only fix it if needed.

In `@CHANGELOG.md` around lines 114 - 123, Move the SPEC-0005 block so the "Added
— Provenance Payload Spec (PP-1)" section appears before the earlier fix entries
that reference SPEC-0005; clarify the meaning of the "(PP-1)" tag (e.g.,
milestone, RFC or internal tracker) next to the heading; split the single dense
bullet into sub-bullets that enumerate the four new types (ProvenancePayload,
BoundaryTransitionRecord, ProvenanceNode, DerivationGraph), the wire
format/CBOR/domain separation note, the two worked examples, the bridge to
ProvenanceStore/PlaybackCursor APIs, and the attestation envelope/SLSA
alignment; and add a verification note that the referenced file
docs/spec/SPEC-0005-provenance-payload.md exists and matches the description.

### Fixed (CI)

- **Evidence Derivation:** Replaced artifact-directory-presence check for `DET-001` with
Expand Down
Loading