@davidorex/pi-jit-agents 0.26.0 → 0.28.0

package/templates/gap-identifier/task.md

@@ -0,0 +1,103 @@
+Identify gaps in the project at `{{ path }}`.
+
+## Architecture
+
+{% if architecture.overview %}
+{{ architecture.overview }}
+{% endif %}
+
+### Modules
+{% if architecture.modules is defined %}
+{% for m in architecture.modules %}
+- **{{ m.name }}** (`{{ m.file }}`{% if m.lines %}, {{ m.lines }} lines{% endif %}): {{ m.responsibility }}
+{% endfor %}
+{% endif %}
+
+{% if architecture.patterns is defined %}
+### Patterns
+{% for p in architecture.patterns %}
+- **{{ p.name }}**: {{ p.description }}{% if p.used_in %} — used in: {{ p.used_in | join(", ") }}{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if architecture.boundaries is defined %}
+### Boundaries
+{% for b in architecture.boundaries %}
+- {{ b }}
+{% endfor %}
+{% endif %}
+
+## Codebase Analysis
+
+{% if exploration.files is defined %}
+### Files ({{ exploration.files | length }} total)
+{% 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 %}
+
+## Instructions
+
+Cross-reference the architecture and analysis to identify gaps. Use targeted reads to verify findings.
+
+### Gap categories to check
+
+1. **missing** — functionality that should exist based on architecture but doesn't
+   - Test files for source modules (find test files, compare against source)
+   - Error handling for public APIs
+   - Documentation for exported interfaces
+   - Schema validation for user-facing inputs
+
+2. **incomplete** — partially implemented functionality
+   - TODO/FIXME/HACK comments (`grep -r "TODO\|FIXME\|HACK"`)
+   - Stub or placeholder implementations
+   - Functions that return hardcoded values or throw "not implemented"
+
+3. **defect** — likely bugs or incorrect behavior
+   - Uncaught promise rejections, missing null checks
+   - Type assertions that bypass safety (`as any`, `!` operator overuse)
+   - Error paths that swallow exceptions silently
+
+4. **technical-debt** — code that works but hampers maintenance
+   - Duplicated logic across modules
+   - Outdated patterns inconsistent with the rest of the codebase
+   - Overly complex functions (high cyclomatic complexity)
+
+5. **improvement** — opportunities to improve existing working code
+   - Performance bottlenecks
+   - Missing caching or memoization for expensive operations
+   - Public APIs that could be more ergonomic
+
+6. **question** — ambiguities requiring human or further investigation
+   - Unclear design decisions without documented rationale
+   - Behavior that could be intentional or accidental
+
+### Gap ID format
+
+Use the pattern: `gap-{abbrev}-{nnn}` where abbrev is:
+- `miss` for missing, `inc` for incomplete, `def` for defect
+- `debt` for technical-debt, `imp` for improvement, `q` for question
+
+### Priority calibration
+
+- **critical**: blocks further development or causes data loss
+- **high**: significant impact on reliability, correctness, or developer experience
+- **medium**: notable but workable; should be addressed in normal development
+- **low**: minor cleanup or cosmetic; address opportunistically
+
+Set `source` to `"agent"` for all gaps. Set `status` to `"open"` for all gaps.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/gap-resolution-assessor/task.md

@@ -0,0 +1,48 @@
+Assess whether the implementation resolves this gap.
+
+## Gap
+
+**ID**: {{ gap.id }}
+**Description**: {{ gap.description }}
+**Category**: {{ gap.category | default("unspecified") }}
+**Priority**: {{ gap.priority | default("unspecified") }}
+
+## Investigation Findings
+
+```json
+{{ investigation | dump(2) }}
+```
+
+## Implementation Results
+
+{% if implementation_results is iterable and implementation_results is not string %}
+{% for result in implementation_results %}
+### Spec: {{ result.spec_name | default("unnamed") }}
+- Status: {{ result.status | default("unknown") }}
+- Files changed: {{ result.files_changed | default([]) | join(", ") }}
+{% if result.commit_hash %}- Commit: {{ result.commit_hash }}{% endif %}
+{% endfor %}
+{% else %}
+```json
+{{ implementation_results | dump(2) }}
+```
+{% endif %}
+
+## Check Results
+
+- Status: {{ check_results.status }}
+{% if check_results.errors | length > 0 %}
+- Errors:
+{% for err in check_results.errors %}
+  - {{ err }}
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+1. Read the gap description above. Understand what root cause it identifies.
+2. Examine the implementation results — what files were changed and what was the stated work.
+3. Run `git diff HEAD~{{ implementation_results | length | default(1) }}` (or appropriate range) to see actual code changes.
+4. Judge: do the code changes address the root cause described in the gap?
+5. If tests failed or lint errors exist, the gap is NOT resolved regardless of code quality.
+6. Produce your assessment as JSON.

package/templates/handoff-writer/task.md

@@ -0,0 +1,101 @@
+Capture a handoff snapshot for the project at `{{ path }}`.
+
+## Current Project State
+
+{% if project_state.blocks_status %}
+### Block Availability
+
+| Block | Available |
+|-------|-----------|
+{% for name, available in project_state.blocks_status %}
+| {{ name }} | {{ "yes" if available else "NO — absent" }} |
+{% endfor %}
+{% endif %}
+
+{% if project_state.project %}
+### Project
+**{{ project_state.project.name | default("unnamed") }}** — {{ project_state.project.description | default("no description") }}
+Status: {{ project_state.project.status | default("unknown") }}
+{% endif %}
+
+{% if project_state.phases and project_state.phases | length > 0 %}
+### Phases
+{% for phase in project_state.phases %}
+- Phase {{ phase.number | default(loop.index) }}: {{ phase.name | default("unnamed") }} ({{ phase.status | default("unknown") }})
+{% endfor %}
+{% endif %}
+
+{% if project_state.blockSummaries %}
+### Block Summaries
+{% for block in project_state.blockSummaries %}
+- **{{ block.name }}**: {{ block.count | default("?") }} entries
+{% endfor %}
+{% endif %}
+
+{% if project_state.gaps %}
+### Open Gaps
+{% for gap in project_state.gaps %}
+{% if gap.status == "open" %}
+- [{{ gap.priority }}] {{ gap.id }}: {{ gap.description }}
+{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if project_state.decisions %}
+### Recent Decisions
+{% for decision in project_state.decisions %}
+- {{ decision.id | default("?") }}: {{ decision.description | default(decision.title | default("no description")) }}
+{% endfor %}
+{% endif %}
+
+{% if project_state.recentCommits %}
+### Recent Commits
+{% for commit in project_state.recentCommits %}
+- `{{ commit.sha | default("?") | truncate(7, true, "") }}` {{ commit.message | default("no message") }}
+{% endfor %}
+{% endif %}
+
+## Instructions
+
+Synthesize the project state above into a handoff block that enables a future agent or human to resume work seamlessly.
+
+1. **context** — Write a paragraph capturing:
+   - What was being worked on (current phase, recent commits, active changes)
+   - The current state of thinking (what decisions were made, what approach is being taken)
+   - Any momentum or direction that should be preserved
+
+2. **timestamp** — Current datetime in ISO 8601 format (e.g., 2026-03-18T14:30:00Z)
+
+3. **current_phase** — The phase currently being worked on (number or name)
+
+4. **current_tasks** — Task IDs currently in progress (from project state if available, otherwise infer from recent activity)
+
+5. **blockers** — Anything preventing progress:
+   - Unresolved decisions that block implementation
+   - Failing tests or broken builds
+   - Missing dependencies or external requirements
+   - Only include genuine blockers, not wishes
+
+6. **next_actions** — Concrete next steps, ordered by priority:
+   - What should the next session do first?
+   - What's the next logical step in the current phase?
+   - Keep to 3-5 actionable items
+
+7. **open_questions** — Genuine unknowns requiring input:
+   - Design decisions that need human judgment
+   - Ambiguities discovered during development
+   - Technical choices with trade-offs that haven't been resolved
+
+8. **key_decisions_pending** — Decision IDs from the project state that need resolution
+
+9. **files_in_flux** — Files with incomplete or in-progress changes (NOT every recently committed file — only files that have partial work)
+
+Read project blocks if needed to get more detail than the summary provides. Focus on in-flight state, not project overview.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/investigator/task.md

@@ -0,0 +1,30 @@
+## Gap to Investigate
+
+**ID:** {{ gap.id }}
+**Description:** {{ gap.description }}
+**Category:** {{ gap.category }}
+**Priority:** {{ gap.priority }}
+{% if gap.details %}
+**Details:** {{ gap.details }}
+{% endif %}
+
+## Instructions
+
+Produce structured findings for this gap. Scope your investigation to the minimum needed:
+
+1. If the gap names specific files, read those. If not, use `find` or `ls` to identify candidates — don't read file contents unless you need to confirm behavior.
+2. For each affected file: what it does, what needs to change.
+3. List hard constraints (existing tests, interfaces, conventions that must not break).
+4. Note risks only if non-obvious.
+5. Set `needs_research` to true only if the solution requires knowledge you don't have. Most gaps don't.
+6. Complexity: `low` = single concern, mechanical. `medium` = multiple files, design choices. `high` = architectural.
+
+Match your depth to the gap's category and priority. A `cleanup/low` gap needs a few lines of findings, not a codebase survey.
+
+## Required Output Schema
+
+You MUST produce JSON conforming exactly to this schema. Every required field must be present.
+
+```json
+{{ output_schema }}
+```

package/templates/items/architecture.md

@@ -0,0 +1,33 @@
+{#-
+  Per-item macro for the `architecture` block (Plan 8 / per-item-macros wave 4).
+
+  Singleton kind: architecture holds one record per repository describing
+  modules, patterns, boundaries, and (optionally) compilation_pipeline /
+  execution_model / dispatch_design. The "per-item" rendering 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 the renderer-registry call convention; no helpers from
+  shared/render-helpers.md are needed.
+-#}
+
+{% macro render_architecture_item(a, depth=0) %}
+{% if a %}
+## Architecture
+{% if a.overview %}{{ a.overview }}
+{% endif %}
+{% if a.modules %}
+### Modules
+{% for m in a.modules %}- **{{ m.name }}** (`{{ m.file }}`{% if m.lines %}, {{ m.lines }} lines{% endif %}): {{ enforceBudget(m.responsibility, "architecture", "modules.items.responsibility") }}{% if m.dependencies %} — deps: {{ m.dependencies | join(", ") }}{% endif %}
+{% endfor %}{% endif %}
+{% if a.patterns %}
+### Patterns
+{% for p in a.patterns %}- **{{ p.name }}**: {{ enforceBudget(p.description, "architecture", "patterns.items.description") }}{% if p.used_in %} — used in: {{ p.used_in | join(", ") }}{% endif %}
+{% endfor %}{% endif %}
+{% if a.boundaries %}
+### Boundaries
+{% for b in a.boundaries %}- {{ b }}
+{% endfor %}{% endif %}
+{% endif %}
+{% endmacro %}

package/templates/items/conformance.md

@@ -0,0 +1,26 @@
+{#-
+  Per-item macro for the `conformance-reference` block (Plan 8 / per-item-macros wave 4).
+
+  Block schema: .project/schemas/conformance-reference.schema.json. The
+  block holds a name, scope, and principles[]. Each principle has nested
+  rules[]. The "per-item" granularity here is one principle (with its
+  rules) — the natural unit for prompt injection per the substrate spec.
+
+  No cross-block references — references are to source material (sources[]
+  at the block level), not to other block items. Depth parameter accepted
+  for renderer-registry shape-uniformity.
+
+  Companion whole-block macro:
+    render_conformance(data) in shared/macros.md emits the block-level
+    name + scope header, then iterates principles through this macro.
+-#}
+
+{% macro render_conformance_principle(p, depth=0) %}
+{% if p %}
+### {{ p.id }}: {{ p.name }}
+{% if p.description %}{{ enforceBudget(p.description, "conformance-reference", "principles.items.description") }}{% endif %}
+{% for r in p.rules %}- **{{ r.id }}**: {{ enforceBudget(r.rule, "conformance-reference", "principles.items.rules.items.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 %}
+{% endif %}
+{% endmacro %}

package/templates/items/conventions.md

@@ -0,0 +1,19 @@
+{#-
+  Per-item macro for the `conventions` block (Plan 8 / per-item-macros wave 4).
+
+  Block schema: .project/schemas/conventions.schema.json. Each item is one
+  rule object inside data.rules[] (id, description, enforcement, severity).
+
+  No cross-block references — conventions are leaf rules. Depth parameter
+  accepted for shape-uniformity; reserved for future schema additions.
+
+  Companion whole-block macro:
+    render_conventions(data) in shared/macros.md emits the test_conventions
+    and lint_command/lint_scope header fields once, then iterates rules
+    through this macro.
+-#}
+
+{% macro render_convention(rule, depth=0) %}
+{% if rule %}- **{{ rule.id }}** [{{ rule.severity }}, {{ rule.enforcement }}]: {{ enforceBudget(rule.description, "conventions", "rules.items.description") }}
+{% endif %}
+{% endmacro %}

package/templates/items/decisions.md

@@ -0,0 +1,47 @@
+{#-
+  Per-item macro for the `decisions` block.
+
+  Block schema: .project/schemas/decisions.schema.json (Plan 6 / per-item-macros wave 3).
+
+  Macro signature:
+    render_decision(dec, depth=0)
+      dec   — single decision object matching .decisions[*] in the schema
+      depth — integer recursion budget for cross-block reference inlining
+
+  Cross-block reference recursion (supersedes, superseded_by, related_findings,
+  related_features, related_gaps) 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.
+
+  References array (`references[]`):
+    Labelled pointers (label + optional path/lines/commit). NOT recursable —
+    references point to code paths, research docs, commit SHAs, external specs,
+    none of which are project blocks. Rendered inline as one bullet per ref.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_block, render_id_single_block, render_optional_scalar %}
+
+{% macro render_decision(dec, depth=0) %}
+ID: {{ dec.id }}
+Title: {{ dec.title }}
+Status: {{ dec.status }}
+Created by: {{ dec.created_by }}
+Created at: {{ dec.created_at }}
+{{ render_optional_scalar("Enacted by", dec.enacted_by) }}{{ render_optional_scalar("Enacted at", dec.enacted_at) }}
+Context:
+{{ enforceBudget(dec.context, "decisions", "decisions.items.context") }}
+
+Decision:
+{{ enforceBudget(dec.decision, "decisions", "decisions.items.decision") }}
+
+Consequences:
+{% if dec.consequences and dec.consequences | length > 0 %}{% for c in dec.consequences %}  - {{ enforceBudget(c, "decisions", "decisions.items.consequences.items") }}
+{% endfor %}{% else %}  (none)
+{% endif %}{% if dec.options_considered is defined %}Options considered:
+{% if dec.options_considered | length > 0 %}{% for opt in dec.options_considered %}  - {{ opt.label }}: {{ opt.description }}
+{% if opt.tradeoffs %}    Tradeoffs: {{ opt.tradeoffs }}
+{% endif %}{% if opt.rejected_reason %}    Rejected reason: {{ opt.rejected_reason }}
+{% endif %}{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}{{ render_id_list_block("Supersedes", dec.supersedes, depth) }}{{ render_id_single_block("Superseded by", dec.superseded_by, depth) }}{{ render_id_list_block("Related findings", dec.related_findings, depth) }}{{ render_id_list_block("Related features", dec.related_features, depth) }}{{ render_id_list_block("Related gaps", dec.related_gaps, depth) }}{% if dec.references is defined %}References:
+{% if dec.references | length > 0 %}{% for ref in dec.references %}  - {{ ref.label }}{% if ref.path %} — path: {{ ref.path }}{% if ref.lines %}:{{ ref.lines }}{% endif %}{% endif %}{% if ref.commit %} — commit: {{ ref.commit }}{% endif %}
+{% endfor %}{% else %}  (none)
+{% endif %}{% endif %}{% endmacro %}

package/templates/items/domain.md

@@ -0,0 +1,21 @@
+{#-
+  Per-item macro for the `domain` block (Plan 8 / per-item-macros wave 4).
+
+  Block schema: .project/schemas/domain.schema.json. Each item is one
+  knowledge entry inside data.entries[]. Required: id, title, content,
+  category. Optional: source, confidence, related_requirements (array of
+  REQ- IDs), tags.
+
+  Cross-block reference recursion (related_requirements) is delegated to
+  shared/render-helpers.md — see that file for the depth contract, ambient
+  globals, and empty-array convention.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_inline %}
+
+{% macro render_domain_entry(e, depth=0) %}
+{% if e %}- **{{ e.id }}** [{{ e.category }}]: {{ e.title }}
+  {{ enforceBudget(e.content, "domain", "entries.items.content") }}{% if e.tags %} — tags: {{ e.tags | join(", ") }}{% endif %}
+{% if e.source %}  Source: {{ e.source }}
+{% endif %}{% if e.confidence %}  Confidence: {{ e.confidence }}
+{% endif %}{{ render_id_list_inline("Related requirements", e.related_requirements, depth) }}{% endif %}
+{% endmacro %}

package/templates/items/features.md

@@ -0,0 +1,63 @@
+{#-
+  Per-item macro for the `features` block.
+
+  Block schema: .project/schemas/features.schema.json (Plan 7 / per-item-macros wave 4).
+
+  Cross-block reference recursion (dependencies, gates, blocks_resolved,
+  decisions) is delegated to shared/render-helpers.md — see that file for
+  the depth contract, ambient globals, and empty-array convention.
+
+  Nested embedded structures:
+    Each feature carries nested `stories[]` (with embedded `tasks[]`) and
+    `findings[]` (scoped-finding shape). These are NOT separate block kinds
+    — they are sub-shapes on the feature schema and have no per-item macro
+    of their own. They are rendered inline as sub-lists under the feature
+    body. Story-level `depends_on`/`gates` are rendered as bare-ID lists
+    (story IDs are scoped to the feature, not in the global index) and stay
+    inline because they use a deeper indent (4 spaces) than the helper
+    convention assumes.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_block, render_optional_scalar %}
+
+{% macro render_feature(feat, depth=0) %}
+ID: {{ feat.id }}
+Title: {{ feat.title }}
+Status: {{ feat.status }}
+Layer: {{ feat.layer }}
+Created by: {{ feat.created_by }}
+Created at: {{ feat.created_at }}
+{{ render_optional_scalar("Modified by", feat.modified_by) }}{{ render_optional_scalar("Modified at", feat.modified_at) }}{{ render_optional_scalar("Approved by", feat.approved_by) }}{{ render_optional_scalar("Approved at", feat.approved_at) }}
+Description:
+{{ enforceBudget(feat.description, "features", "features.items.description") }}
+
+{% if feat.motivation %}Motivation:
+{{ enforceBudget(feat.motivation, "features", "features.items.motivation") }}
+
+{% endif %}Acceptance criteria:
+{% if feat.acceptance_criteria and feat.acceptance_criteria | length > 0 %}{% for ac in feat.acceptance_criteria %}  - {{ ac }}
+{% endfor %}{% else %}  (none)
+{% endif %}{{ render_id_list_block("Dependencies", feat.dependencies, depth) }}{{ render_id_list_block("Gates", feat.gates, depth) }}{{ render_id_list_block("Blocks resolved", feat.blocks_resolved, depth) }}{{ render_id_list_block("Decisions", feat.decisions, depth) }}Stories:
+{% if feat.stories and feat.stories | length > 0 %}{% for s in feat.stories %}  - {{ s.id }} [{{ s.status }}] {{ s.title }}
+{% if s.description %}    Description: {{ enforceBudget(s.description, "features", "features.items.stories.items.description") }}
+{% endif %}{% if s.acceptance_criteria is defined %}    Acceptance criteria: {% if s.acceptance_criteria | length > 0 %}{% for ac in s.acceptance_criteria %}{{ ac }}{% if not loop.last %}; {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% if s.depends_on is defined %}    Depends on: {% if s.depends_on | length > 0 %}{% for dep in s.depends_on %}{{ dep }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% if s.gates is defined %}    Gates: {% if s.gates | length > 0 %}{% for g in s.gates %}{{ g }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}    Tasks:
+{% if s.tasks and s.tasks | length > 0 %}{% for t in s.tasks %}      - {{ t.id }} [{{ t.status }}] {{ t.title }}
+{% if t.description %}        Description: {{ t.description }}
+{% endif %}{% if t.files is defined %}        Files: {% if t.files | length > 0 %}{% for f in t.files %}{{ f }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% if t.acceptance %}        Acceptance: {{ t.acceptance }}
+{% endif %}{% if t.depends_on is defined %}        Depends on: {% if t.depends_on | length > 0 %}{% for dep in t.depends_on %}{{ dep }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% if t.assigned_to %}        Assigned to: {{ t.assigned_to }}
+{% endif %}{% endfor %}{% else %}      (none)
+{% endif %}{% endfor %}{% else %}  (none)
+{% endif %}Findings:
+{% if feat.findings and feat.findings | length > 0 %}{% for f in feat.findings %}  - {{ f.id }} [{{ f.severity }}/{{ f.state }}] reporter={{ f.reporter }} at={{ f.created_at }}
+    Description: {{ enforceBudget(f.description, "features", "features.items.findings.items.description") }}
+{% if f.evidence %}    Evidence: {{ f.evidence }}
+{% endif %}{% if f.category %}    Category: {{ f.category }}
+{% 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 %}{% endfor %}{% else %}  (none)
+{% endif %}{% endmacro %}

package/templates/items/framework-gaps.md

@@ -0,0 +1,43 @@
+{#-
+  Per-item macro for the `framework-gaps` block.
+
+  Block schema: .project/schemas/framework-gaps.schema.json (Plan 7 / per-item-macros wave 4).
+
+  Cross-block reference recursion (related_features, related_decisions,
+  related_issues) is delegated to shared/render-helpers.md — see that file
+  for the depth contract, ambient globals, and empty-array convention.
+
+  Naming note:
+    The canonical macro name is `render_framework_gap`. The legacy
+    `render_gap` macro lives in templates/shared/macros.md and retires
+    under Plan 8 (parallel). Plan 7 deliberately does NOT author
+    `render_gap` here.
+
+  Evidence array:
+    Each gap carries an embedded `evidence[]` of {file, lines, reference}
+    triples. These are file pointers, NOT block IDs — rendered inline as
+    sub-list, never recursed.
+-#}
+{% from "shared/render-helpers.md" import render_id_list_block, render_optional_scalar %}
+
+{% macro render_framework_gap(gap, depth=0) %}
+ID: {{ gap.id }}
+Title: {{ gap.title }}
+Status: {{ gap.status }}
+Package: {{ gap.package }}
+Created by: {{ gap.created_by }}
+Created at: {{ gap.created_at }}
+{{ render_optional_scalar("Priority", gap.priority) }}{{ render_optional_scalar("Layer", gap.layer) }}{{ render_optional_scalar("Canonical vocabulary", gap.canonical_vocabulary) }}{{ render_optional_scalar("Closed by", gap.closed_by) }}{{ render_optional_scalar("Closed at", gap.closed_at) }}
+Description:
+{{ enforceBudget(gap.description, "framework-gaps", "gaps.items.description") }}
+
+Impact:
+{{ enforceBudget(gap.impact, "framework-gaps", "gaps.items.impact") }}
+
+Proposed resolution:
+{{ enforceBudget(gap.proposed_resolution, "framework-gaps", "gaps.items.proposed_resolution") }}
+
+Evidence:
+{% if gap.evidence and gap.evidence | length > 0 %}{% for e in gap.evidence %}  - {{ e.file }}{% if e.lines %}:{{ e.lines }}{% endif %} — {{ enforceBudget(e.reference, "framework-gaps", "gaps.items.evidence.items.reference") }}
+{% endfor %}{% else %}  (none)
+{% endif %}{{ render_id_list_block("Related features", gap.related_features, depth) }}{{ render_id_list_block("Related decisions", gap.related_decisions, depth) }}{{ render_id_list_block("Related issues", gap.related_issues, depth) }}{% endmacro %}

package/templates/items/issues.md

@@ -0,0 +1,21 @@
+{#-
+  Per-item macro for the `issues` block (Plan 8 / per-item-macros wave 4).
+
+  Block schema: .project/schemas/issues.schema.json. Each item is one issue
+  inside data.issues[]. Required: id (^issue-\d{3}$), title, body, location,
+  status, category, priority, package. Optional: source, resolved_by.
+
+  No cross-block references in current schema — resolved_by is a free-form
+  commit reference, not a project-block ID. Depth parameter accepted for
+  renderer-registry shape-uniformity; reserved for future schema additions
+  (e.g., resolved_by_pr or related_decisions[]).
+-#}
+
+{% macro render_issue(i, depth=0) %}
+{% if i %}- **{{ i.id }}** [{{ i.priority }}, {{ i.status }}]: {{ i.title }}
+  {{ enforceBudget(i.body, "issues", "issues.items.body") }}{% if i.location %} — {{ i.location }}{% endif %}{% if i.package %} ({{ i.package }}){% endif %}
+{% if i.category %}  Category: {{ i.category }}
+{% endif %}{% if i.source %}  Source: {{ i.source }}
+{% endif %}{% if i.resolved_by %}  Resolved by: {{ i.resolved_by }}
+{% endif %}{% endif %}
+{% endmacro %}

package/templates/items/layer-plans.md

@@ -0,0 +1,50 @@
+{#-
+  Per-item macro for the `layer-plans` block.
+
+  Block schema: .project/schemas/layer-plans.schema.json (Plan 7 / per-item-macros wave 4).
+
+  Cross-block reference recursion (related_gaps, related_features,
+  related_decisions) is delegated to shared/render-helpers.md — see that
+  file for the depth contract, ambient globals, and empty-array convention.
+
+  Nested embedded structures:
+    Each plan carries `layers[]` (each with current_blocks/target_blocks
+    sub-arrays) and `migration_phases[]`. These are NOT separate block kinds
+    — they are sub-shapes on the plan schema and rendered inline. Phase
+    `depends_on` references are scoped to phase IDs within the same plan and
+    rendered as bare-ID lists (no recursion).
+-#}
+{% from "shared/render-helpers.md" import render_id_list_block %}
+
+{% macro render_layer_plan(plan, depth=0) %}
+ID: {{ plan.id }}
+Title: {{ plan.title }}
+Status: {{ plan.status }}
+Model: {{ plan.model }}
+Created by: {{ plan.created_by }}
+Created at: {{ plan.created_at }}
+{% if plan.description %}
+Description:
+{{ enforceBudget(plan.description, "layer-plans", "plans.items.description") }}
+
+{% endif %}Layers:
+{% if plan.layers and plan.layers | length > 0 %}{% for l in plan.layers %}  - {{ l.id }}: {{ l.name }}
+    Purpose: {{ enforceBudget(l.purpose, "layer-plans", "plans.items.layers.items.purpose") }}
+{% if l.canonical_vocabulary %}    Canonical vocabulary: {{ l.canonical_vocabulary }}
+{% endif %}{% if l.lifetime %}    Lifetime: {{ l.lifetime }}
+{% endif %}{% if l.ownership_principle %}    Ownership principle: {{ enforceBudget(l.ownership_principle, "layer-plans", "plans.items.layers.items.ownership_principle") }}
+{% endif %}    Current blocks: {% if l.current_blocks | length > 0 %}{% for cb in l.current_blocks %}{{ cb }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+    Target blocks:
+{% if l.target_blocks and l.target_blocks | length > 0 %}{% for tb in l.target_blocks %}      - {{ tb.name }} (shape: {{ tb.shape }}){% if tb.notes %} — {{ tb.notes }}{% endif %}
+{% endfor %}{% else %}      (none)
+{% endif %}{% endfor %}{% else %}  (none)
+{% endif %}Migration phases:
+{% if plan.migration_phases and plan.migration_phases | length > 0 %}{% for p in plan.migration_phases %}  - {{ p.id }}: {{ p.name }}{% if p.status %} [{{ p.status }}]{% endif %}
+    Description: {{ enforceBudget(p.description, "layer-plans", "plans.items.migration_phases.items.description") }}
+    Depends on: {% if p.depends_on | length > 0 %}{% for dep in p.depends_on %}{{ dep }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+    Exit criteria:
+{% if p.exit_criteria | length > 0 %}{% for ec in p.exit_criteria %}      - {{ enforceBudget(ec, "layer-plans", "plans.items.migration_phases.items.exit_criteria.items") }}
+{% endfor %}{% else %}      (none)
+{% endif %}{% if p.produces is defined %}    Produces: {% if p.produces | length > 0 %}{% for pr in p.produces %}{{ pr }}{% if not loop.last %}, {% endif %}{% endfor %}{% else %}(none){% endif %}
+{% endif %}{% endfor %}{% else %}  (none)
+{% endif %}{{ render_id_list_block("Related gaps", plan.related_gaps, depth) }}{{ render_id_list_block("Related features", plan.related_features, depth) }}{{ render_id_list_block("Related decisions", plan.related_decisions, depth) }}{% endmacro %}

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 %}