Document expand_foreach in developers-guide; add ADR for actions foreach/when; clarify roadmap 3.14 disposition #299

Activity

1. leynos commented on May 31, 2026

   

   leynos

   on May 31, 2026

   Owner

   More actions

   @coderabbitai looking at the codebase, is this issue still relevant? If the issue has been fixed in the code, does the documentation reflect this?

   If it is still relevant, please provide an assessment of the issue criticality (critical, high, medium or low), based on risk of the issue impacting the user and the anticipated blast radius.\n\nOnce a decision has been made, apply the appropriate label.

   If the issue is documentation ONLY (i.e., no code changes needed), apply the documentation label in addition to the appropriate criticality label.

   Please also provide an impact of the required changes.

   👀React with 👀1Reacted by coderabbitai
2. coderabbitai commented on May 31, 2026

   

   coderabbitaiBot

   on May 31, 2026 – with coderabbitai

   ContributorAuthor

   More actions

   All three documentation items have been addressed in the codebase:

   1. expand_foreach in the developers guide – docs/developers-guide.md contains both a high-level pipeline walkthrough under Manifest foreach expansion and a full API reference under expand_foreach, covering purpose, inputs, behaviour, error conditions, and cross-references to netsuke-design.md §2.5 and roadmap task 3.14.2.

   2. ADR for actions foreach/when scope – docs/adr-003-actions-foreach-when-scope.md (accepted 2026-05-08) records the decision to keep foreach and when scoped to manifest targets only. It documents the rationale, the alternatives rejected, and the consequences (validators must reject action-level control keys with an error).

   3. Roadmap 3.14 disposition – Section 3.14 Conditional action planning is fully present in docs/roadmap.md with tasks 3.14.1–3.14.11. The Historical task traceability preamble explains which tasks were completed (3.14.1–3.14.3) and which remain active (3.14.4–3.14.11), with a specific note on 3.14.2 and 3.14.4.

   No further changes are required. Closing as resolved.

   Note: docs/adr-003-actions-foreach-when-scope.md and docs/adr-003-agent-consistent-human-first-cli.md share the same ADR number prefix. This numbering conflict is outside the scope of this issue but may warrant a follow-up renaming.
3. coderabbitai

   closed this as completedon May 31, 2026
4. coderabbitai commented on May 31, 2026

   

   coderabbitaiBot

   on May 31, 2026 – with coderabbitai

   ContributorAuthor

   More actions

   🧩 Analysis chain

   🏁 Script executed:

   #!/bin/bash
   # Fetch issue details
   gh issue view 299 --repo leynos/netsuke --json title,body,labels,state,comments
   
   echo "---AVAILABLE LABELS---"
   gh label list --repo leynos/netsuke

   Length of output: 3342

   ---

   🏁 Script executed:

   #!/bin/bash
   echo "=== Check expand_foreach in expand.rs ==="
   fd "expand.rs" --exec cat {}
   
   echo ""
   echo "=== Check developers-guide.md for expand_foreach ==="
   fd "developers-guide.md" --exec grep -n "expand_foreach\|foreach\|when" {}
   
   echo ""
   echo "=== List docs/ directory ==="
   fd . docs/ --max-depth 1
   
   echo ""
   echo "=== Check roadmap.md for section 3.14 ==="
   fd "roadmap.md" --exec cat {}
   
   echo ""
   echo "=== List ADR files ==="
   fd "adr" --type f

   Length of output: 44503

   ---

   🏁 Script executed:

   #!/bin/bash
   echo "=== ADR-003-actions-foreach-when-scope.md ==="
   cat docs/adr-003-actions-foreach-when-scope.md
   
   echo ""
   echo "=== ADR-003-agent-consistent-human-first-cli.md (first 20 lines) ==="
   head -20 docs/adr-003-agent-consistent-human-first-cli.md
   
   echo ""
   echo "=== developers-guide.md expand_foreach section (lines 200-260 and 690-740) ==="
   sed -n '200,260p' docs/developers-guide.md
   echo "---"
   sed -n '690,740p' docs/developers-guide.md

   Length of output: 8723

   ---

   🏁 Script executed:

   #!/bin/bash
   gh issue close 299 --repo leynos/netsuke --comment "All three documentation items have been addressed in the codebase:
   
   1. **\`expand_foreach\` in the developers guide** – \`docs/developers-guide.md\` contains both a high-level pipeline walkthrough under *Manifest \`foreach\` expansion* and a full API reference under *expand_foreach*, covering purpose, inputs, behaviour, error conditions, and cross-references to \`netsuke-design.md\` §2.5 and roadmap task 3.14.2.
   
   2. **ADR for actions \`foreach\`/\`when\` scope** – \`docs/adr-003-actions-foreach-when-scope.md\` (accepted 2026-05-08) records the decision to keep \`foreach\` and \`when\` scoped to manifest targets only. It documents the rationale, the alternatives rejected, and the consequences (validators must reject action-level control keys with an error).
   
   3. **Roadmap 3.14 disposition** – Section 3.14 *Conditional action planning* is fully present in \`docs/roadmap.md\` with tasks 3.14.1–3.14.11. The *Historical task traceability* preamble explains which tasks were completed (3.14.1–3.14.3) and which remain active (3.14.4–3.14.11), with a specific note on 3.14.2 and 3.14.4.
   
   No further changes are required. Closing as resolved.
   
   > **Note:** \`docs/adr-003-actions-foreach-when-scope.md\` and \`docs/adr-003-agent-consistent-human-first-cli.md\` share the same ADR number prefix. This numbering conflict is outside the scope of this issue but may warrant a follow-up renaming."

   Length of output: 1851

   ---

   ---

   @leynos, issue #299 is now closed. All three items have been fully addressed in the codebase:

   1. expand_foreach documentation — docs/developers-guide.md contains both a high-level pipeline walkthrough under Manifest foreach expansion and a full API reference under expand_foreach, covering purpose, inputs, behaviour, error conditions, and cross-references to netsuke-design.md §2.5 and roadmap task 3.14.2.

   2. ADR for actions foreach/when scope — docs/adr-003-actions-foreach-when-scope.md (accepted 2026-05-08) records the decision to keep foreach and when scoped to manifest targets only. It documents the rationale, the alternatives rejected, and the consequences (validators must reject action-level control keys with a hard error, not a warning).

   3. Roadmap 3.14 disposition — Section 3.14 Conditional action planning is fully present in docs/roadmap.md with tasks 3.14.1–3.14.11. The Historical task traceability preamble explains which were completed (3.14.1–3.14.3) and which remain active (3.14.4–3.14.11).

   No code changes are required; this was documentation only.

   ---

   One side-note worth a follow-up: docs/adr-003-actions-foreach-when-scope.md and docs/adr-003-agent-consistent-human-first-cli.md share the 003 number prefix. The second ADR should be renumbered to adr-004-* to avoid ambiguity. Raise a separate issue if you'd like that tracked.