Add Hello Echo demo and docs lifecycle policy

[flyingrobots]

Summary

• add cargo xtask hello-echo as a 30-second evidence capsule for Echo
• update the README with the FAQ/onramp framing for common Echo misconceptions
• add the docs lifecycle policy for design accumulation, canonical domain-doc absorption, supersession, and archive handling

Verification

• cargo fmt --check
• cargo check -p xtask
• cargo xtask hello-echo --json
• npx markdownlint-cli2 README.md
• cargo xtask lint-dead-refs --file README.md
• cargo check
• npx prettier --check docs/procedures/DOCS-LIFECYCLE.md docs/index.md docs/workflows.md
• npx markdownlint-cli2 docs/procedures/DOCS-LIFECYCLE.md docs/index.md docs/workflows.md
• cargo xtask lint-dead-refs --file docs/procedures/DOCS-LIFECYCLE.md --file docs/index.md --file docs/workflows.md
• git diff --check

Notes

The pre-existing untracked docs/README.md.md was left untouched and is not part of this PR.

Summary by CodeRabbit

• New Features

  • Added hello-echo command-line tool for testing and evidence validation.

• Documentation

  • Expanded README with problem statement, vocabulary definitions, and comprehensive FAQ.
  • Introduced documentation lifecycle policy with status tracking for design documents.
  • Updated contributor workflows and documentation navigation.

[coderabbitai]

Warning

Review limit reached

@flyingrobots, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 11 minutes and 37 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: ad2d7d58-22b7-4016-ac28-a8b53e50db0f

📥 Commits

Reviewing files that changed from the base of the PR and between 9009462 and ca134b5.

📒 Files selected for processing (2)

• xtask/Cargo.toml
• xtask/src/hello_echo.rs

📝 Walkthrough

Walkthrough

Establishes documentation lifecycle governance for design docs (active → accepted → absorbed/superseded/archived states), repositions README around lawful evidence framing, and adds a cargo xtask hello-echo command that executes a deterministic warp-core scenario, captures state/artifacts/digests, writes validated WSC, classifies suffix admission, and returns a structured evidence report with feature witness matrix.

Changes

Documentation Governance Framework

Layer / File(s)	Summary
Docs Lifecycle policy foundation docs/procedures/DOCS-LIFECYCLE.md	Defines lifecycle states (active, accepted, absorbed, superseded, archived), required status headers, canonical domain areas, evidence-building workflow, absorption/supersession/archive rules with tombstone requirements, public docs map curation, PR checklist, and anti-patterns with a minimal slice procedure.
Workflow and navigation integration docs/workflows.md, docs/index.md	Session Workflow now requires design packets record lifecycle status/domain/canonical-output/evidence-path and absorb behavior into canonical docs upon implementation landing. Index adds "Docs lifecycle" navigation link and expands Archive Boundary guidance on material retirement and policy application.
README narrative repositioning README.md	Hero tagline replaced with "State is a reading"; new "A Concrete Problem" section articulates need for machine-checkable lawful evidence under named rules in collaboration; "Boundary Vocabulary" table defines Echo-specific terms (ReadingEnvelope, WARP optic, witnessed suffix, retained artifact); comprehensive FAQ compares Echo to Git/blockchain/event sourcing/actor model/CRDTs/databases; Status heading renamed to Current Reality.

Hello Echo Evidence Capsule Tooling

Layer / File(s)	Summary
CLI command and argument wiring xtask/Cargo.toml, xtask/src/main.rs	Adds blake3, bytes, hex, warp-core (with native_rule_bootstrap feature) dependencies. Defines HelloEchoArgs with --json, --out-dir (default target/hello-echo), --max-ms (default 30000) flags. Adds Commands::HelloEcho enum variant and run_hello_echo handler that calls hello_echo::run and prints JSON or human-readable report.
Report data model and serialization xtask/src/hello_echo.rs (config/report structs)	HelloEchoConfig struct (out_dir, max_ms). HelloEchoReport root capturing demo verdict, elapsed_ms, max_ms, deterministic_evidence_digest, features, worldline, ingress, receipt, counter, hashes, patch, wsc, continuum, inspection. Nested report types: FeatureEvidence, WorldlineReport, IngressReport, ReceiptReport, ReceiptEntryReport, CounterReport, HashReport, PatchReport, WscReport, ContinuumReport, InspectionReport.
Capsule execution and time/budget enforcement xtask/src/hello_echo.rs (run, run_capsule)	run() entry point measures elapsed time, enforces max_ms budget, calls run_capsule to orchestrate scenario execution, transforms artifacts via CapsuleArtifacts::into_report, returns HelloEchoReport or error on store/engine/WSC/suffix failures. run_capsule creates output directory, initializes GraphStore and warp engine, registers counter rule, commits tick with local intent envelopes, reads result, writes/validates WSC, exports/imports suffix bundle, returns all artifacts.
Graph store initialization and counter rule plumbing xtask/src/hello_echo.rs (initial_store, counter_rule, counter helpers)	initial_store() constructs GraphStore with root/counter nodes and edge. counter_rule/counter_matcher/counter_executor/counter_footprint define rewrite rule. Intent parsing helpers (read_intent_amount, parse_amount, intent_bytes) translate attachment-based values into increments with overflow checks. Serialization helpers (counter_node_id, counter_attachment, counter_from_attachment, read_counter_from_state) manage counter identity and state readback.
WSC and continuum suffix handling xtask/src/hello_echo.rs (write_and_validate_wsc, continuum_shell, context impls)	write_and_validate_wsc() builds WSC from worldline/tick, writes to disk, validates via WscFile, computes content/state/attachment digests, returns file path and hashes. continuum_shell() exports/imports suffix bundle, classifies WitnessedSuffixAdmissionOutcome as label, counts admitted refs. DemoSuffixExportContext and DemoSuffixAdmissionContext implement context traits to supply source entries, boundary witness, shell digest, basis resolution, and local admission posture.
Report transformation and evidence digest xtask/src/hello_echo.rs (into_report, receipt_report, feature_matrix, digest)	CapsuleArtifacts::into_report() transforms runtime artifacts into HelloEchoReport by deriving ingress hashes/payloads, receipt summaries, feature evidence, and inspection commands. receipt_report() summarizes applied/rejected/conflict entry counts and blocked_by indices. feature_matrix() builds fixed FeatureEvidence list with witness counts from ingress/receipt/conflicts/patch-ops/WSC/continuum. deterministic_evidence_digest() computes Blake3 hash over commit/state/plan/decision/receipt/patch/WSC/continuum/counter as hex.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• flyingrobots/echo#308: Both PRs extend xtask/src/main.rs CLI wiring by adding new Commands enum subcommands and dispatch handlers; this PR adds hello-echo, PR#308 adds pr-status/pr-threads/pr-preflight.

Suggested labels

tooling

---

🎮 State is a reading—the game engine now proves it.
Lifecycle docs find their witness, WSC digests their proof,
and Echo's suffix shell admits what's lawful under WARP.
Run the capsule. Trust the hashes. Archive the evidence.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the two main changes: adding the Hello Echo demo and the docs lifecycle policy. Both components are clearly present in the changeset.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch cycle/hello-echo-demo

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@xtask/Cargo.toml`:
- Around line 14-18: The dependency constraint bytes = "1.0" is too broad and
may resolve to a vulnerable release; update the xtask dependency for bytes to
require the patched range (e.g. set bytes to ">=1.11.1" or pin to "1.11.1" or
newer) in Cargo.toml so Cargo will not select versions in the vulnerable range,
and then run cargo update -p bytes and verify Cargo.lock records bytes >=
1.11.1; reference the bytes dependency entry in xtask/Cargo.toml when making the
change.

In `@xtask/src/hello_echo.rs`:
- Line 323: Change function parameters from &PathBuf to &Path for idiomatic path
references: update the signature of run_capsule(out_dir: &PathBuf) ->
Result<CapsuleArtifacts> to run_capsule(out_dir: &Path) ->
Result<CapsuleArtifacts>, then adjust all callers to pass &path or
path.as_path() instead of requiring owned PathBuf; do the same for the other
function that currently takes &PathBuf (the second occurrence noted in the
review). Ensure any local variable types or imports that assumed PathBuf
ownership are updated to use &Path or convert with .to_path_buf() only where
ownership is needed.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 5b96f10d-8376-4006-b421-ea7149b16bf0

📥 Commits

Reviewing files that changed from the base of the PR and between c26e3ed and 9009462.

⛔ Files ignored due to path filters (1)

• Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (7)

• README.md
• docs/index.md
• docs/procedures/DOCS-LIFECYCLE.md
• docs/workflows.md
• xtask/Cargo.toml
• xtask/src/hello_echo.rs
• xtask/src/main.rs