Reconcile roadmap 4.2.3 with ExecPlan completion evidence (#738)

[leynos]

Closes #738

Summary

Reconciles the completion state of roadmap item 4.2.3 with its ExecPlan.

The issue's premise was inverted. It recorded the ExecPlan as
Status: IN PROGRESS, but Revision 2.27 had already moved the header to
COMPLETE (commit d30b33eb, PR #586), and PR #564 had flipped the roadmap
checkbox to [x] in 6c646f1c, the same commit that delivered the work.
Rather than re-litigate the header, every acceptance criterion was re-derived
from fresh evidence.

Acceptance criteria

Criterion	Result
Capped full make kani-ir	Met — 15/15 harnesses, 0 failures, all covers satisfied, 5m03s incl. cold compile
Mutation evidence	Met after repair — all five patches re-verified against named checks
Deterministic + documentation gates	Met — 7 gates green
Trace links	Met — all five resolve to live definitions
Review	Met — coderabbit review --agent returned zero findings

The full-suite requirement is discharged: Revision 2.24's exit 124 was a
five-minute cap under sequential scheduling, not a working-tree defect. The
supported --jobs 4 --output-format terse pair clears it.

Verdict: every criterion passes, so the header stays COMPLETE and
docs/roadmap.md needs no correction. Its claims are now verified true
rather than assumed.

A defect found and fixed along the way

-D warnings entered the make kani-full recipe on 2026-09-18 (#714). Two of
this plan's five mutation patches seed their fault by leaving a binding unused —
a warning when written, a hard compile error after that date. The patched tree
failed to build, so the patches yielded zero mutation evidence while still
passing the contract test: every_patch_applies_cleanly runs
git apply --check, which proves a patch applies, not that the patched tree
compiles.

Both were regenerated so they still seed the same production fault and still
compile, then re-verified end to end (named failure with the patch, success
after restoration):

• marker_token_match_is_exact → marker match agrees with exact text
• scanner_agrees_with_independent_specification → template = "__NETSUKE_OUTS_PLACEHOLDER__", ins = "", outs = "a"

Raised, not fixed

Three further patches are broken by the identical mechanism and belong to
roadmap 4.2.1 and 4.2.2. They are recorded in the ExecPlan rather than fixed
here, per this plan's own OBL-PATCHES instruction to escalate rather than
silently absorb a neighbouring roadmap's work. The cheapest systemic fix —
widening the contract test to cargo check each patched tree under
-D warnings — is a repository-wide change, so it is filed separately as
#756, which carries the exact compiler errors for all three patches reproduced
against a clean tree.

Files changed

• docs/execplans/4-2-3-kani-harnesses-for-command-interpolation.md — new
  Reconciliation against acceptance criteria section, Progress and Revision
  note entries, and a corrected stale header revision pointer (2.26 → 2.28).
• docs/verification/mutations/ir__cmd_interpolate__verification__marker_token_match_is_exact.patch
• docs/verification/mutations/ir__cmd_interpolate__property_tests__scanner_agrees_with_independent_specification.patch

Test plan

• Capped make kani-ir (15/15, 0 failures, covers satisfied)
• Each of the five mutation patches fails its named check, then passes on restore
• make check-fmt, make lint, make test, make typecheck
• make doc-coverage (98.80%), make markdownlint, make nixie
• coderabbit review --agent — zero findings

References

• Issue: Reconcile roadmap 4.2.3 with ExecPlan completion evidence #738
• Follow-up filed: Mutation patches can apply cleanly and still not compile under -D warnings #756
• Lody session: https://lody.ai/leynos/sessions/8f88c9e6-2619-4f7b-a150-363c2f486795
• Backlink: Document the command placeholder contract in the README (4.4.1) #699 (comment)

🤖 Generated with Claude Code

Summary by Sourcery

Reconcile roadmap item 4.2.3 with fresh completion evidence and restore valid mutation verification without changing its COMPLETE status.

Bug Fixes:

• Repair two command-interpolation mutation patches so they compile under the warnings-as-errors configuration and provide valid mutation evidence.

Enhancements:

• Reconcile roadmap 4.2.3 completion status against fresh full-suite, mutation, documentation, traceability, and review evidence while documenting related issues in neighbouring roadmap items.

Documentation:

• Document the acceptance-criteria reconciliation, verified completion evidence, revision history, and escalated mutation-patch issues in the command-interpolation ExecPlan.

Tests:

• Re-verify all five command-interpolation mutation patches and confirm the full Kani harness suite and repository quality gates pass.

[coderabbitai]

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

• Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true

---

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

[sourcery-ai]

Reviewer's Guide

This PR verifies that roadmap 4.2.3 was already correctly marked COMPLETE by re-running every acceptance criterion, repairs two mutation patches invalidated by the repository’s -D warnings change, and documents three analogous issues in neighboring roadmap items as raised rather than fixed.

Sequence diagram for mutation patch repair and verification

sequenceDiagram
    participant Maintainer
    participant MutationPatches
    participant Build
    participant NamedChecks

    Maintainer->>MutationPatches: Regenerate two mutation patches
    Maintainer->>Build: Apply patch and compile under -D warnings
    Build-->>Maintainer: Patched tree compiles
    Maintainer->>NamedChecks: Run marker_token_match_is_exact
    NamedChecks-->>Maintainer: Named check fails
    Maintainer->>NamedChecks: Run scanner_agrees_with_independent_specification
    NamedChecks-->>Maintainer: Named check fails
    Maintainer->>MutationPatches: Restore production code
    Maintainer->>NamedChecks: Re-run named checks
    NamedChecks-->>Maintainer: Checks pass

Loading

Flow diagram for roadmap 4.2.3 reconciliation and completion verdict

flowchart TD
    A[Re-run acceptance criteria] --> B{All criteria pass?}
    B -->|Yes| C[Keep ExecPlan COMPLETE]
    C --> D[Keep roadmap checkbox checked]
    B -->|No| E[Investigate completion state]

Loading

File-Level Changes

Change	Details	Files
Reconciles the ExecPlan’s completion status against fresh execution, mutation, quality-gate, traceability, and review evidence without changing the roadmap completion state.	Adds a criterion-by-criterion reconciliation covering the capped 15-harness Kani run, five mutation checks, seven repository gates, trace links, and CodeRabbit review. Documents that the prior timeout was scheduling-related and that the supported parallel Kani invocation completes within tolerance. Records the unchanged COMPLETE header and roadmap checkbox, plus the decision to raise neighboring broken patches rather than fix them here. Updates progress and revision history with the reconciliation outcome and evidence references.	docs/execplans/4-2-3-kani-harnesses-for-command-interpolation.md
Repairs two mutation patches that stopped compiling after warnings became hard errors, restoring meaningful mutation evidence.	Regenerates the marker-token mutation while preserving its intended named failure. Regenerates the scanner-specification mutation while preserving its intended counterexample. Re-verifies both patches end to end, including failure with the mutation and success after restoration.	docs/verification/mutations/ir__cmd_interpolate__verification__marker_token_match_is_exact.patch docs/verification/mutations/ir__cmd_interpolate__property_tests__scanner_agrees_with_independent_specification.patch

Assessment against linked issues

Issue	Objective	Addressed	Explanation
#738	Reassess and document the status of every acceptance criterion in the ExecPlan, including full Kani-suite, mutation, deterministic/documentation, trace-link, and review evidence.	✅
#738	Obtain current reproducible evidence for the previously incomplete capped full make kani-ir requirement and any other outstanding criteria.	✅
#738	Reconcile the roadmap and ExecPlan completion states, setting the ExecPlan to COMPLETE only if all criteria pass, and otherwise correcting the roadmap; record the resulting assessment in the ExecPlan.	✅

Possibly linked issues

• Reconcile roadmap 4.2.3 with ExecPlan completion evidence #738: The PR directly fulfills issue Reconcile roadmap 4.2.3 with ExecPlan completion evidence #738 by reassessing criteria, documenting evidence, and confirming synchronized COMPLETE status.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.