@davidorex/pi-jit-agents 0.26.0 → 0.28.1

package/templates/shared/macros.md

@@ -0,0 +1,169 @@
+{#- Block rendering macros — whole-block forms as derived views over per-item macros.
+
+    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.
+
+    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 %}{{ render_architecture_item(data) }}{% 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 %}{{ render_conformance_principle(p) }}{% 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 %}
+
+{% 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 %}
+
+{% 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 %}
+
+{#- 6 whole-block delegators landed via the template-relocation arc. Each
+    delegates to the per-item macro from items/<kind>.md through
+    render_whole_block_truthy. Names follow the plural convention
+    (render_<plural-kind>). The display_name string and array_key are
+    sourced from packages/pi-context/samples/conception.json verbatim;
+    array_key diverges from block_kind for 3 of these 6 (framework-gaps→
+    gaps, layer-plans→plans, spec-reviews→reviews). The canonical macro
+    name + the array_key are also encoded in CANONICAL_MACRO_NAMES at
+    packages/pi-jit-agents/src/renderer-registry.ts for programmatic
+    resolution. Alphabetical by block_kind. -#}
+
+{% from "items/decisions.md" import render_decision %}
+{% macro render_decisions(data) %}{% call(d) render_whole_block_truthy("Decisions", data.decisions if data else None) %}{{ render_decision(d) }}{% endcall %}{% endmacro %}
+
+{% from "items/features.md" import render_feature %}
+{% macro render_features(data) %}{% call(f) render_whole_block_truthy("Features", data.features if data else None) %}{{ render_feature(f) }}{% endcall %}{% endmacro %}
+
+{% from "items/framework-gaps.md" import render_framework_gap %}
+{% macro render_framework_gaps(data) %}{% call(g) render_whole_block_truthy("Framework Gaps", data.gaps if data else None) %}{{ render_framework_gap(g) }}{% endcall %}{% endmacro %}
+
+{% from "items/layer-plans.md" import render_layer_plan %}
+{% macro render_layer_plans(data) %}{% call(p) render_whole_block_truthy("Layer Restructure Plans", data.plans if data else None) %}{{ render_layer_plan(p) }}{% endcall %}{% endmacro %}
+
+{#- research per-item macro is itself named render_research (the canonical
+    per-item name in CANONICAL_MACRO_NAMES); alias on import to avoid the
+    name collision with the whole-block delegator declared just below. -#}
+{% from "items/research.md" import render_research as render_research_item %}
+{% macro render_research(data) %}{% call(r) render_whole_block_truthy("Research", data.research if data else None) %}{{ render_research_item(r) }}{% endcall %}{% endmacro %}
+
+{% from "items/spec-reviews.md" import render_spec_review %}
+{% macro render_spec_reviews(data) %}{% call(rev) render_whole_block_truthy("Spec Reviews", data.reviews if data else None) %}{{ render_spec_review(rev) }}{% endcall %}{% endmacro %}
+
+{#- 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 %}
+
+{% macro render_exploration(exploration) %}
+{% if exploration %}
+{% if exploration.files is defined %}
+## Prior Exploration
+{% for file in exploration.files %}- `{{ file.path }}` ({{ file.lines | default("?") }} lines){% if file.exports %}: {{ file.exports | length }} exports{% endif %}
+{% endfor %}{% endif %}
+{% if exploration.types is defined %}
+### Known Types
+{% for t in exploration.types %}- `{{ t.name }}` ({{ t.kind }}) in `{{ t.file }}`
+{% endfor %}{% endif %}
+{% endif %}
+{% endmacro %}
+
+{% macro render_exploration_full(exploration) %}
+{% if exploration %}
+{% if exploration.files is defined %}
+### Files{% if exploration.files | length > 20 %} ({{ exploration.files | length }} total){% endif %}
+{% for file in exploration.files %}- `{{ file.path }}` ({{ file.language | default("unknown") }}, {{ file.lines | default("?") }} lines){% if file.exports %} — {{ file.exports | length }} exports{% endif %}
+{% endfor %}{% endif %}
+{% if exploration.types is defined %}
+### Types
+{% for t in exploration.types %}- `{{ t.name }}` ({{ t.kind }}) in `{{ t.file }}`
+{% endfor %}{% endif %}
+{% if exploration.dependencies is defined %}
+### Dependencies
+{% for d in exploration.dependencies %}- `{{ d.from }}` → `{{ d.to }}` ({{ d.type | default("import") }})
+{% endfor %}{% endif %}
+{% if exploration.entryPoints is defined %}
+### Entry Points
+{% for ep in exploration.entryPoints %}- `{{ ep }}`
+{% endfor %}{% 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/templates/spec-implementer/task.md

@@ -0,0 +1,53 @@
+## Plan: {{ spec.name }}
+
+### Intent
+{{ spec.intent | default(spec.description, true) }}
+
+{% if spec.tasks %}
+### Tasks
+{% for task in spec.tasks %}
+{{ loop.index }}. {{ task }}
+{% endfor %}
+{% endif %}
+
+### Files to Change
+{% for f in spec.files_to_change | default(spec.files, true) %}
+- `{{ f }}`
+{% endfor %}
+
+### Acceptance Criteria
+{% for criterion in spec.acceptance_criteria %}
+- {{ criterion }}
+{% endfor %}
+
+{% if spec.context_needed %}
+### Context to Read First
+{% for ctx in spec.context_needed %}
+- `{{ ctx }}`
+{% endfor %}
+{% endif %}
+
+### Architecture Reference
+{% for module in architecture.modules %}
+- **{{ module.name }}** ({{ module.file }}): {{ module.responsibility }}
+{% endfor %}
+
+### Conventions
+{% for rule in conventions.rules %}
+- {{ rule.id }}: {{ rule.description }} ({{ rule.enforcement }})
+{% endfor %}
+
+## Instructions
+
+Implement this plan. Follow these steps:
+
+1. **Read context first**: Read the files listed under "Context to Read First" and any related source files to understand existing patterns
+2. **Implement each task**: Work through the task list in order, writing code that follows the project conventions
+3. **Run tests**: After implementation, run the relevant test suite to verify your changes work
+4. **Validate acceptance criteria**: Confirm each acceptance criterion is met
+
+Produce a JSON result conforming to this schema:
+
+```json
+{{ output_schema }}
+```

package/templates/synthesizer/system.md

@@ -0,0 +1,3 @@
+You are a report synthesizer. You receive typed analysis data from three independent reviewers (structure, quality, patterns) and produce a unified synthesis as structured JSON.
+
+Every finding must trace to specific data from the input analyses. Do not invent findings that aren't grounded in the input data.

package/templates/synthesizer/task.md

@@ -0,0 +1,38 @@
+Synthesize the following analyses into a unified report.
+
+## Structure Analysis
+Architecture: {{ structure.architecture.organization }}
+Patterns: {% for p in structure.architecture.patterns %}{{ p }}{% if not loop.last %}, {% endif %}{% endfor %}
+
+### Modules
+{% for m in structure.modules %}
+- **{{ m.name }}**: {{ m.responsibility }} ({{ m.files | length }} files)
+{% endfor %}
+
+### Dependencies
+{% for d in structure.dependencies %}
+- `{{ d.from }}` → `{{ d.to }}` ({{ d.type }})
+{% endfor %}
+
+## Quality Analysis
+{% for c in quality.concerns %}
+- [{{ c.severity }}] {{ c.description }}{% if c.file %} in `{{ c.file }}`{% endif %}
+{% endfor %}
+
+### Test Coverage
+- Tested: {% for t in quality.testCoverage.tested %}`{{ t }}`{% if not loop.last %}, {% endif %}{% endfor %}
+- Untested: {% for t in quality.testCoverage.untested %}`{{ t }}`{% if not loop.last %}, {% endif %}{% endfor %}
+
+### Maintainability: {{ quality.maintainability.score }}
+
+## Pattern Analysis
+{% for p in patterns.patterns %}
+- **{{ p.name }}**: {{ p.usage }}{% if not p.correct %} ⚠️{% endif %}
+{% endfor %}
+
+### Recommendations
+{% for r in patterns.recommendations %}
+- [{{ r.priority }}] **{{ r.pattern }}**: {{ r.suggestion }}
+{% endfor %}
+
+Write your synthesis as JSON conforming to the output schema.

package/templates/task-verifier/task.md

@@ -0,0 +1,44 @@
+Verify whether the following task implementation satisfies its acceptance criteria.
+
+## Task: {{ task_id }}
+
+## Acceptance Criteria
+
+{% for criterion in acceptance_criteria %}
+{{ loop.index }}. {{ criterion }}
+{% endfor %}
+
+## Implementation Changes
+
+{% if changes is mapping %}
+{% if changes.tasks is defined %}
+### Worker Results
+- Status: {{ changes.status | default("unknown") }}
+{% for t in changes.tasks %}
+- **{{ t.name }}**: {{ t.status }}{% if t.files_modified %} (files: {{ t.files_modified | join(", ") }}){% endif %}
+{% if t.notes %} — {{ t.notes }}{% endif %}
+{% endfor %}
+{% else %}
+```json
+{{ changes | dump(2) }}
+```
+{% endif %}
+{% else %}
+{{ changes }}
+{% endif %}
+
+## Instructions
+
+For EACH acceptance criterion above:
+
+1. Read the relevant source files to understand the current code state
+2. If the criterion is verifiable by command (test, build, lint), run the command
+3. If the criterion requires code inspection, read the files and assess
+4. Record your verdict: `passed`, `failed`, or `skipped`
+5. Provide specific evidence (file:line references, command output, code snippets)
+
+Then produce a JSON verification entry:
+
+```json
+{{ output_schema }}
+```

package/templates/task-worker/task.md

@@ -0,0 +1,52 @@
+## Task: {{ task.id }}
+
+### Description
+{{ task.description }}
+
+{% if task.phase %}
+### Phase
+{{ task.phase }}
+{% endif %}
+
+### Files
+{% for f in task.files %}
+- `{{ f }}`
+{% endfor %}
+
+### Acceptance Criteria
+{% for criterion in task.acceptance_criteria %}
+- [ ] {{ criterion }}
+{% endfor %}
+
+{% if task.depends_on %}
+### Dependencies (completed)
+{% for dep in task.depends_on %}
+- {{ dep }}
+{% endfor %}
+{% endif %}
+
+{% if task.notes %}
+### Notes
+{{ task.notes }}
+{% endif %}
+
+{% if context %}
+### Context
+{{ context }}
+{% endif %}
+
+## Instructions
+
+Implement this task. Follow these steps:
+
+1. **Read the target files** listed above to understand the current state
+2. **Implement changes** that satisfy each acceptance criterion
+3. **Stay within scope** — only modify the files listed, unless a new file is strictly necessary
+4. **Run tests** after implementation to verify nothing is broken
+5. **Validate each criterion** — confirm every acceptance criterion is addressed
+
+Produce a JSON result conforming to this schema:
+
+```json
+{{ output_schema }}
+```

package/templates/verifier/task.md

@@ -0,0 +1,57 @@
+You are verifying the output of a prior step against declared success criteria.
+
+## Success Criteria
+
+{% for criterion in criteria %}
+- {{ criterion }}
+{% endfor %}
+
+## Step Output to Verify
+
+```json
+{{ step_output | dump(2) }}
+```
+
+{% if files_to_check %}
+## Files to Check
+
+{% for f in files_to_check %}
+- `{{ f }}`
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+For each criterion, choose the appropriate verification method and execute it:
+
+1. **command** — Run a shell command (test suite, build, lint) and report exit code + output as evidence
+2. **grep** — Search for specific patterns in files and report matches as evidence
+3. **inspect** — Read files and assess their content (use your judgment)
+4. **human** — Flag items that require human eyes and explain why automation cannot verify them
+
+### Process
+
+1. Evaluate each success criterion using the most appropriate verify method
+2. For `command` criteria: actually run the command and capture the output
+3. For `grep` criteria: search the relevant files and report what you find
+4. For `inspect` criteria: read the files and assess whether they meet the criterion
+5. For `human` criteria: describe what needs to be checked and why it needs a person
+6. Build truth claims from your observations, marking each as `verified`, `failed`, or `uncertain`
+7. Check that all referenced artifacts exist and are substantive (not stubs)
+8. Compute an overall score as "N/M" where N = passed criteria, M = total criteria
+9. Set status: `passed` if all criteria pass, `gaps_found` if any fail, `human_needed` if any require human review
+
+### Output Format
+
+Produce JSON conforming to the verifier-output schema with these fields:
+
+- `status`: "passed" | "gaps_found" | "human_needed"
+- `score`: "N/M" format
+- `truths[]`: observable claims with status and evidence
+- `criteria_results[]`: one entry per criterion with verify_method, status, expected/actual outcome, evidence
+- `artifacts[]`: (optional) file paths checked with existence/substance status
+- `requirements_coverage[]`: (optional) requirement satisfaction mapping
+- `human_verification[]`: (optional) items needing human review
+- `gaps[]`: (optional) failed or uncertain truths with reasons
+
+Be thorough. Run actual commands. Read actual files. Report what you observe, not what you assume.