docs: optional trackers and checkpoint vs merge-ready (RM-1712)

Closed
RM
13d ago
+297-126

User description

Summary

Removes mandatory Beads/Dolt setup, GitHub issue twins, native-task-list bans, and duplicate metadata/audit handoff gates from contribution guidance. Linear stays the maintainers’ internal backlog; a GitHub PR is enough to contribute.

Checkpoint commits/pushes/draft PRs are allowed with truthful focused-check status. Merge/release readiness still needs risk-matched review and integrated native gates. Discussion/intent/help messages do not invent a SHA.

Checked-in Claude SessionStart/PreCompact hooks call scripts/optional-bd-prime.sh, which no-ops when bd is missing. writ install still preserves unrelated existing hooks.

Preserves RM-125 / #183 Class A/B/C classifier guidance in SKILL.md and REVIEW.md (shared-file ownership only). Does not take ci_taxonomy runtime, docs/ci-taxonomy.md, or writ ci classify. Until that command exists, agents classify from the inline table.

Review follow-up on this head:

  • Issue-form Linear fields use placeholder, not a submitted value.
  • Authoritative policy says do not create GitHub issue twins.
  • Both the commit workflow and the PR workflow allow task omitted or none. Scope then comes from the assigned request, and no tracker comment is required.
  • Stage 7 reports to the supplied tracker when one exists.
  • Checkpoint publication does not wait for independent review. A merge-ready claim names fmt, clippy, and workspace tests with results.
  • The missing-bd test does not search system PATH.

Task

Linear: RM-1712

No GitHub issue twin.

Status

Head 7058706ac5af10cbfecee1feb08b35cd185e0e3f.

Local gates passed on 3b1542fa7c4788c6e0680952c892b99a6f6b3a78: cargo fmt --all -- --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace. The follow-up commit is docs-only and did not re-run that suite.

GitHub CI for this SHA is not reported yet. Not a merge-ready claim. Not merged.

Scope

Guidance and optional setup only. Does not change lease/coord schema, CI required checks, #203 (remains draft), or #183 taxonomy implementation.

Linear Issue: RM-1712

Open in Web Open in Cursor 

Devin Review

Summary by cubic

Makes Beads/Dolt setup, GitHub issue twins, and full-suite checkpoint gates optional in contribution guidance. Linear remains the maintainers' backlog; a GitHub PR is now enough to contribute, and checkpoint commits/pushes/draft PRs may proceed with honest test status instead of a full-suite run.

  • Session-start hooks call scripts/optional-bd-prime.sh, which no-ops when bd is missing; new tests isolate the script from a system-installed bd. writ install continues preserving unrelated existing hooks.
  • Docs now distinguish checkpoint/draft status from merge-ready claims, which still require risk-matched review and the integrated native gates. The commit/PR workflows accept a task of none or omitted, take scope from the assigned request, and skip the tracker comment when no tracker exists. The Linear footer in issue templates stays blank unless an RM-* task already exists, and inventing a GitHub twin is forbidden.
  • SKILL.md/REVIEW.md keep the inline CI Class A/B/C guidance: skipping is not a pass, ACTION_REQUIRED is not a merge gate, and no empty retrigger commits. The writ ci classify command belongs to RM-125, not this branch.

CodeAnt-AI Description

Make contribution tracking optional and allow honest checkpoint PRs without treating them as merge-ready

What Changed

  • Contributors can submit a GitHub PR without Linear, Beads, or a GitHub issue twin; maintainer task links are optional.
  • Checkpoint commits, pushes, and draft PRs may proceed with focused checks and clearly reported residuals, while merge-ready claims still require integrated validation and risk-matched review.
  • Claude session hooks now continue successfully when Beads is unavailable, invoke it when installed, and preserve unrelated existing hooks.
  • Added tests covering missing Beads, successful Beads execution, propagated failures, and preservation of existing hooks.

Impact

✅ No tracker setup required for external contributions
✅ Draft PRs can be published with honest focused-check status
✅ Claude sessions no longer fail when Beads is not installed

💡 Usage Guide

Checking Your Pull Request

Every time you make a pull request, our system automatically looks through it. We check for security issues, mistakes in how you're setting up your infrastructure, and common code problems. We do this to make sure your changes are solid and won't cause any trouble later.

Talking to CodeAnt AI

Got a question or need a hand with something in your pull request? You can easily get in touch with CodeAnt AI right here. Just type the following in a comment on your pull request, and replace "Your question here" with whatever you want to ask:

@codeant-ai ask: Your question here

This lets you have a chat with CodeAnt AI about your pull request, making it easier to understand and improve your code.

Example

@codeant-ai ask: Can you suggest a safer alternative to storing this secret?

Preserve Org Learnings with CodeAnt

You can record team preferences so CodeAnt AI applies them in future reviews. Reply directly to the specific CodeAnt AI suggestion (in the same thread) and replace "Your feedback here" with your input:

@codeant-ai: Your feedback here

This helps CodeAnt AI learn and adapt to your team's coding style and standards.

Example

@codeant-ai: Do not flag unused imports.

Retrigger review

Ask CodeAnt AI to review the PR again, by typing:

@codeant-ai: review

Check Your Repository Health

To analyze the health of your code repository, visit our dashboard at https://app.codeant.ai. This tool helps you identify potential issues and areas for improvement in your codebase, ensuring your repository maintains high standards of code health.