Document the command placeholder contract in the README (4.4.1)

[leynos]

Plans roadmap item 4.4.1, which adds a "Security and command interpolation" section to the README and settles the three contract questions that docs/formal-verification-methods-in-netsuke.md §Command placeholder contract leaves open.

No implementation yet — this PR is the plan, and it needs approval before anything is built.

ExecPlan: docs/execplans/4-4-1-document-command-placeholder-contract-in-readme.md

What the ground truth turned out to be

The contract was established by reading src/ir/cmd_interpolate/ rather than by
trusting the existing prose, and three findings shaped the plan:

• $in and $out are rewritten in script: recipes, though not in
  command: recipes (find_script_substitution,
  src/ir/cmd_interpolate/mod.rs:269-297). Three documents state the opposite
  without qualification.
• The backtick guard is a whole-string odd-parity count
  (has_unmatched_backticks, src/ir/cmd_interpolate/mod.rs:172-174), not a
  quoting-aware model. It does not defend against author-written command
  substitution: a balanced pair reaches the shell and executes.
• shlex::split gates POSIX and Bash command: recipes only — never
  script: recipes, never PowerShell — and is never used to build an argv.

The three decisions

• D1 — {{ ins }}/{{ outs }} in both recipe kinds; $in/$out in
  script: only, documented as retained legacy with a shadowing warning
  rather than as a blessed feature.
• D2 — the marker invariant is promised; the backtick parity check is
  documented as a conservative check that a future release may widen without
  that being a breaking change; author-written backticks carry no guarantee at
  all.
• D3 — the shlex rejection is contractual; the precise accepted set is
  not, because Cargo.toml:138 is a caret requirement rather than a pin. Both
  drift directions are named, and the README states that passing the gate does
  not make a command safe.

Why this is not a documentation-only change

tests/documentation_examples/ requires a <!-- tested-example: ... --> marker
on every README fence and compares identifiers for exact set equality. Adding
the section is therefore a test change too, which gives the item a genuine
red-green cycle. Five verification obligations make each documented claim
falsifiable, with three negative controls including a seeded mutation from
docs/verification/mutations/.

Scope

Five milestones: ADR-021 recording the decisions; correction of the three
inaccurate documents (deliberately before the README, so the repository is
never in a state where two normative documents disagree); the README section
with three executable examples; the six translated READMEs, preserving their
current section-for-section parity; and the roadmap closure.

Review

A six-lens community-of-experts design review ran against revision 1 and found
four factual errors in the plan plus two obligations that should have existed
and did not — notably that the plan's own headline finding had no test behind
it, and that the section's only positive security promise was unasserted.
Revision 2 folds all of it in; the Revision note and Surprises & discoveries
sections record what changed and why.

One decision, D1-LEGACY, is flagged as awaiting the owner's confirmation: the
evidence is genuinely ambiguous about whether the script:-only $in/$out
forms are intended or vestigial. The plan is written so that either answer
leaves the documentation honest.

References

• Lody session: https://lody.ai/leynos/sessions/a52242fa-b09a-4ab9-8c9e-687ca8533644

🤖 Generated with Claude Code

Summary by Sourcery

Establish and document the implemented command placeholder and shell-validation contract ahead of the planned README publication.

Bug Fixes:

• Correct inaccurate documentation about command placeholder interpolation, including the script-only legacy $in and $out forms and route-specific validation behavior.

Enhancements:

• Record the command placeholder, backtick-handling, and shlex acceptance contract in ADR-027 and link it from the relevant design and documentation indexes.
• Clarify the distinctions between guaranteed marker protection, conservative backtick parity checking, author-written shell command substitution, and the limited scope of the shlex guard.
• Update user, developer, and formal-verification documentation to reflect the implemented interpolation contract and its limitations.
• Add and document an execution plan for publishing the contract in the README and translated README editions.

Documentation:

• Add ADR-027 defining the command placeholder contract and its compatibility implications.
• Update the users' guide, developers' guide, formal-verification methods, and design documentation to align with the implementation.

Chores:

• Correct the command interpolation module documentation and stale source reference.

[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 planning-only PR introduces a revision-2 ExecPlan for roadmap item 4.4.1, specifying how the command interpolation contract will be documented, tested through executable README examples and negative controls, propagated across documentation and translations, and recorded in ADR-021; no implementation changes are included.

Flow diagram for planned command placeholder handling

flowchart TD
    Recipe{Recipe kind}
    Recipe -->|command| Command[Rewrite ins and outs]
    Recipe -->|script| Script[Rewrite ins outs and legacy dollar aliases]
    Command --> Guard[POSIX or Bash validation gates]
    Script --> ScriptResult[Generate script text]
    Guard -->|accepted| CommandResult[Generate command text]
    Guard -->|rejected| Invalid[Invalid command interpolation]
    CommandResult --> Quoted[Own path substitutions are shell-quoted]
    ScriptResult --> Quoted

Loading

Flow diagram for planned documentation and verification milestones

flowchart LR
    Decisions[ADR-021 decisions D1 D2 D3] --> Corrections[Correct internal documentation]
    Corrections --> README[README contract and examples]
    README --> Tests[Executable examples and negative controls]
    README --> Translations[Six translated READMEs]
    Tests --> Gates[Validation gates]
    Translations --> Parity[README structural parity]
    Gates --> Closure[Close roadmap item 4.4.1]
    Parity --> Closure

Loading

File-Level Changes

Change	Details	Files
Adds a detailed execution plan for documenting and formalising the command placeholder contract without changing production behaviour.	Defines decisions for placeholder rewriting, backtick handling, and the shlex rejection gate. Records implementation facts, constraints, risks, milestones, recovery procedures, and review history. Requires an ADR, corrections to conflicting documentation, README content, translations, and roadmap closure.	docs/execplans/4-4-1-document-command-placeholder-contract-in-readme.md

---

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.

[codescene-access]

No quality gates enabled for this code.

[leynos]

@coderabbitai please create a new GitHub issue for the following:

$in and $out should not be emitted as ninja input and output markers. If present in scripts, they should be escaped as shell variables.

Term of art — "marker". In this plan, marker means a Netsuke-owned placeholder that Netsuke rewrites: {{ ins }}, {{ outs }}, and (in scripts only) $in and $out. Internal token means the INS_TOKEN /OUTS_TOKEN sentinel strings that exist only between stages 1 and 2. Shell variable means text such as $PATH or $ins that Netsuke deliberately leaves alone. These three are distinct and the existing documentation conflates them; not conflating them is a goal of this plan.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

repo="leynos/netsuke"
pr_number="699"
needle='$in and $out should not be emitted as ninja input and output markers'

comment_url="$(
  {
    gh api "repos/${repo}/issues/${pr_number}/comments" --paginate
    gh api "repos/${repo}/pulls/${pr_number}/comments" --paginate
  } | jq -r --arg needle "$needle" '
    select((.body // "") | contains($needle)) | .html_url
  ' | head -n1
)"

if [ -z "$comment_url" ]; then
  echo "Could not find the originating comment URL." >&2
  exit 1
fi

body_file="$(mktemp)"
trap 'rm -f "$body_file"' EXIT

cat >"$body_file" <<EOF
## Summary

Prevent \`$in\` and \`$out\` from becoming Ninja input and output markers.

When these forms occur in \`script:\` recipes, escape them as shell variables. Preserve the distinction between Netsuke-owned markers, internal tokens, and shell variables.

## Rationale

The current documentation conflates three distinct concepts:

- **Marker**: a Netsuke-owned placeholder that Netsuke rewrites: \`{{ ins }}\`, \`{{ outs }}\`, and, in scripts only, \`$in\` and \`$out\`.
- **Internal token**: the \`INS_TOKEN\` or \`OUTS_TOKEN\` sentinel used only between interpolation stages.
- **Shell variable**: text such as \`$PATH\` or \`$ins\` that Netsuke intentionally leaves unchanged.

Do not emit shell-variable forms as Ninja markers.

## Affected areas

- Command interpolation for \`script:\` recipes.
- Ninja marker generation and escaping.
- Documentation that describes markers, internal tokens, and shell variables.
- Regression tests for script interpolation and generated Ninja output.

## Acceptance criteria

- \`$in\` and \`$out\` do not appear as Ninja input or output markers in generated output.
- In \`script:\` recipes, \`$in\` and \`$out\` are escaped as shell variables.
- \`{{ ins }}\` and \`{{ outs }}\` retain their documented Netsuke marker behaviour.
- Tests distinguish markers, internal tokens, and shell variables.
- Documentation uses the defined terms consistently.

Requested by `@leynos`.

Backlinks: [PR `#699`](https://github.com/leynos/netsuke/pull/699) · [originating comment](${comment_url})
EOF

gh issue create \
  --repo "$repo" \
  --title 'Escape `$in` and `$out` as shell variables in scripts' \
  --body-file "$body_file" \
  --assignee leynos

Length of output: 2717

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

repo="leynos/netsuke"
pr_number="699"
needle='$in and $out should not be emitted as ninja input and output markers'

comment_url="$(
  {
    gh api "repos/${repo}/issues/${pr_number}/comments" --paginate
    gh api "repos/${repo}/pulls/${pr_number}/comments" --paginate
  } | jq -r --arg needle "$needle" '
    .[] | select((.body // "") | contains($needle)) | .html_url
  ' | head -n1
)"

if [ -z "$comment_url" ]; then
  echo "Could not find the originating comment URL." >&2
  exit 1
fi

body_file="$(mktemp)"
trap 'rm -f "$body_file"' EXIT

cat >"$body_file" <<'EOF'
## Summary

Prevent `$in` and `$out` from becoming Ninja input and output markers.

When these forms occur in `script:` recipes, escape them as shell variables. Preserve the distinction between Netsuke-owned markers, internal tokens, and shell variables.

## Rationale

The current documentation conflates three distinct concepts:

- **Marker**: a Netsuke-owned placeholder that Netsuke rewrites: `{{ ins }}`, `{{ outs }}`, and, in scripts only, `$in` and `$out`.
- **Internal token**: the `INS_TOKEN` or `OUTS_TOKEN` sentinel used only between interpolation stages.
- **Shell variable**: text such as `$PATH` or `$ins` that Netsuke intentionally leaves unchanged.

Do not emit shell-variable forms as Ninja markers.

## Affected areas

- Command interpolation for `script:` recipes.
- Ninja marker generation and escaping.
- Documentation that describes markers, internal tokens, and shell variables.
- Regression tests for script interpolation and generated Ninja output.

## Acceptance criteria

- `$in` and `$out` do not appear as Ninja input or output markers in generated output.
- In `script:` recipes, `$in` and `$out` are escaped as shell variables.
- `{{ ins }}` and `{{ outs }}` retain their documented Netsuke marker behaviour.
- Tests distinguish markers, internal tokens, and shell variables.
- Documentation uses the defined terms consistently.

Requested by `@leynos`.

Backlinks: [PR `#699`](https://github.com/leynos/netsuke/pull/699) · [originating comment](COMMENT_URL)
EOF

sed -i "s|COMMENT_URL|${comment_url}|g" "$body_file"

gh issue create \
  --repo "$repo" \
  --title 'Escape `$in` and `$out` as shell variables in scripts' \
  --body-file "$body_file" \
  --assignee leynos

Length of output: 2654

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

repo="leynos/netsuke"
pr_number="699"

echo "Issue comments:"
gh api "repos/${repo}/issues/${pr_number}/comments" --paginate \
  --jq '.[] | [.html_url, .user.login, (.body | gsub("[\r\n]+"; " ") | .[0:180])] | `@tsv`' || true

echo "Review comments:"
gh api "repos/${repo}/pulls/${pr_number}/comments" --paginate \
  --jq '.[] | [.html_url, .user.login, (.body | gsub("[\r\n]+"; " ") | .[0:180])] | `@tsv`' || true

echo "Reviews:"
gh api "repos/${repo}/pulls/${pr_number}/reviews" --paginate \
  --jq '.[] | [.html_url, .user.login, (.body | gsub("[\r\n]+"; " ") | .[0:180])] | `@tsv`' || true

Length of output: 1946

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

body_file="$(mktemp)"
trap 'rm -f "$body_file"' EXIT

cat >"$body_file" <<'EOF'
## Summary

Prevent `$in` and `$out` from becoming Ninja input and output markers.

When `$in` or `$out` occurs in a `script:` recipe, escape it as a shell variable. Keep the three concepts below distinct in implementation, tests, and documentation.

## Definitions

- **Marker**: A Netsuke-owned placeholder that Netsuke rewrites: `{{ ins }}`, `{{ outs }}`, and, in scripts only, `$in` and `$out`.
- **Internal token**: The `INS_TOKEN` or `OUTS_TOKEN` sentinel that exists only between interpolation stages 1 and 2.
- **Shell variable**: Text such as `$PATH` or `$ins` that Netsuke deliberately leaves unchanged.

## Rationale

The existing documentation conflates markers, internal tokens, and shell variables. This change prevents `$in` and `$out` from being emitted as Ninja markers while preserving the documented placeholder contract.

## Affected areas

- Command interpolation for `script:` recipes.
- Ninja marker generation and escaping.
- Documentation that defines markers, internal tokens, and shell variables.
- Regression tests for script interpolation and generated Ninja output.

## Acceptance criteria

- `$in` and `$out` do not appear as Ninja input or output markers in generated output.
- In `script:` recipes, `$in` and `$out` are escaped as shell variables.
- `{{ ins }}` and `{{ outs }}` retain their documented Netsuke marker behaviour.
- Tests distinguish markers, internal tokens, and shell variables.
- Documentation uses the defined terms consistently.

Requested by `@leynos`.

Backlinks: [PR `#699`](https://github.com/leynos/netsuke/pull/699) · [originating comment](https://github.com/leynos/netsuke/pull/699#issuecomment-5737451901)
EOF

gh issue create \
  --repo leynos/netsuke \
  --title 'Escape `$in` and `$out` as shell variables in scripts' \
  --body-file "$body_file" \
  --assignee leynos

Length of output: 2125

---

@leynos Created issue #737 and assigned it to you. The issue links to PR #699 and the originating comment.

---

✏️ Learnings added

Learnt from: leynos
URL: https://github.com/leynos/netsuke/pull/699

Timestamp: 2026-09-18T23:34:39.858Z
Learning: In `leynos/netsuke`, distinguish these terms in command interpolation implementation, tests, and documentation: a marker is a Netsuke-owned placeholder that Netsuke rewrites (`{{ ins }}`, `{{ outs }}`, and in `script:` recipes `$in` and `$out`); an internal token is the `INS_TOKEN` or `OUTS_TOKEN` sentinel that exists only between interpolation stages; a shell variable is text such as `$PATH` or `$ins` that Netsuke deliberately leaves unchanged. Do not conflate these terms.

Note: Learnings are effective only in the context of similar code segments. To apply general coding guidelines, please configure review instructions. You can manage existing learnings in the app.

You are interacting with an AI system.

[leynos]

@coderabbitai please create a new GitHub issue for the following:

roadmap 4.2.3 is marked complete but its execplan header says IN PROGRESS. docs/roadmap.md:490-504 checks all six sub-items; docs/execplans/4-2-3-kani-harnesses-for-command-interpolation.md:8 reads Status: IN PROGRESS.

Assess the completion status of the execplan and update it to COMPLETE if all acceptance criteria are met.

[coderabbitai]

Tip

For best results, initiate chat on the files or code changes.

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
set -euo pipefail

echo '== Roadmap item 4.2.3 =='
sed -n '480,510p' docs/roadmap.md

echo '== ExecPlan outline =='
ast-grep outline docs/execplans/4-2-3-kani-harnesses-for-command-interpolation.md --items all || true

echo '== ExecPlan content =='
cat -n docs/execplans/4-2-3-kani-harnesses-for-command-interpolation.md

echo '== Matching Kani and command interpolation artefacts =='
fd -HI . . | rg '(^|/)(kani|cmd_interpolate|command_interpolation)' | head -n 200

echo '== Originating comment =='
gh api 'repos/leynos/netsuke/issues/699/comments?per_page=100' --paginate \
  --jq '.[] | select(.user.login == "leynos" and (.body | contains("roadmap 4.2.3 is marked complete"))) | .html_url' | head -n 1

Length of output: 128196

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

repo="leynos/netsuke"
query='repo:leynos/netsuke is:issue is:open ("4.2.3" OR "command interpolation") ("IN PROGRESS" OR "Status")'

gh issue list \
  --repo "$repo" \
  --state open \
  --search "$query" \
  --json number,title,url,body \
  --jq '.[] | {number, title, url, body}'

Length of output: 453

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail

body_file="$(mktemp)"
trap 'rm -f "$body_file"' EXIT

cat >"$body_file" <<'EOF'
## Summary

Reconcile the completion state of roadmap item 4.2.3 with its ExecPlan status.

`docs/roadmap.md` marks item 4.2.3 and its sub-items complete. `docs/execplans/4-2-3-kani-harnesses-for-command-interpolation.md` currently states `Status: IN PROGRESS`.

## Assessment

Do not change the ExecPlan status to `COMPLETE` from the currently recorded evidence.

The ExecPlan acceptance criteria require a successful capped full `make kani-ir` run, passing deterministic and documentation gates, resolved trace links, and final reconciliation before the status changes to `COMPLETE`.

Revision 2.24 records that the documented `LD_LIBRARY_PATH`-capped full Kani run exited with code 124 before the full suite completed. Revision 2.26 records successful focused YAML, format, and lint validation, but retains `Status: IN PROGRESS`.

## Required work

1. Reassess each acceptance criterion in `docs/execplans/4-2-3-kani-harnesses-for-command-interpolation.md`.
2. Run or obtain valid current evidence for the outstanding full Kani-suite requirement.
3. Confirm the remaining required deterministic, documentation, mutation, trace-link, and review evidence.
4. If every acceptance criterion passes, change the ExecPlan header to `Status: COMPLETE`.
5. If any criterion remains unmet, retain `Status: IN PROGRESS` and correct `docs/roadmap.md` so that it does not claim completion without the required evidence.
6. Record the assessment and evidence in the ExecPlan.

## Affected files

- `docs/roadmap.md`
- `docs/execplans/4-2-3-kani-harnesses-for-command-interpolation.md`
- Kani validation and related verification artefacts, as required by the ExecPlan

## Acceptance criteria

- The issue documents the status of every ExecPlan acceptance criterion.
- The full Kani-suite requirement has current, reproducible evidence.
- The roadmap and ExecPlan report the same completion state.
- Set `Status: COMPLETE` only after all ExecPlan acceptance criteria pass.

Requested by `@leynos`.

Backlinks: [PR `#699`](https://github.com/leynos/netsuke/pull/699) · [originating comment](https://github.com/leynos/netsuke/pull/699#issuecomment-5737476040)
EOF

gh issue create \
  --repo leynos/netsuke \
  --title 'Reconcile roadmap 4.2.3 with ExecPlan completion evidence' \
  --body-file "$body_file" \
  --assignee leynos

Length of output: 2609

---

@leynos: Created and assigned issue #738.

The issue records that the ExecPlan must remain IN PROGRESS until the full capped Kani-suite requirement and all other acceptance criteria have current evidence. It requires reconciliation of the roadmap and ExecPlan status.

You are interacting with an AI system.