@davidorex/pi-workflows 0.14.4 → 0.26.0

package/templates/items/project.md

@@ -0,0 +1,48 @@
+{#-
+  Per-item macro for the `project` block (Plan 8 / per-item-macros wave 4).
+
+  Singleton kind: the project block holds one record per repository (no
+  homogeneous items[] array). The "per-item" rendering thus operates on the
+  whole block payload as a single record. The whole-block delegator in
+  shared/macros.md passes its data argument straight through.
+
+  No cross-block references — depth parameter accepted for shape-uniformity
+  with other per-item macros; no helpers from shared/render-helpers.md are
+  needed at present.
+
+  Empty-array convention:
+    Optional list/object fields render their label only when populated. The
+    project schema makes `name`, `description`, and `core_value` required and
+    the rest optional; bare-required output is the predictable shape for
+    minimal records.
+-#}
+
+{% macro render_project_item(p, depth=0) %}
+{% if p %}
+## Project
+**{{ p.name }}** — {{ enforceBudget(p.description, "project", "description") }}
+{% if p.core_value %}Core value: {{ enforceBudget(p.core_value, "project", "core_value") }}{% endif %}
+{% if p.vision %}
+Vision: {{ enforceBudget(p.vision, "project", "vision") }}{% endif %}
+{% if p.status %}Status: {{ p.status }}{% endif %}
+{% if p.target_users %}
+Target users: {{ p.target_users | join(", ") }}{% endif %}
+{% if p.constraints %}
+### Constraints
+{% for c in p.constraints %}- [{{ c.type }}] {{ enforceBudget(c.description, "project", "constraints.items.description") }}
+{% endfor %}{% endif %}
+{% if p.scope_boundaries %}
+### Scope
+**In:** {% for s in p.scope_boundaries.in %}{{ s }}{% if not loop.last %}, {% endif %}{% endfor %}
+
+**Out:** {% for s in p.scope_boundaries.out %}{{ s }}{% if not loop.last %}, {% endif %}{% endfor %}
+{% endif %}
+{% if p.goals %}
+### Goals
+{% for g in p.goals %}- **{{ g.id }}**: {{ enforceBudget(g.description, "project", "goals.items.description") }}{% if g.success_criteria %} — criteria: {% for sc in g.success_criteria %}{{ enforceBudget(sc, "project", "goals.items.success_criteria.items") }}{% if not loop.last %}; {% endif %}{% endfor %}{% endif %}
+{% endfor %}{% endif %}
+{% if p.repository %}Repository: {{ p.repository }}
+{% endif %}{% if p.stack %}Stack: {{ p.stack | join(", ") }}
+{% endif %}
+{% endif %}
+{% endmacro %}

package/templates/items/requirements.md

@@ -0,0 +1,20 @@
+{#-
+  Per-item macro for the `requirements` block (Plan 8 / per-item-macros wave 4).
+
+  Block schema: .project/schemas/requirements.schema.json. Each item is one
+  requirement inside data.requirements[]. Required: id (^REQ-\d{3,}$),
+  description, type, status, priority. Optional: acceptance_criteria,
+  source, traces_to (phase/task IDs), depends_on (other requirement IDs).
+
+  Cross-block reference recursion (traces_to, depends_on) is delegated to
+  shared/render-helpers.md — see that file for the depth contract, ambient
+  globals, and empty-array convention shared across all per-item macros.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_inline %}
+
+{% macro render_requirement(req, depth=0) %}
+{% if req %}- **{{ req.id }}** [{{ req.priority }}] ({{ req.type }}, {{ req.status }}): {{ enforceBudget(req.description, "requirements", "requirements.items.description") }}{% if req.acceptance_criteria %}
+  Criteria: {% for ac in req.acceptance_criteria %}{{ enforceBudget(ac, "requirements", "requirements.items.acceptance_criteria.items") }}{% if not loop.last %}; {% endif %}{% endfor %}{% endif %}
+{% if req.source %}  Source: {{ req.source }}
+{% endif %}{{ render_id_list_inline("Traces to", req.traces_to, depth) }}{{ render_id_list_inline("Depends on", req.depends_on, depth) }}{% endif %}
+{% endmacro %}

package/templates/items/research.md

@@ -0,0 +1,57 @@
+{#-
+  Per-item macro for the `research` block.
+
+  Block schema: .project/schemas/research.schema.json (Plan 7 / per-item-macros wave 4).
+
+  Cross-block reference recursion (informs, informed_by, related_research,
+  produces_findings, supersedes, superseded_by) is delegated to
+  shared/render-helpers.md — see that file for the depth contract, ambient
+  globals, and empty-array convention.
+
+  Embedded substructures:
+    `grounding` is an object with dependencies/revisions/external_refs
+    string arrays — rendered inline as labelled sub-lists, never recursed.
+    `citations[]` carries label/path/lines/url/retrieved_at — labelled
+    pointers to source material, not block IDs; rendered inline.
+    `stale_conditions[]` and `scope[]` are simple string arrays rendered as
+    bullet sub-lists.
+
+  x-prompt-budget integration:
+    The schema annotates `findings_summary`, `question`, `method` with
+    `x-prompt-budget`. enforceBudget is wired for these per Plan 5.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_block, render_id_single_block, render_optional_scalar %}
+
+{% macro render_research(r, depth=0) %}
+ID: {{ r.id }}
+Title: {{ r.title }}
+Status: {{ r.status }}
+Layer: {{ r.layer }}
+Type: {{ r.type }}
+Created by: {{ r.created_by }}
+Created at: {{ r.created_at }}
+{{ render_optional_scalar("Modified by", r.modified_by) }}{{ render_optional_scalar("Modified at", r.modified_at) }}{{ render_optional_scalar("Conducted by", r.conducted_by) }}{{ render_optional_scalar("Conducted at", r.conducted_at) }}{{ render_optional_scalar("Grounded at", r.grounded_at) }}
+Question:
+{{ enforceBudget(r.question, "research", "research.items.question") }}
+
+Method:
+{{ enforceBudget(r.method, "research", "research.items.method") }}
+
+{% if r.scope is defined %}Scope:
+{% if r.scope | length > 0 %}{% for s in r.scope %}  - {{ s }}
+{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}Findings summary:
+{{ enforceBudget(r.findings_summary, "research", "research.items.findings_summary") }}
+
+{% if r.findings_document %}Findings document: {{ r.findings_document }}
+{% endif %}{% if r.grounding is defined %}Grounding:
+{% if r.grounding.dependencies is defined %}  Dependencies: {% if r.grounding.dependencies | length > 0 %}{% for d in r.grounding.dependencies %}{{ d }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% if r.grounding.revisions is defined %}  Revisions: {% if r.grounding.revisions | length > 0 %}{% for rv in r.grounding.revisions %}{{ rv }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% if r.grounding.external_refs is defined %}  External refs: {% if r.grounding.external_refs | length > 0 %}{% for er in r.grounding.external_refs %}{{ er }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% endif %}{% if r.stale_conditions is defined %}Stale conditions:
+{% if r.stale_conditions | length > 0 %}{% for sc in r.stale_conditions %}  - {{ sc }}
+{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}{% if r.citations is defined %}Citations:
+{% if r.citations | length > 0 %}{% for c in r.citations %}  - {{ c.label }}{% if c.path %} — path: {{ c.path }}{% if c.lines %}:{{ c.lines }}{% endif %}{% endif %}{% if c.url %} — url: {{ c.url }}{% endif %}{% if c.retrieved_at %} — retrieved_at: {{ c.retrieved_at }}{% endif %}
+{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}{{ render_id_list_block("Informs", r.informs, depth) }}{{ render_id_list_block("Informed by", r.informed_by, depth) }}{{ render_id_list_block("Related research", r.related_research, depth) }}{{ render_id_list_block("Produces findings", r.produces_findings, depth) }}{{ render_id_list_block("Supersedes", r.supersedes, depth) }}{{ render_id_single_block("Superseded by", r.superseded_by, depth) }}{% endmacro %}

package/templates/items/spec-reviews.md

@@ -0,0 +1,51 @@
+{#-
+  Per-item macro for the `spec-reviews` block.
+
+  Block schema: .project/schemas/spec-reviews.schema.json (Plan 7 / per-item-macros wave 4).
+
+  Findings:
+    Each review carries an embedded findings registry (definitions/finding
+    in the schema). Findings are rendered inline as a sub-list under the
+    review body — they are not block items in their own right and have no
+    per-item macro of their own. Each finding's `produces_decision` (when
+    present and depth > 0) recurses into the decisions block via
+    resolve/render_recursive — that pattern stays inline because it has a
+    deeper indent (4 spaces) than the helper convention assumes and is
+    embedded in a finding-iteration loop rather than a top-level field.
+    `related_findings` on a finding refer to sibling findings within the
+    same review by their string ids; they are emitted as bare IDs (no
+    recursion — finding IDs are scoped to the review and not in the global
+    ID index).
+
+  Optional review-level scalars (target_revision, reviewer, completed_at,
+  clean) and the method body delegate to shared/render-helpers.md
+  render_optional_scalar where the shape matches.
+-#}
+{% from "shared/render-helpers.md" import render_optional_scalar %}
+
+{% macro render_spec_review(rev, depth=0) %}
+ID: {{ rev.id }}
+Target: {{ rev.target }}
+Status: {{ rev.status }}
+Created by: {{ rev.created_by }}
+Created at: {{ rev.created_at }}
+{{ render_optional_scalar("Target revision", rev.target_revision) }}{{ render_optional_scalar("Reviewer", rev.reviewer) }}{{ render_optional_scalar("Completed at", rev.completed_at) }}{% if rev.clean is defined %}Clean: {{ rev.clean }}
+{% endif %}{% if rev.method %}Method:
+{{ enforceBudget(rev.method, "spec-reviews", "reviews.items.method") }}
+
+{% endif %}{% if rev.scope is defined %}Scope:
+{% if rev.scope | length > 0 %}{% for s in rev.scope %}  - {{ s }}
+{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}Findings:
+{% if rev.findings and rev.findings | length > 0 %}{% for f in rev.findings %}  - {{ f.id }} [{{ f.severity }}/{{ f.category }}/{{ f.state }}] reporter={{ f.reporter }} at={{ f.created_at }}
+    Description: {{ enforceBudget(f.description, "spec-reviews", "reviews.items.findings.items.description") }}
+{% if f.evidence %}    Evidence: {{ f.evidence }}
+{% endif %}{% if f.location %}    Location: {{ f.location }}
+{% endif %}{% if f.resolution %}    Resolution: {{ f.resolution }}
+{% endif %}{% if f.resolved_by %}    Resolved by: {{ f.resolved_by }}
+{% endif %}{% if f.resolved_at %}    Resolved at: {{ f.resolved_at }}
+{% endif %}{% if f.produces_decision %}    Produces decision: {% if depth > 0 %}{% set loc = resolve(f.produces_decision) %}{% if loc %}
+{{ render_recursive(loc, depth - 1) }}{% else %}{{ f.produces_decision }}{% endif %}{% else %}{{ f.produces_decision }}{% endif %}
+{% endif %}{% if f.related_findings is defined %}    Related findings: {% if f.related_findings | length > 0 %}{% for rf in f.related_findings %}{{ rf }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% endfor %}{% else %}  (none)
+{% endif %}{% endmacro %}

package/templates/items/tasks.md

@@ -0,0 +1,29 @@
+{#-
+  Per-item macro for the `tasks` block (Plan 8 / per-item-macros wave 4).
+
+  Block schema: .project/schemas/tasks.schema.json. Each item is one task
+  inside data.tasks[]. Required: id (^TASK-\d{3,}$), description, status.
+  Optional: phase (string|integer), files, acceptance_criteria, depends_on
+  (other task IDs), assigned_agent, verification (verification ID), notes.
+
+  When status === "completed", schema additionally requires verification
+  (the if/then conditional in the schema).
+
+  Cross-block reference recursion (depends_on, verification) is delegated to
+  shared/render-helpers.md — see that file for the depth contract, ambient
+  globals, and empty-array convention. verification is rendered as a single
+  inline reference (one ID) rather than a list.
+
+  Files field:
+    files[] is a list of code paths, not project-block IDs. Rendered inline
+    as a comma-separated list; never recursed.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_inline, render_id_single_inline %}
+
+{% macro render_task(t, depth=0) %}
+{% if t %}- **{{ t.id }}** [{{ t.status }}]: {{ enforceBudget(t.description, "tasks", "tasks.items.description") }}{% if t.phase %} (phase {{ t.phase }}){% endif %}{% if t.files %} — files: {{ t.files | join(", ") }}{% endif %}
+{% if t.acceptance_criteria %}  Criteria: {% for ac in t.acceptance_criteria %}{{ enforceBudget(ac, "tasks", "tasks.items.acceptance_criteria.items") }}{% if not loop.last %}; {% endif %}{% endfor %}
+{% endif %}{% if t.assigned_agent %}  Assigned agent: {{ t.assigned_agent }}
+{% endif %}{% if t.notes %}  Notes: {{ enforceBudget(t.notes, "tasks", "tasks.items.notes") }}
+{% endif %}{{ render_id_list_inline("Depends on", t.depends_on, depth) }}{{ render_id_single_inline("Verification", t.verification, depth) }}{% endif %}
+{% endmacro %}

package/templates/shared/macros.md

@@ -1,109 +1,104 @@
-{#- Block rendering macros — one per schema with agent prompt use cases.
-    Import via: {% from "shared/macros.md" import render_project, render_architecture %}
-    Each macro: null guard, markdown heading, field rendering. Missing data renders nothing. -#}
+{#- Block rendering macros — whole-block forms as derived views over per-item macros.
 
-{% macro render_project(data) %}
-{% if data %}
-## Project
-**{{ data.name }}** — {{ data.description }}
-{% if data.core_value %}Core value: {{ data.core_value }}{% endif %}
-{% if data.vision %}
-Vision: {{ data.vision }}{% endif %}
-{% if data.status %}Status: {{ data.status }}{% endif %}
-{% if data.target_users %}
-Target users: {{ data.target_users | join(", ") }}{% endif %}
-{% if data.constraints %}
-### Constraints
-{% for c in data.constraints %}- [{{ c.type }}] {{ c.description }}
-{% endfor %}{% endif %}
-{% if data.scope_boundaries %}
-### Scope
-**In:** {% for s in data.scope_boundaries.in %}{{ s }}{% if not loop.last %}, {% endif %}{% endfor %}
+    Plan 8 (Wave 4) refactor: each whole-block macro that has a per-item sibling
+    in templates/items/<kind>.md delegates to that per-item macro by mapping
+    over the items array. Per-item macros own field rendering; whole-block macros
+    own the surrounding heading and the null/empty guard.
 
-**Out:** {% for s in data.scope_boundaries.out %}{{ s }}{% if not loop.last %}, {% endif %}{% endfor %}
-{% endif %}
-{% if data.goals %}
-### Goals
-{% for g in data.goals %}- **{{ g.id }}**: {{ g.description }}{% if g.success_criteria %} — criteria: {{ g.success_criteria | join("; ") }}{% endif %}
-{% endfor %}{% endif %}
-{% endif %}
+    v0.24.2 follow-up (Item 3 of 2026-05-02 residual-debt patch): the
+    repeated `{% if data and data.<key> [and data.<key> | length > 0] %}` +
+    `## <Heading>` + `{% for x in data.<key> %}{{ render_<kind>_item(x) }}
+    {% endfor %}` shape that previously lived inline in render_requirements,
+    render_domain, render_tasks, and render_issues now routes through the
+    `render_whole_block_truthy` / `render_whole_block_nonempty` scaffolds in
+    shared/render-helpers.md. The guard / heading / loop chassis lives once
+    in render-helpers; each whole-block macro here is the per-kind binding
+    (heading text, items slice, per-item macro inside the `{% call %}` body).
+    Output stays byte-identical to the prior inline shape — the two
+    truthy-vs-nonempty helpers preserve the empty-array surface each
+    delegator originally shipped (tasks/issues/domain emit `## <Heading>`
+    with empty array; requirements emits nothing — both regimes are kept
+    explicitly so existing consumers see no diff).
+
+    Imports for downstream consumers (unchanged signatures):
+        {% from "shared/macros.md" import render_project, render_architecture,
+                                          render_requirements, render_conformance,
+                                          render_domain, render_tasks, render_issues,
+                                          render_conventions,
+                                          render_exploration, render_exploration_full %}
+
+    Each macro:
+      - null/empty guard via the helper or local conditional,
+      - markdown heading (via the helper for list kinds; inline for the
+        singletons and the heading-bearing block-level shapes),
+      - delegation loop calling the per-item macro per item.
+
+    Retired in Plan 8:
+      - render_decisions(data) — legacy whole-block decisions macro deleted.
+        The new lifecycle decisions block has its own per-item macro
+        (templates/items/decisions.md ships render_decision + alias
+        render_decisions). The legacy macro rendered fields (decision,
+        rationale) that no longer match the current decisions.schema.json.
+      - render_gap(gap) — legacy single-item validation-concept macro deleted.
+        The framework-gaps.json block uses Plan 7's render_framework_gap in
+        templates/items/framework-gaps.md.
+
+    Retained as-is:
+      - render_exploration(exploration) and render_exploration_full(exploration)
+        are workflow-step output formatters (rendering exploration payloads
+        emitted by exploration agents), not project-block renderers. They do
+        not fit the per-item refactor pattern and stay unchanged. -#}
+
+{% from "shared/render-helpers.md" import render_whole_block_truthy, render_whole_block_nonempty %}
+
+{% from "items/project.md" import render_project_item %}
+{% macro render_project(data) %}
+{% if data %}{{ render_project_item(data) }}{% endif %}
 {% endmacro %}
 
+{% from "items/architecture.md" import render_architecture_item %}
 {% macro render_architecture(data) %}
-{% if data %}
-## Architecture
-{% if data.overview %}{{ data.overview }}
-{% endif %}
-{% if data.modules %}
-### Modules
-{% for m in data.modules %}- **{{ m.name }}** (`{{ m.file }}`{% if m.lines %}, {{ m.lines }} lines{% endif %}): {{ m.responsibility }}{% if m.dependencies %} — deps: {{ m.dependencies | join(", ") }}{% endif %}
-{% endfor %}{% endif %}
-{% if data.patterns %}
-### Patterns
-{% for p in data.patterns %}- **{{ p.name }}**: {{ p.description }}{% if p.used_in %} — used in: {{ p.used_in | join(", ") }}{% endif %}
-{% endfor %}{% endif %}
-{% if data.boundaries %}
-### Boundaries
-{% for b in data.boundaries %}- {{ b }}
-{% endfor %}{% endif %}
-{% endif %}
+{% if data %}{{ render_architecture_item(data) }}{% endif %}
 {% endmacro %}
 
-{% macro render_requirements(data) %}
-{% if data and data.requirements and data.requirements | length > 0 %}
-## Requirements
-{% for r in data.requirements %}- **{{ r.id }}** [{{ r.priority }}] ({{ r.type }}, {{ r.status }}): {{ r.description }}{% if r.acceptance_criteria %}
-  Criteria: {{ r.acceptance_criteria | join("; ") }}{% endif %}
-{% endfor %}
-{% endif %}
-{% endmacro %}
+{% from "items/requirements.md" import render_requirement %}
+{% macro render_requirements(data) %}{% call(req) render_whole_block_nonempty("Requirements", data.requirements if data else None) %}{{ render_requirement(req) }}{% endcall %}{% endmacro %}
 
+{% from "items/conformance.md" import render_conformance_principle %}
 {% macro render_conformance(data) %}
 {% if data and data.principles %}
 ## Conformance Reference
 {% if data.name %}**{{ data.name }}**{% endif %}
-{% for p in data.principles %}
-### {{ p.id }}: {{ p.name }}
-{% if p.description %}{{ p.description }}{% endif %}
-{% for r in p.rules %}- **{{ r.id }}**: {{ r.rule }}{% if r.severity %} [{{ r.severity }}]{% endif %}{% if r.check_method %} — check: {{ r.check_method }}{% endif %}
-{% if r.anti_patterns %}  Anti-patterns: {{ r.anti_patterns | join("; ") }}
-{% endif %}{% endfor %}
-{% endfor %}
+{% for p in data.principles %}{{ render_conformance_principle(p) }}{% endfor %}
 {% endif %}
 {% endmacro %}
 
-{% macro render_domain(data) %}
-{% if data and data.entries %}
-## Domain Knowledge
-{% for e in data.entries %}- **{{ e.id }}** [{{ e.category }}]: {{ e.title }}
-  {{ e.content }}{% if e.tags %} — tags: {{ e.tags | join(", ") }}{% endif %}
-{% endfor %}
-{% endif %}
-{% endmacro %}
+{% from "items/domain.md" import render_domain_entry %}
+{% macro render_domain(data) %}{% call(e) render_whole_block_truthy("Domain Knowledge", data.entries if data else None) %}{{ render_domain_entry(e) }}{% endcall %}{% endmacro %}
 
-{% macro render_decisions(data) %}
-{% if data and data.decisions %}
-## Decisions
-{% for d in data.decisions %}- **{{ d.id }}** ({{ d.status }}): {{ d.decision }}
-  Rationale: {{ d.rationale }}{% if d.context %} — context: {{ d.context }}{% endif %}
-{% endfor %}
-{% endif %}
-{% endmacro %}
+{% from "items/tasks.md" import render_task %}
+{% macro render_tasks(data) %}{% call(t) render_whole_block_truthy("Tasks", data.tasks if data else None) %}{{ render_task(t) }}{% endcall %}{% endmacro %}
 
-{% macro render_tasks(data) %}
-{% if data and data.tasks %}
-## Tasks
-{% for t in data.tasks %}- **{{ t.id }}** [{{ t.status }}]: {{ t.description }}{% if t.phase %} (phase {{ t.phase }}){% endif %}{% if t.files %} — files: {{ t.files | join(", ") }}{% endif %}
-{% endfor %}
-{% endif %}
-{% endmacro %}
+{% from "items/issues.md" import render_issue %}
+{% macro render_issues(data) %}{% call(i) render_whole_block_truthy("Issues", data.issues if data else None) %}{{ render_issue(i) }}{% endcall %}{% endmacro %}
 
-{% macro render_issues(data) %}
-{% if data and data.issues %}
-## Issues
-{% for i in data.issues %}- **{{ i.id }}** [{{ i.priority }}, {{ i.status }}]: {{ i.title }}
-  {{ i.body }}{% if i.location %} — {{ i.location }}{% endif %}{% if i.package %} ({{ i.package }}){% endif %}
-{% endfor %}
+{#- Authored fresh in Plan 8: render_conventions did not previously exist in
+    macros.md despite README references implying it did. The block-level
+    header surfaces test_conventions, lint_command, and lint_scope (all
+    optional) before iterating rules through render_convention.
+
+    Block schema: .project/schemas/conventions.schema.json. Required: rules.
+    Optional: test_conventions { runner_command, file_pattern }, lint_command,
+    lint_scope. -#}
+{% from "items/conventions.md" import render_convention %}
+{% macro render_conventions(data) %}
+{% if data and data.rules %}
+## Conventions
+{% if data.test_conventions %}
+**Tests:** `{{ data.test_conventions.runner_command }}` (pattern: `{{ data.test_conventions.file_pattern }}`)
+{% endif %}{% if data.lint_command %}**Lint:** `{{ data.lint_command }}`{% if data.lint_scope %} (scope: {{ data.lint_scope }}){% endif %}
+{% endif %}
+{% for rule in data.rules %}{{ render_convention(rule) }}{% endfor %}
 {% endif %}
 {% endmacro %}
 
@@ -140,13 +135,3 @@ Target users: {{ data.target_users | join(", ") }}{% endif %}
 {% endfor %}{% endif %}
 {% endif %}
 {% endmacro %}
-
-{% macro render_gap(gap) %}
-{% if gap %}
-**ID:** {{ gap.id }}
-**Description:** {{ gap.description }}
-**Category:** {{ gap.category | default("unspecified") }}
-**Priority:** {{ gap.priority | default("unspecified") }}
-{% if gap.details %}**Details:** {{ gap.details }}{% endif %}
-{% endif %}
-{% endmacro %}

package/templates/shared/render-helpers.md

@@ -0,0 +1,106 @@
+{#-
+  Shared rendering helpers for per-item macros.
+
+  Captures repeated micro-patterns that previously lived inline in every
+  per-item macro file under `items/*.md`. The aim is one definition per
+  pattern, consumed by every per-item macro that uses it.
+
+  Helpers exported:
+    render_id_list_block(label, ids, depth)
+    render_id_single_block(label, id, depth)
+    render_id_list_inline(label, ids, depth)
+    render_id_single_inline(label, id, depth)
+    render_optional_scalar(label, value)
+
+  Output convention:
+    Block-style helpers emit `<Label>:\n` followed by `  - <id>\n` per entry
+    (or `  (none)\n` for present-but-empty arrays). Absent (undefined)
+    arrays emit nothing.
+
+    Inline-style helpers emit `  <Label>: <id>[, <id>...]\n` (or `(none)\n`
+    for empty). The two-space indent prefix is part of the inline shape used
+    by domain.related_requirements, requirements.traces_to/depends_on, and
+    tasks.depends_on/verification — it is the indent under a parent list
+    bullet, not arbitrary padding.
+
+  Depth contract:
+    Each helper that takes `depth` honours the same recursion budget as the
+    per-item macros: depth <= 0 emits bare ID text; depth > 0 calls resolve
+    + render_recursive (ambient Nunjucks globals registered by compileAgent
+    in @davidorex/pi-jit-agents) and falls back to bare-ID on resolve miss.
+    Cycles → `[cycle: <id>]` and missing per-item macros → `[unrendered:
+    <kind>/<id>]` are produced inside render_recursive itself, not here.
+
+  resolve(id) and render_recursive(loc, depth) are env-level globals
+  available to imported macros without re-import.
+
+  Empty-array convention:
+    `is defined` discriminates absent vs present. Present-but-empty arrays
+    render the label with `(none)`; absent fields render nothing. This
+    preserves the per-item macro contract documented in items/decisions.md
+    and mirrored across every per-item macro.
+
+  Output equivalence:
+    The helper bodies are byte-identical to the patterns they replace. The
+    existing render-*.test.ts assertions are the regression net. If a
+    helper drifts from the inline pattern's output, those tests break.
+-#}
+
+{% macro render_id_list_block(label, ids, depth) %}{% if ids is defined %}{{ label }}:
+{% if ids | length > 0 %}{% for id in ids %}{% if depth > 0 %}{% set loc = resolve(id) %}{% if loc %}{{ render_recursive(loc, depth - 1) }}
+{% else %}  - {{ id }}
+{% endif %}{% else %}  - {{ id }}
+{% endif %}{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}{% endmacro %}
+
+{% macro render_id_single_block(label, id, depth) %}{% if id is defined and id %}{{ label }}:
+{% if depth > 0 %}{% set loc = resolve(id) %}{% if loc %}{{ render_recursive(loc, depth - 1) }}
+{% else %}  - {{ id }}
+{% endif %}{% else %}  - {{ id }}
+{% endif %}{% endif %}{% endmacro %}
+
+{% macro render_id_list_inline(label, ids, depth) %}{% if ids is defined %}  {{ label }}: {% if ids | length > 0 %}{% for id in ids %}{% if depth > 0 %}{% set loc = resolve(id) %}{% if loc %}{{ render_recursive(loc, depth - 1) }}{% else %}{{ id }}{% endif %}{% else %}{{ id }}{% endif %}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% endmacro %}
+
+{% macro render_id_single_inline(label, id, depth) %}{% if id %}  {{ label }}: {% if depth > 0 %}{% set loc = resolve(id) %}{% if loc %}{{ render_recursive(loc, depth - 1) }}{% else %}{{ id }}{% endif %}{% else %}{{ id }}{% endif %}
+{% endif %}{% endmacro %}
+
+{% macro render_optional_scalar(label, value) %}{% if value %}{{ label }}: {{ value }}
+{% endif %}{% endmacro %}
+
+{#-
+  Whole-block list scaffold (Plan 8 follow-up).
+
+  Centralises the truthy-guard + heading + per-item iteration shape that
+  previously repeated across the whole-block delegators in shared/macros.md
+  for `render_domain`, `render_tasks`, and `render_issues`. Each delegator
+  now reduces to one `{% call %}` block that supplies the per-item macro as
+  its body — the heading-and-loop chassis lives here once.
+
+  Two variants encode the two empty-handling regimes the legacy delegators
+  shipped, kept distinct so output stays byte-identical to the originals:
+
+    `render_whole_block_truthy(heading, items)`
+        Heading-and-loop fire whenever `items` is truthy (matches the
+        legacy `{% if data and data.<key> %}` guard used by tasks, issues,
+        domain). Empty arrays still emit the heading because `[]` is truthy
+        in Nunjucks — that surface is preserved deliberately.
+
+    `render_whole_block_nonempty(heading, items)`
+        Heading-and-loop fire only when `items | length > 0` (matches the
+        legacy `{% if data and data.requirements and data.requirements |
+        length > 0 %}` guard used by requirements). Empty arrays produce
+        nothing.
+
+  In both, the caller body (`{{ caller(item) }}`) is invoked once per item
+  with the item bound to the call-block parameter.
+-#}
+{% macro render_whole_block_truthy(heading, items) %}{% if items %}
+## {{ heading }}
+{% for item in items %}{{ caller(item) }}{% endfor %}
+{% endif %}{% endmacro %}
+
+{% macro render_whole_block_nonempty(heading, items) %}{% if items and items | length > 0 %}
+## {{ heading }}
+{% for item in items %}{{ caller(item) }}{% endfor %}
+{% endif %}{% endmacro %}

package/workflows/analyze-existing-project.workflow.yaml

@@ -85,4 +85,4 @@ completion:
     **Architecture:** ${{ steps.infer-architecture.output.modules | length }} modules, ${{ steps.infer-architecture.output.patterns | length }} patterns
     **Gaps:** ${{ steps.identify-issues.output.issues | length }} identified
 
-    Use `/project status` to see the full state. Use `/project validate` to check cross-block references.
+    Use `/context status` to see the full state. Use `/context validate` to check cross-block references.

package/workflows/init-new-project.workflow.yaml

@@ -78,4 +78,4 @@ completion:
     **Architecture:** ${{ steps.design-architecture.output.modules | length }} modules
     **Plan:** phases and tasks created
 
-    Use `/project status` to see the full state. Use `/project validate` to check cross-block references.
+    Use `/context status` to see the full state. Use `/context validate` to check cross-block references.

package/workflows/plan-from-requirements.workflow.yaml

@@ -44,5 +44,5 @@ completion:
   template: |
     Plan created from requirements. Tasks written to .project/tasks.json.
 
-    Use `/project status` to see the phase and task breakdown.
-    Use `/project validate` to check cross-block references.
+    Use `/context status` to see the phase and task breakdown.
+    Use `/context validate` to check cross-block references.