@davidorex/pi-jit-agents 0.14.6 → 0.28.0

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

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/phase-author/task.md

@@ -0,0 +1,82 @@
+## Intent
+
+{{ intent }}
+
+## Existing Phases
+
+{% for phase in phases %}
+- Phase {{ phase.number }}: {{ phase.name }} ({{ phase.status }})
+{% endfor %}
+
+{% if architecture and architecture.modules %}
+## Current Architecture
+
+{% for module in architecture.modules %}
+- **{{ module.name }}** ({{ module.file }}, {{ module.lines }} lines): {{ module.responsibility }}
+{% endfor %}
+
+{% if architecture.compilation_pipeline %}
+### Compilation Pipeline
+{% for stage in architecture.compilation_pipeline %}
+{{ loop.index }}. **{{ stage.stage }}**: {{ stage.description }}
+{% endfor %}
+{% endif %}
+{% endif %}
+
+{% if conventions and conventions.rules %}
+## Conventions
+
+{% for rule in conventions.rules %}
+- {{ rule.id }}: {{ rule.description }} ({{ rule.enforcement }})
+{% endfor %}
+{% endif %}
+
+{% if gaps and gaps.gaps %}
+## Current Gaps
+
+{% for gap in gaps.gaps %}
+{% if gap.status == "open" %}
+- [{{ gap.priority }}] {{ gap.id }}: {{ gap.description }}
+{% endif %}
+{% endfor %}
+{% endif %}
+
+{% if inventory %}
+## Current Inventory
+
+{% if inventory.step_types %}- Step types: {{ inventory.step_types | length }}
+{% endif %}{% if inventory.agent_specs %}- Agent specs: {{ inventory.agent_specs | length }}
+{% endif %}{% if inventory.schemas %}- Schemas: {{ inventory.schemas | length }}
+{% endif %}{% if inventory.test_count is defined %}- Tests: {{ inventory.test_count }}
+{% endif %}{% endif %}
+
+## Instructions
+
+Convert the intent above into a structured phase spec. Read the codebase to understand what exists and what the intent requires.
+
+1. **Determine the phase number** — next after the highest existing phase number
+2. **Write a clear intent statement** — what this phase accomplishes and why
+3. **Define success criteria** — each with a verify_method:
+   - `command`: can be verified by running a shell command (test suite, grep, validate)
+   - `inspect`: requires reading files and assessing content
+   - `human`: requires human judgment
+4. **Decompose into specs** — each spec is a focused unit of work:
+   - Sequential numbering continuing from the last spec in the previous phase
+   - Clear intent per spec
+   - Concrete acceptance criteria (strings, each independently checkable)
+   - Specs should be ordered by dependency — earlier specs don't depend on later ones
+5. **Identify dependencies** — which phase numbers this phase depends on
+6. **List artifacts produced** — file paths this phase will create or modify
+
+### Sizing guidance
+
+- Each spec should be completable by one agent in one context window
+- If a spec needs more than ~5 files changed, split it
+- If a spec has more than ~5 acceptance criteria, it might be doing too much
+- Group related changes (e.g., schema + instance + validation test = one spec)
+
+### Cross-reference gaps
+
+Check if any existing open gaps are addressed by this phase. If so, note that in the spec intent — the gap can be marked resolved when the spec completes.
+
+Produce a JSON object conforming to the phase schema.

package/templates/plan-creator/task.md

@@ -0,0 +1,143 @@
+## Project Identity
+
+**Name:** {{ project.name }}
+**Description:** {{ project.description }}
+**Core Value:** {{ project.core_value }}
+**Status:** {{ project.status }}
+{% if project.stack %}
+
+### Stack
+{% for item in project.stack %}
+- {{ item }}
+{% endfor %}
+{% endif %}
+
+## Requirements Summary
+
+{% for req in requirements.requirements %}
+{% if req.priority == "must" %}
+- **{{ req.id }}** [must/{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+{% for req in requirements.requirements %}
+{% if req.priority == "should" %}
+- **{{ req.id }}** [should/{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+{% for req in requirements.requirements %}
+{% if req.priority == "could" %}
+- **{{ req.id }}** [could/{{ req.type }}]: {{ req.description }}
+{% endif %}
+{% endfor %}
+
+## Architecture
+
+**Overview:** {{ architecture.overview }}
+
+### Modules
+{% for module in architecture.modules %}
+- **{{ module.name }}** (`{{ module.file }}`): {{ module.responsibility }}{% if module.dependencies %} [depends: {{ module.dependencies | join(", ") }}]{% endif %}
+{% endfor %}
+
+### Patterns
+{% for pattern in architecture.patterns %}
+- **{{ pattern.name }}**: {{ pattern.description }} (used in: {{ pattern.used_in | join(", ") }})
+{% endfor %}
+
+### Boundaries
+{% for boundary in architecture.boundaries %}
+- {{ boundary }}
+{% endfor %}
+
+{% if existing_files %}
+## Existing Project Files
+
+The project directory already contains these files:
+{% for file in existing_files %}
+- {{ file }}
+{% endfor %}
+
+Account for existing structure — do not plan to recreate files that already exist unless they need modification.
+{% endif %}
+
+## Instructions
+
+Create implementation phases and tasks that build this project incrementally. The plan should take the project from its current state ({{ project.status }}) to a working system that satisfies all "must" requirements and addresses "should" requirements.
+
+### Phase guidelines
+
+1. **Phase 1** — Foundation: project structure, core module scaffolding, configuration, initial tests
+2. **Phase 2+** — Layer functionality in priority order: "must" requirements first, then "should"
+3. **Final phase** — Integration, documentation, and verification
+4. Each phase should represent a meaningful milestone — the project is more capable after each phase
+5. A phase with more than 8-10 tasks is likely too large — split it
+
+### For each phase, provide:
+
+- **number** — sequential starting at 1
+- **name** — short descriptive name
+- **intent** — what this phase accomplishes and why it comes at this point
+- **goal** — what is true after this phase that was not true before
+- **status** — `"planned"`
+- **success_criteria** — array of `{ criterion, verify_method }` (verify_method: "command", "inspect", or "test")
+- **dependencies** — array of phase numbers this depends on (empty for phase 1)
+- **inputs** — what this phase needs from prior phases or external sources
+- **outputs** — what this phase produces for later phases or users
+
+### For each task, provide:
+
+- **id** — unique, formatted as T-001, T-002, etc.
+- **description** — clear statement of what to do
+- **status** — `"planned"`
+- **phase** — phase number this belongs to
+- **files** — array of file paths this task creates or modifies
+- **acceptance_criteria** — array of specific, verifiable statements
+- **depends_on** — array of task IDs this depends on (empty if none)
+- **notes** — optional: any implementation guidance or caveats
+
+### Task sizing
+
+- Each task should be completable by one agent in one context window
+- A task touching more than 3-5 files likely needs splitting
+- A task with more than 5 acceptance criteria may be doing too much
+- Group related changes: schema + implementation + test = one task when files are few
+
+### Traceability
+
+- Every "must" requirement should be addressed by at least one task
+- Every task's files should map to at least one architecture module
+- Note requirement IDs in task descriptions or notes where the mapping is clear
+
+### Output format
+
+Produce a single JSON object with two arrays:
+
+```json
+{
+  "phases": [
+    {
+      "number": 1,
+      "name": "string",
+      "intent": "string",
+      "goal": "string",
+      "status": "planned",
+      "success_criteria": [{ "criterion": "string", "verify_method": "command" }],
+      "dependencies": [],
+      "inputs": ["string"],
+      "outputs": ["string"]
+    }
+  ],
+  "tasks": [
+    {
+      "id": "T-001",
+      "description": "string",
+      "status": "planned",
+      "phase": 1,
+      "files": ["src/file.ts"],
+      "acceptance_criteria": ["string"],
+      "depends_on": [],
+      "notes": "optional string"
+    }
+  ]
+}
+```

package/templates/plan-decomposer/task.md

@@ -0,0 +1,46 @@
+## Phase: {{ phase.name }}
+
+### Intent
+{{ phase.intent }}
+
+### Success Criteria
+{% for criterion in phase.success_criteria %}
+- {{ criterion.criterion }} (verify: {{ criterion.verify_method }})
+{% endfor %}
+
+### Specs
+{% if phase.specs %}
+{% for spec in phase.specs %}
+- **{{ spec.id }}**: {{ spec.name }}
+{% endfor %}
+{% endif %}
+
+### Current Architecture
+{% 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
+
+Decompose this phase into implementation plans. Each plan should be a focused unit of work that one agent can complete in a single context window.
+
+Before creating plans:
+1. Read source files referenced in the architecture to understand existing patterns
+2. Identify logical boundaries — which specs or features are independent
+3. Determine which plans can run in parallel (independent file sets)
+
+For each plan, produce:
+- **name**: short identifier for the plan
+- **intent**: what this plan accomplishes and why
+- **tasks**: concrete list of things to do (create files, add tests, wire up)
+- **files_to_change**: paths that will be created or modified
+- **acceptance_criteria**: how to know the plan is done
+- **context_needed**: files or modules the implementing agent should read first
+- **parallel_group**: group name — plans in the same group can run concurrently (independent file sets get the same group; dependent plans get different groups)
+
+Output a JSON object with a `plans` array conforming to the plan-breakdown schema.