Skip to content

workflows.md

Latest commit

 

History

History
206 lines (148 loc) · 9.75 KB

workflows.md

File metadata and controls

206 lines (148 loc) · 9.75 KB

Workflows (Contributor Playbook)

This doc is the “official workflow index” for Echo: how we work, what invariants we enforce, and the blessed entrypoints/scripts.

Echo is docs-driven and determinism-driven. When in doubt, prefer writing down the invariant and then encoding it as a test or guard.

Session Workflow

  • Record architectural decisions in active design packets (docs/design/), Method items (docs/method/), or PR descriptions.
  • Before opening a PR, run the validation workflow below.

Branch + PR Workflow

  • Isolated Branches: Every new task, feature, or bugfix MUST begin on a fresh, isolated branch based on the latest main (unless context explicitly dictates otherwise). Never mix unrelated objectives on the same branch.
  • Keep main pristine; do work on a branch (prefer echo/<feature> or timeline/<experiment>).
  • Do not rebase; do not force push; do not amend commits.
  • Every PR must be tied to a GitHub Issue. If no issue exists, open one before opening the PR.
  • Include an explicit closing keyword in the PR body (example): Closes #123.

Validation Workflow

Local iteration should start with the narrowest target that proves the changed surface. Prefer the repo-owned slices below before reaching for broad Cargo filters:

cargo xtask test-slice strand
cargo xtask test-slice settlement
cargo xtask test-slice observation
cargo xtask test-slice neighborhood
cargo xtask test-slice warp-core-smoke

Why this matters: cargo test -p warp-core settlement still compiles and launches every crates/warp-core/tests/*.rs integration-test target before applying the runtime filter. That makes narrow runtime work pay for unrelated test binaries and stale fixtures. The test-slice commands use exact Cargo target selection such as --lib settlement::tests or --test strand_contract_tests.

Hard ban during docs inventory and local iteration:

cargo test -p <crate> <filter>

Use only exact test targets:

cargo test -p <crate> --lib <filter>
cargo test -p <crate> --test <test_file_name> <filter>
cargo xtask test-slice <slice>

Checkpoint checks:

cargo fmt --all
cargo test --workspace
cargo clippy --all-targets -- -D warnings -D missing_docs

Tooling Entry Points

Echo uses a few “blessed” command entry points.

make

  • make hooks installs repo git hooks.
  • make docs runs the VitePress docs site.
  • make dags regenerates dependency DAGs from cached snapshots.
  • make dags-fetch regenerates dependency DAGs from GitHub data (requires gh auth + network).

cargo xtask

The repo also exposes maintenance commands via cargo xtask …:

  • cargo xtask dags regenerates dependency DAG DOT/SVG assets.
  • cargo xtask dags --fetch fetches snapshots via gh before generating.
  • cargo xtask dags --snapshot-label none omits snapshot labels (best for CI automation).
  • cargo xtask dags --snapshot-label rolling emits a stable rolling label.
  • cargo xtask dags --snapshot-label 2026-01-02 pins a date label (useful for comparisons).
  • cargo xtask doghouse sortie 308 --intent merge_check emits agent-native JSONL for the selected PR, including sortie intent, CodeRabbit summary-comment state (cooldown, checkbox rearm, or other callout weirdness), actionable checkbox ids/labels when present, baseline selection, comparison trust/quality assessment, semantic delta, and an intent-aware next-action verdict that still keeps human/Codex review state separate.
  • cargo xtask doghouse rearm-coderabbit 308 --yes edits the latest CodeRabbit summary comment when Rabbit has paused itself behind an active-changes checkbox gate.
  • cargo xtask doghouse nudge-coderabbit 308 --yes posts @coderabbitai review or @coderabbitai resume when Doghouse has already determined that Rabbit is actionable again.
  • cargo xtask pr-status summarizes the current PR head, exact unresolved review-thread count, grouped check state, and a concise current-blockers section.
  • cargo xtask pr-status 306 targets an explicit PR number instead of the current branch PR.
  • cargo xtask pr-snapshot records a durable local PR review snapshot under artifacts/pr-review/.
  • cargo xtask pr-snapshot 308 --intent fix_batch targets an explicit PR number and records why the capture was taken.
  • cargo xtask pr-threads list lists unresolved review threads for the current PR with thread ids, comment ids, path, author, URL, and a short preview.
  • cargo xtask pr-threads list 306 targets an explicit PR number instead of the current branch PR.
  • cargo xtask pr-threads reply 123456789 --body-file /tmp/reply.md posts a human-authored reply to a review comment id on the current branch PR.
  • cargo xtask pr-threads reply 123456789 --selector 306 --body-file /tmp/reply.md targets an explicit PR when the review comment belongs to another repo/PR context.
  • cargo xtask pr-threads resolve --all --selector 306 --yes resolves all unresolved review threads for a PR after you have verified the fix batch.
  • cargo xtask pr-threads resolve --yes THREAD_ID_A THREAD_ID_B resolves explicit GitHub review thread ids when you already know the targets.
  • cargo xtask test-slice strand runs the strand contract/live-basis slice with exact Cargo target selection.
  • cargo xtask test-slice settlement runs only warp-core settlement module unit tests via --lib.
  • cargo xtask test-slice observation runs only warp-core observation module unit tests via --lib.
  • cargo xtask test-slice neighborhood runs only warp-core neighborhood module unit tests via --lib.
  • cargo xtask test-slice warp-core-smoke runs the warp-core lib tests plus the strand integration target without launching every integration-test binary.
  • cargo xtask pr-preflight runs the default changed-scope pre-PR gate against origin/main.
  • cargo xtask pr-preflight --full runs the broader explicit full pre-PR gate.
  • cargo xtask dind runs the DIND (Deterministic Ironclad Nightmare Drills) harness locally.

Pre-PR Preflight

Before opening a PR, run:

cargo xtask pr-preflight

What it proves:

  • the changed surface passes the normal local verify-local PR gate
  • changed Markdown docs pass markdownlint, and docs branches also get dead-ref checking
  • runtime schema changes get explicit pnpm schema:runtime:check
  • feature-sensitive crates get explicit --no-default-features checks
  • maintained shell scripts get a syntax pass via bash -n

What it intentionally does not prove:

  • full CI parity for every matrix lane
  • review-thread state or merge readiness on GitHub
  • human/self-review quality

Use cargo xtask pr-preflight --full when you want the broader local proof before a high-risk or cross-cutting PR. make pr-preflight ARGS='--full' remains available as a thin alias.

PR Flight Recorder

When a review cycle starts getting noisy, make Doghouse your first stop before manually spelunking through gh output or the GitHub UI. Capture the current state after opening the PR, after each push, and before or after each fix batch:

cargo xtask pr-snapshot

The recorder writes timestamped JSON + Markdown under artifacts/pr-review/pr-<number>/ and refreshes latest.json / latest.md for the selected PR. When a prior local snapshot exists, the recorder also writes timestamped and latest.delta.* semantic delta artifacts so you can answer "what changed since the last sortie?" without diffing raw JSON by hand. Those artifacts are local-only and gitignored on purpose. They exist to make review-state drift legible: head SHA, grouped checks, unresolved threads, review decision, merge state, current blockers, and the transition between successive snapshots.

For agent-native triage, prefer:

cargo xtask doghouse sortie 308 --intent post_push

That JSONL stream is the plumbing surface. It picks a meaningful baseline, grades comparison trust/quality, reports CodeRabbit pause or cooldown state without eclipsing human/Codex reviewers, and emits the current next-action verdict.

If that next-action verdict is capture_fresh_sortie, trust the recorder: Doghouse is telling you the selected comparison is too stale or noisy to support an affirmative move like nudging Rabbit, requesting review, or concluding merge readiness. Capture another sortie before acting.

If the verdict is nudge_coderabbit, the follow-up command is:

cargo xtask doghouse nudge-coderabbit 308 --yes

If Rabbit paused itself behind summary-comment checkboxes first, Doghouse will steer you to:

cargo xtask doghouse rearm-coderabbit 308 --yes

Use make pr-snapshot ARGS='308' if you prefer a Make alias or need to target an explicit PR number.

Dependency DAG Workflow

Artifacts:

  • DOT + SVG output lives under docs/assets/dags/.
  • The hand-maintained edge list lives in docs/assets/dags/deps-config.json.
  • The generator is scripts/generate-dependency-dags.js (wrapped by cargo xtask dags).
  • The explainer doc is docs/method/dependency-dags.md.

Automation:

  • GitHub Action Refresh Dependency DAGs runs on a schedule and opens a PR only if outputs changed:
    • workflow file: .github/workflows/refresh-dependency-dags.yml
    • uses --snapshot-label none to avoid “date churn” diffs

Issue linkage for automation PRs:

  • If you enforce strict PR↔Issue linkage, create a single tracking issue (example: “Automate dependency DAG refresh”) and set a repository Actions variable:
    • DAG_REFRESH_ISSUE=<issue-number>
  • The workflow will include Refs #<issue-number> in the PR body when DAG_REFRESH_ISSUE is set.

If you add new issues/milestones that should appear in the graph, update docs/assets/dags/deps-config.json (and consider annotating edges with confidence).