Record the three possible v0.1 exits (1.1.2) - #50
Conversation
Record the execution plan for roadmap task 1.1.2, which captures the "ship nothing", "ship conventions only", and "ship macro" outcomes and binds each to concrete evidence in the technical design. The plan proposes ADR 003 as the deliverable, adds a contract test that parses the decision record so the mapping cannot rot away from design.md, and specifies a red-green cycle whose red state is the honest transcription of what the design says today. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
A six-lens design review found substantive errors in the first draft. Correct the gate bindings: bet B2's evidence comes from roadmap task 4.2.1 and its decision from 4.3.1, not from 3.1.3, which only unlocks phase 4. Remove the circularity that had the parser enforce the dominance rule it was meant to check, and replace the dominance justification, which wrongly claimed B2 is undefined when B1 fails. Surface the split case, where exactly one validation example improves, as a combination neither the design nor the terms of reference maps, and raise it as an approval-gate question rather than assuming a resolution. Strengthen the drift guard from heading existence to load-bearing clause matching, add a gate-binding check, and drop insta, proptest, and rstest-bdd, cutting new dev-dependencies from five to two. Remove the deliberately failing milestone, which contradicted AGENTS.md, and add the formatter, audit, and workflow-contract gates the first draft missed. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Reviewer's GuideAdds a detailed ExecPlan document for roadmap task 1.1.2 that specifies how to introduce a v0.1 exit register ADR and a contract test, including constraints, verification strategy, documentation sync, and decision log; this PR only introduces the plan, not the ADR, tests, or code changes themselves. Sequence diagram for v0_1 exit register contract test flowsequenceDiagram
participant Dev as Developer
participant Make as make_test
participant Test as v0_1_exit_register_contract
participant ADR as adr_003_v0_1_exit_register_md
participant Design as design_md
participant Roadmap as roadmap_md
Dev->>Make: make test
Make->>Test: run v0_1_exit_register_contract
Test->>ADR: include_str!("docs/adr-003-v0-1-exit-register.md")
Test->>Design: include_str!("docs/design.md")
Test->>Roadmap: include_str!("docs/roadmap.md")
Test->>Test: parse_register(adr_body)
Test->>Test: check_totality(rows)
Test->>Test: check_dominance(rows)
Test->>Test: check_quoted_clauses(design_body)
Test->>Test: check_gate_bindings(rows, roadmap_body)
Test->>Dev: report pass/fail with repair hints
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
![codescene-access[bot]](https://avatars.githubusercontent.com/in/3755875?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
Warning Your free Security trial is over. An organization admin can activate billing to continue. |
|
Important Draft PR not reviewedDraft PRs are not automatically reviewed by default.
To automatically review draft PRs, update your CodeRabbit configuration: reviews:
auto_review:
drafts: trueWarning Your free Security trial is over. An organization admin can activate billing to continue. Comment |
leynos
changed the title
Define the three mutually exclusive v0.1 release scopes and bind them to the evidence gates that choose them. Guard the decision record against register, quotation, and roadmap drift with a test-only document contract.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Document that completing the required remaining sync exceeds the plan tolerance and requires explicit authorization.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Connect ADR 003 to the design, roadmap, guides, glossary, and repository index so its release gates remain discoverable.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Capture the full delivery gate results and retrospective while the final independent review is pending.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Record the final clean CodeRabbit review and completion evidence for roadmap task 1.1.2.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph. If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message in a code block that I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced. Bumpy Road Aheadtests/v0_1_exit_register_contract/support.rs: check_gate_bindings What lead to degradation?check_gate_bindings has 2 blocks with nested conditional logic. Any nesting of 2 or deeper is considered. Threshold is 2 blocks per function Why does this problem occur?A Bumpy Road is a function that contains multiple chunks of nested conditional logic inside the same function. The deeper the nesting and the more bumps, the lower the code health. How to fix it?Bumpy Road implementations indicate a lack of encapsulation. Check out the detailed description of the Bumpy Road code health issue. |
|
@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph. If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message in a code block that I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced. String Heavy Function Argumentstests/v0_1_exit_register_contract/support.rs: What lead to degradation?In this module, 70.8% of all arguments to its 16 functions are strings. The threshold for string arguments is 39.0% Why does this problem occur?String is a generic type that fail to capture the constraints of the domain object it represents. In this module, 71 % of all function arguments are string types. How to fix it?Heavy string usage indicates a missing domain language. Introduce data types that encapsulate the semantics. For example, a user_name is better represented as a constrained User type rather than a pure string, which could be anything. |
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
file="tests/v0_1_exit_register_contract/support.rs"
printf '%s\n' '--- current HEAD ---'
git rev-parse --short HEAD
printf '%s\n' '--- module outline ---'
ast-grep outline "$file" --items all --view expanded || true
printf '%s\n' '--- function definitions and string-related signatures ---'
rg -n -C 3 '^\s*(pub(?:\([^)]*\))?\s+)?fn\b|&str|String' "$file" || true
printf '%s\n' '--- module references ---'
rg -n -C 2 'v0_1_exit_register_contract::support|mod support|use support|check_[A-Za-z0-9_]+\s*\(' tests || trueLength of output: 11933
File: Suppress this diagnostic. I verified this against current head Do not add newtypes for these arguments. The module is a private test-only Markdown parser. Its Do not extract a Paste this suppression message into CodeScene: This module is private test support for a contract test that parses Markdown documentation loaded through `include_str!`. Its string arguments represent either complete source documents (`adr`, `design`, `terms`, `context`, and `roadmap`) or raw Markdown cells and tokens that the parser must inspect. These values do not form a production domain API.
Adding wrapper types for each borrowed text value would be mechanical. It would not add validation, ownership, or behaviour. It would also not materially reduce the module-wide string-argument ratio because the parser helpers must continue to accept raw text. The module already converts stable exit-register concepts into `Verdict`, `Exit`, and `Row`. Suppress this diagnostic for `tests/v0_1_exit_register_contract/support.rs`.You are interacting with an AI system. |
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
@coderabbitai Please suggest a fix for this issue and supply a prompt for an AI coding agent to enable it to apply the fix. Include the file and symbol names indicated in the issue at the head of your response. Ensure that this is validated against the current version of the codegraph. If further refinement to address this finding would be deleterious, please supply a clear explanatory one to two paragraph markdown message in a code block that I can paste into the CodeScene web ui's diagnostic suppression function so this diagnostic can be silenced. Bumpy Road Aheadtests/v0_1_exit_register_contract/support.rs: check_gate_bindings What lead to degradation?check_gate_bindings has 2 blocks with nested conditional logic. Any nesting of 2 or deeper is considered. Threshold is 2 blocks per function Why does this problem occur?A Bumpy Road is a function that contains multiple chunks of nested conditional logic inside the same function. The deeper the nesting and the more bumps, the lower the code health. How to fix it?Bumpy Road implementations indicate a lack of encapsulation. Check out the detailed description of the Bumpy Road code health issue. |
This comment was marked as resolved.
This comment was marked as resolved.
Split gate-to-roadmap and parsed-row validation into private helpers while preserving error messages and validation order. Add focused controls for a wrong ADR task, a ticked roadmap task, and an unknown row gate.
Capture the maintenance refactor's preserved contract boundary, validation order, focused controls, and completion status in the v0.1 exit ExecPlan.
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
|
@coderabbitai please assess the implementation in this PR for completeness and correctness against the execplan:
|
|
Tip For best results, initiate chat on the files or code changes. 🧩 Analysis chain🏁 Script executed: #!/bin/bash
set -euo pipefail
plan="docs/execplans/1-1-2-record-the-three-possible-v0-1-exits.md"
printf '%s\n' '--- current PR HEAD and base ---'
git rev-parse --short HEAD
git status --short
git branch --show-current
git merge-base HEAD origin/main 2>/dev/null || true
printf '%s\n' '--- changed files against main ---'
git diff --name-status "$(git merge-base HEAD origin/main)" HEAD 2>/dev/null || git diff --name-status HEAD~1 HEAD
printf '%s\n' '--- execution plan outline ---'
ast-grep outline "$plan" --items all --view expanded 2>/dev/null || true
printf '%s\n' '--- execution plan ---'
cat -n "$plan"
printf '%s\n' '--- relevant documentation and test files ---'
fd -t f . docs tests | rg '(adr-003|roadmap|design\.md|terms-of-reference|glossary|guide|index|v0_1_exit_register_contract|Cargo\.toml|Makefile|AGENTS\.md)$' || true
printf '%s\n' '--- Rust test-support outline ---'
ast-grep outline tests/v0_1_exit_register_contract/support.rs --items all --view expanded 2>/dev/null || true
printf '%s\n' '--- contract test files ---'
find tests/v0_1_exit_register_contract -type f -maxdepth 2 -print 2>/dev/null | sort
printf '%s\n' '--- contract test references ---'
rg -n -C 3 'ADR 003|adr-003|G1|G2|G3|B1|B2|include_str!|check_gate_bindings|googletest|pretty_assertions' docs tests Cargo.toml Makefile AGENTS.md 2>/dev/null || true
printf '%s\n' '--- dependency and validation targets ---'
rg -n -C 3 'googletest|pretty_assertions|rstest|insta|proptest|^\[dev-dependencies\]|^(test|check-fmt|markdownlint|nixie):' Cargo.toml Makefile AGENTS.md 2>/dev/null || trueLength of output: 2183 🏁 Script executed: #!/bin/bash
set -u
plan="docs/execplans/1-1-2-record-the-three-possible-v0-1-exits.md"
printf '%s\n' '--- PR metadata and changed files ---'
gh pr view 50 --repo leynos/statelet --json number,headRefOid,baseRefName,baseRefOid,files,commits \
--jq '{number, headRefOid, baseRefName, baseRefOid, files: [.files[].path], commits: [.commits[].oid]}' 2>&1 || true
printf '%s\n' '--- execution plan headings ---'
rg -n '^(#|##|###|####) ' "$plan" 2>&1 || true
printf '%s\n' '--- execution plan ---'
cat -n "$plan" 2>&1 || true
printf '%s\n' '--- relevant files that exist ---'
fd -t f . docs tests 2>/dev/null | rg '(adr-003|roadmap|design\.md|terms-of-reference|glossary|guide|index|v0_1_exit_register_contract)' | sort || true
for file in Cargo.toml Makefile AGENTS.md; do
if [ -f "$file" ]; then printf '%s\n' "$file"; fi
done
printf '%s\n' '--- contract test module outline ---'
ast-grep outline tests/v0_1_exit_register_contract --items all --view expanded 2>&1 || true
printf '%s\n' '--- ADR, roadmap, source requirements, and contract checks ---'
rg -n -C 2 'ADR 003|adr-003|G1|G2|G3|B1|B2|include_str!|check_gate_bindings|googletest|pretty_assertions|ship nothing|ship conventions only|ship macro' \
docs tests Cargo.toml Makefile AGENTS.md 2>/dev/null || true
printf '%s\n' '--- development dependencies and test targets ---'
rg -n -C 3 'googletest|pretty_assertions|rstest|insta|proptest|^\[dev-dependencies\]|^(test|check-fmt|markdownlint|nixie):' \
Cargo.toml Makefile AGENTS.md 2>/dev/null || trueLength of output: 185683 🏁 Script executed: #!/bin/bash
set -u
printf '%s\n' '--- PR patch summary ---'
gh api "repos/leynos/statelet/pulls/50/files?per_page=100" \
--jq '.[] | "\(.filename)\t+\(.additions) -\(.deletions)"' 2>&1 || true
printf '%s\n' '--- integration contract test ---'
cat -n tests/v0_1_exit_register_contract.rs 2>&1 || true
printf '%s\n' '--- support predicates and parser ---'
cat -n tests/v0_1_exit_register_contract/support.rs 2>&1 || true
printf '%s\n' '--- ADR structure and contents ---'
cat -n docs/adr-003-v0-1-exit-register.md 2>&1 || true
printf '%s\n' '--- ADR template structure ---'
rg -n '^(#|##|###) |^Status:|^Date:' docs/documentation-style-guide.md docs/adr-002-transition-boundary-scope.md 2>&1 || true
printf '%s\n' '--- required companion references and link targets ---'
for file in \
docs/contents.md docs/context.md docs/design.md docs/developers-guide.md \
docs/roadmap.md docs/terms-of-reference.md docs/users-guide.md \
docs/repository-layout.md
do
printf '\n%s\n' "--- $file ---"
rg -n -C 2 'adr-003-v0-1-exit-register|ADR 003|1\.1\.2|either validation example' "$file" 2>&1 || true
done
printf '%s\n' '--- source sections and gate tasks ---'
sed -n '390,430p;580,630p' docs/design.md 2>&1 || true
sed -n '220,250p;340,365p' docs/terms-of-reference.md 2>&1 || true
rg -n -C 4 '2\.2\.3\.|3\.1\.3\.|4\.2\.1\.|4\.3\.1\.' docs/roadmap.md 2>&1 || true
printf '%s\n' '--- unintended runtime or regular dependencies ---'
gh api "repos/leynos/statelet/compare/78c30a1ac14802aa91f6783457cbf86630b5418b...660908d26f4d7992536b09f09304f421d0203c1d" \
--jq '{files: [.files[].filename], commits: [.commits[].sha]}' 2>&1 || trueLength of output: 53224 🏁 Script executed: #!/bin/bash
set -u
printf '%s\n' '--- ADR required and conditional sections ---'
sed -n '355,492p' docs/documentation-style-guide.md 2>&1 || true
printf '%s\n' '--- execution-plan requirements for reachability, citations, and gates ---'
sed -n '640,765p;1038,1068p' docs/execplans/1-1-2-record-the-three-possible-v0-1-exits.md 2>&1 || true
printf '%s\n' '--- reachability field usages ---'
rg -n -C 2 '\breachable\b|Reachable' tests/v0_1_exit_register_contract.rs tests/v0_1_exit_register_contract/support.rs 2>&1 || true
printf '%s\n' '--- gate extraction and citation extraction implementations ---'
sed -n '199,243p;245,319p' tests/v0_1_exit_register_contract/support.rs 2>&1 || true
printf '%s\n' '--- static mutation checks: identify no-op contract changes ---'
python3 - <<'PY'
from pathlib import Path
adr = Path("docs/adr-003-v0-1-exit-register.md").read_text()
test = Path("tests/v0_1_exit_register_contract.rs").read_text()
support = Path("tests/v0_1_exit_register_contract/support.rs").read_text()
checks = {
"reachable mutation": adr.replace(
"| Falsified | Held | E1 ship nothing | G2 | no |",
"| Falsified | Held | E1 ship nothing | G2 | yes |",
),
"E3 gate mutation": adr.replace(
"| Held | Held | E3 ship macro | G3 | yes |",
"| Held | Held | E3 ship macro | G1 | yes |",
),
}
for name, mutated in checks.items():
print(f"{name}:")
print(" changes input:", mutated != adr)
print(" Row::reachable read by policy:", "row.reachable" in support or ".reachable" in test)
print(" per-verdict required gate check present:", "row.b1" in support and "row.gate" in support and "G3" in support)
print(" hard-coded GATES gate table remains unchanged:", all(
f'("{gate}", "{task}")' in support
for gate, task in (("G1", "2.2.3"), ("G2", "3.1.3"), ("G3", "4.3.1"))
))
print("citation extraction from ADR:")
print(" citation parser present:", "citation" in support.lower())
print(" CLAUSES is hard-coded:", "const CLAUSES" in support)
print(" ADR non-existent citation control present:", "never existed" in test)
PYLength of output: 22944
Implemented correctly
Required fixes1. Enforce the unreachable-row invariantFile: The parser reads the As a result, changing the ADR row Add a reachability policy check. Require:
Add a negative control that changes the unreachable row to 2. Make
|
1 participant
Summary
Drafts the execution plan for roadmap task 1.1.2, "Record the three possible
v0.1 exits". No implementation is included; the plan awaits approval.
The plan is at
docs/execplans/1-1-2-record-the-three-possible-v0-1-exits.md.What the plan proposes
Deliver
docs/adr-003-v0-1-exit-register.md, recording "ship nothing", "shipconventions only", and "ship macro" as a total, mutually exclusive mapping from
verdicts on bets B1 and B2, and binding each exit to a named roadmap gate.
Guard the mapping with one contract test that reads the record and the upstream
documents through
include_str!, so a design renumbering or a rewrittenquotation breaks
make testin the commit that causes it.Question for the reviewer
The plan opens one question that changes the work, raised under "Open question
for the approval gate".
design.md§11.1 says bet B1 holds only when both validation examples improve,so B1 falls when either fails. But §13.7 and
terms-of-reference.md§7.1both trigger "ship nothing" only when both fail. The split case — one example
improves, the other does not — is unmapped. The plan recommends treating it as
falsifying B1 (resolution R1), which needs a one-sentence amendment to each of
those two documents; the alternative is a fourth outcome, which would change
three roadmap tasks.
A second, smaller call: Decision D7 defers
rstest-bdd,insta, andproptest, cutting new dev-dependencies from five to two.rstest-bdd0.5.0additionally requires the separate
rstest-bdd-macros, an audit-ignore entryfor the unmaintained
proc-macro-error, and adylint.toml. That trims theproject default test stack, so it is flagged rather than assumed.
Review history
A six-lens design review found real errors in the first draft, all corrected in
the second commit: the gate bindings named the wrong roadmap tasks; the
contract test was circular, since the parser enforced the rule it was meant to
check; the dominance justification was unsound; and one milestone committed a
deliberately failing test suite, contrary to
AGENTS.md. Both drafts are keptas separate commits so the revision is reviewable.
Validation
make check-fmt,make markdownlint(including thetyposen-GB Oxfordspelling gate), and
make nixieall pass.make fmtis a no-op on the plan.References
🤖 Generated with Claude Code
Summary by Sourcery
Record the complete evidence-based register of Statelet’s possible v0.1 release scopes and guard it against documentation drift.
New Features:
Bug Fixes:
Enhancements:
Build:
Documentation:
Tests:
Chores: