@benzotti/jdi 0.1.46

package/framework/components/execution/CodebaseContext.md

@@ -0,0 +1,36 @@
+# CodebaseContext Component
+
+Cache-first codebase context loading. Reads existing analysis — never spawns mapper automatically.
+
+---
+
+## Cache-First Loading
+
+1. If `.jdi/codebase/SUMMARY.md` exists → **read it directly** (regardless of age)
+2. If `.jdi/codebase/CONVENTIONS.md` exists → read it when writing code
+3. If neither exists → **inform user** to run `/jdi:map-codebase` first, then proceed without codebase context
+
+**Never spawn codebase mapper automatically.** The mapper is expensive (~30% of session budget). Only run it via explicit `/jdi:map-codebase` command.
+
+**Skip entirely if:** `--skip-codebase` flag is present in command arguments.
+
+---
+
+## Context Files
+
+| File | Purpose | When to Read |
+|------|---------|--------------|
+| `.jdi/codebase/SUMMARY.md` | Architecture overview, file locations, tech stack | Always (if exists) |
+| `.jdi/codebase/CONVENTIONS.md` | Coding standards (mapper output only) | When writing code (if exists) |
+| `.claude/rules/*.md` | Auto-loaded patterns (no explicit read needed) | Automatic |
+| `.jdi/config/state.yaml` | Current phase, plan, position | Always |
+
+---
+
+## Usage in Commands
+
+```
+<JDI:CodebaseContext />
+```
+
+This component reads cached context files. If no codebase analysis exists, it proceeds without it — agents can still analyse relevant source files directly.

package/framework/components/execution/Commit.md

@@ -0,0 +1,121 @@
+---
+name: Commit
+category: execution
+description: Create atomic commits with proper formatting and state tracking
+params:
+  - name: scope
+    type: string
+    required: false
+    default: "task"
+    options: ["task", "plan", "phase", "docs", "fix"]
+    description: What level of work is being committed
+  - name: type
+    type: string
+    required: false
+    default: null
+    options: ["feat", "fix", "refactor", "docs", "test", "chore", "perf", "style"]
+    description: Override commit type (auto-detected if not provided)
+  - name: files
+    type: array
+    required: false
+    default: null
+    description: Specific files to stage (auto-detected if not provided)
+---
+
+# Commit
+
+Create an atomic commit with proper formatting, staging, and state tracking.
+
+---
+
+## Default Behaviour
+
+When invoked as `<JDI:Commit />`:
+
+1. **Check for changes** — `git status --porcelain`. If none, skip.
+
+2. **Identify modified files** — Parse git status, group by change type.
+
+3. **Determine commit type** — `feat` (new), `fix` (bug), `refactor` (cleanup), `docs` (documentation), `test` (tests). Override with `type` param.
+
+4. **Stage files individually**
+   ```bash
+   git add path/to/file1
+   git add path/to/file2
+   ```
+   **NEVER** use `git add .` or `git add -A`
+
+   **EXCLUDED DIRECTORIES** (never stage):
+   - `.worktrees/**` — Git worktrees
+   - `.jdi/**` — JDI runtime state
+
+   ```bash
+   if [[ "$file" == .worktrees/* ]] || [[ "$file" == .jdi/* ]]; then
+     echo "SKIP (excluded): $file"
+     continue
+   fi
+   ```
+
+5. **Create commit message** — Use <JDI:Commit:MessageFormat />
+
+6. **Execute commit**
+   ```bash
+   git commit -m "$(cat <<'EOF'
+   {message}
+   EOF
+   )"
+   ```
+
+7. **Record commit hash** — `git rev-parse --short HEAD`
+
+8. **Update state** — Add commit to `state.yaml` session_commits array.
+
+---
+
+<section name="MessageFormat">
+
+## Message Format
+
+```
+{type}({scope}): {description}
+
+- {change 1}
+- {change 2}
+- {change 3}
+```
+
+### Type Selection
+
+| Type | When to Use |
+|------|-------------|
+| `feat` | New feature, endpoint, component |
+| `fix` | Bug fix, error correction |
+| `test` | Test-only changes |
+| `refactor` | Code cleanup, no behaviour change |
+| `perf` | Performance improvement |
+| `docs` | Documentation changes |
+| `style` | Formatting, linting fixes |
+| `chore` | Config, tooling, dependencies |
+
+### Rules
+- **Scope**: In a plan: `{phase}-{plan}` (e.g., `01-02`). Standalone: feature name or file area.
+- **Description**: Imperative mood, no capital start, no period, max 72 chars.
+- **Body**: 3-5 bullet points of WHAT changed.
+
+</section>
+
+---
+
+## Scope Reference
+
+| Scope | Message Format |
+|-------|----------------|
+| `task` | `{type}({phase}-{plan}): task {N} - {desc}` |
+| `plan` | `docs({phase}-{plan}): complete {plan-name}` |
+| `phase` | `docs({phase}): complete {phase-name}` |
+| `docs` | `docs: {description}` |
+| `fix` | `fix: {description}` |
+
+## State Updates
+
+After commit: append to `commits.session_commits` in state.yaml, update `last_commit_hash`. Append to `implementation.files_modified` in variables.yaml.

package/framework/components/execution/Verify.md

@@ -0,0 +1,140 @@
+---
+name: Verify
+category: execution
+description: Verify completion of tasks, plans, phases, or requirements
+params:
+  - name: scope
+    type: string
+    required: false
+    options: ["task", "plan", "phase", "requirements"]
+    default: "task"
+    description: What level to verify
+  - name: strict
+    type: boolean
+    required: false
+    default: false
+    description: Fail on any unmet criteria (vs warn)
+  - name: include_tests
+    type: boolean
+    required: false
+    default: true
+    description: Run tests as part of verification
+---
+
+# Verify
+
+Verify completion of work at various levels of granularity.
+
+---
+
+## Default Behaviour
+
+When invoked as `<JDI:Verify />`:
+
+1. **Determine scope** — Check current position from state.yaml, default to task-level
+2. **Load verification criteria** — task: PLAN.md verification section; plan: PLAN.md success_criteria; phase: ROADMAP.yaml must_haves
+3. **Execute verification** — Run each check, record pass/fail
+4. **Report results** — Output summary, update state
+
+---
+
+<section name="Task">
+
+## Task Verification (`scope="task"`)
+
+1. **Load task verification criteria** from PLAN.md `**Verification:**` checklist
+2. **Execute each check**: file existence, code patterns, test gates (see TestRunner), manual inspection
+3. **Load done criteria** from `**Done when:**`
+4. **Report result**:
+   ```markdown
+   ## Task Verification: Task {N}
+   **Status:** PASS | FAIL
+
+   ### Verification Checks
+   - [x] {check 1} - PASS
+   - [ ] {check 2} - FAIL: {reason}
+
+   ### Done Criteria
+   - [x] {criterion} - Met
+
+   ### Issues
+   - {issue description if any}
+   ```
+
+</section>
+
+---
+
+<section name="Plan">
+
+## Plan Verification (`scope="plan"`)
+
+1. **Verify all tasks complete** — check status and commits
+2. **Load plan success criteria** from `<success_criteria>` block
+3. **Execute plan-level checks** — test suite, lint/type errors, integration points
+4. **Generate SUMMARY.md preview** — draft with deviations
+5. **Report result**:
+   ```markdown
+   ## Plan Verification: {phase}-{plan}
+   **Status:** PASS | FAIL
+
+   ### Task Completion
+   - [x] Task 1: {name} - {commit}
+
+   ### Success Criteria
+   - [x] {criterion 1} - Met
+   - [ ] {criterion 2} - NOT MET: {reason}
+
+   ### Tests
+   - Suite: {test suite} | Result: {pass/fail} | Coverage: {percentage}
+
+   ### Ready for SUMMARY.md: YES | NO
+   ```
+
+</section>
+
+---
+
+## Advanced Verification (Phase & Requirements)
+
+For `scope="phase"` or `scope="requirements"`, load `<JDI:VerifyAdvanced />`.
+
+---
+
+<section name="TestRunner">
+
+## Test Execution (`include_tests="true"`)
+
+1. **Detect changed files**
+   ```bash
+   # Task-level
+   git diff --cached --name-only
+   git diff --name-only
+   # Plan-level
+   git diff master --name-only
+   ```
+
+2. **Backend test gate (MANDATORY if ANY `*.php` files changed)**
+   ```bash
+   composer test
+   ```
+   If fails: verification FAILS. Do not proceed. Fix tests first.
+
+3. **Frontend tests (if `*.ts`, `*.tsx`, `*.js`, `*.jsx` changed)**
+   ```bash
+   bun run test:vitest
+   ```
+
+4. **Parse results** — total, passed, failed, skipped, coverage
+
+5. **Report**: For each stack (Backend/Frontend), include: ran (yes/no), command, result, counts, and any failed test details.
+
+</section>
+
+---
+
+## State Updates
+
+After verification, set `position.status` to `verified` or `verification_failed`. If gaps found, add to `blockers` array with `type: verification_gap`.
+
+Gap severity: Critical (goal blocked → closure plan), High (requirement unmet → targeted fix), Medium (partially met → note), Low (enhancement → document).

package/framework/components/execution/VerifyAdvanced.md

@@ -0,0 +1,43 @@
+---
+name: VerifyAdvanced
+category: execution
+description: Advanced verification for phase and requirements scope
+---
+
+# VerifyAdvanced
+
+Lazy-loaded verification for `scope="phase"` and `scope="requirements"`. See `<JDI:Verify />` for task and plan verification.
+
+---
+
+<section name="Phase">
+
+## Phase Verification
+
+When `scope="phase"`:
+
+1. **Verify all plans complete** — Check SUMMARY.md exists for each plan, verify success criteria met
+2. **Load phase must_haves from ROADMAP.yaml**
+3. **Verify against codebase (not claims)** — Actually check the codebase, run the functionality
+4. **Create VERIFICATION.md** with must-haves status table, plans completed, gaps found, human verification needed
+5. **Route by status:**
+   - `PASSED` → Continue to next phase
+   - `GAPS_FOUND` → Create gap closure plans
+   - `HUMAN_NEEDED` → Present checklist to user
+
+</section>
+
+---
+
+<section name="Requirements">
+
+## Requirements Verification
+
+When `scope="requirements"`:
+
+1. **Load REQUIREMENTS.yaml** — Get all v1 requirements with REQ-IDs
+2. **For each requirement** — Find which phase/plan claimed to implement it, verify implementation exists, check acceptance criteria
+3. **Cross-reference evidence** — Link to test files, code implementing the requirement, note partial implementations
+4. **Generate report** with total/verified/failed/not-implemented counts, verification results table, failed requirements details, recommendations
+
+</section>

package/framework/components/meta/AgentBase.md

@@ -0,0 +1,121 @@
+# AgentBase Component
+
+Standards inherited by all JDI agents via `<JDI:AgentBase />`. Default loads Core only.
+
+## Standards
+
+- Use **Australian English** spelling in all outputs.
+- Follow `CLAUDE.md` and `.claude/rules/` conventions.
+- Read `.jdi/config/state.yaml` once at task start for context. Do NOT update state.yaml for status transitions — the framework handles this. Only use state.yaml to record decisions, deviations, or blockers via `<JDI:StateUpdate />`.
+- Use the Read tool before editing any file.
+- Batch file reads: issue all Read calls in a single turn rather than sequentially.
+- Batch git operations: combine related commands into a single Bash call where possible.
+
+## Budget Discipline
+
+You have a finite per-invocation budget (tokens, tool calls, wall time). Long runs can be terminated mid-task before you produce your final report. To survive:
+
+1. **Batch reads in parallel** — one turn with all Read calls, not sequential.
+2. **Cap exploration** — read only the files your spawn prompt names. If more are needed, report what you need and stop rather than wandering.
+3. **Write fixes before verifying** — Edit calls persist even if you are later truncated. Save the report for last.
+4. **Short reports (<400 words)** — terse file list + one sentence per change. Long formal reports are where truncation bites.
+5. **One concern per invocation** — address what was asked, do not expand scope.
+6. **Don't re-read files you just edited** — the harness tracks state.
+
+If your work exceeds one invocation, complete what you can, return a progress report naming exactly what remains, and let the orchestrator re-spawn you.
+
+## Component Resolution
+
+When a spec contains `<JDI:*>` tags:
+1. Read the file from `.jdi/framework/components/` (execution/, planning/, quality/, meta/).
+2. If a section is specified (`<JDI:X:Section />`), execute only that section.
+3. Apply tag parameters as constraints. Return to agent spec and continue.
+
+If your spec has a `requires_components` frontmatter field, read ALL listed components before starting execution.
+
+Do NOT skip `<JDI:*>` tags — they contain essential instructions.
+
+## Activation Protocol
+
+On activation, announce and begin immediately:
+```
+You are now active as {agent-name}. {Action verb} as requested.
+```
+
+## Structured Returns
+
+Return a YAML block with `status`, agent-specific fields, and `next_action` after all work is complete.
+
+## Boundaries
+
+- **Will Do**: Actions within agent responsibility. Prioritise these.
+- **Will Not**: Actions outside scope. Delegate or escalate, never attempt.
+
+---
+
+<section name="Sandbox">
+
+## Sandbox Awareness
+
+You run in a sandboxed environment. Key constraints:
+
+| Operation | Tool / Method | Persists? | Notes |
+|-----------|--------------|-----------|-------|
+| Edit existing files | Edit tool | **Yes** | Primary way to modify code |
+| Delete files | Bash `rm` | **Yes** | Destructive — use with care |
+| Create new files | Write tool / Bash `cat >` | **No** | Silently fails — report in `files_to_create` |
+| Git commits | Bash `git commit` | **No** | Silently fails — report in `commits_pending` |
+| Read files | Read tool | **Yes** | Works reliably |
+| Run commands | Bash tool | **Yes** | Output is real; side-effects vary |
+
+**Key Rules:**
+1. **NEVER attempt `git commit`** — it will appear to succeed but produces no real commit.
+2. **NEVER create new files** via Write tool or Bash redirection — they will not persist.
+3. **ALWAYS use the Edit tool** to modify existing files.
+4. **Report pending work** in structured returns using `files_to_create` and `commits_pending`.
+
+### Structured Returns for Sandbox-Limited Operations
+
+```yaml
+files_to_create:
+  - path: "path/to/new/file.md"
+    content: |
+      Full file content here...
+files_modified:
+  - path/to/edited/file1.ts
+commits_pending:
+  - message: |
+      feat(01-01-T1): implement feature X
+    files:
+      - path/to/modified/file1.ts
+```
+
+### Orchestrator Post-Agent Handling
+
+After a sandboxed agent completes, the orchestrator must:
+1. Create files from `files_to_create` using Write tool
+2. Execute commits from `commits_pending` via `git add` + `git commit`
+3. Record real commit hashes in `.jdi/config/state.yaml`
+
+</section>
+
+---
+
+<section name="TeamMode">
+
+## Communication (Team Mode)
+
+When operating within an Agent Team (spawned by coordinator):
+
+1. **Claim tasks**: Call TaskList, find tasks assigned to you
+2. **Execute**: Read task description, implement using Edit tool
+3. **Report**: SendMessage to coordinator with structured return (include `files_modified`, `files_to_create`, `commits_pending`)
+4. **Complete**: TaskUpdate(status: "completed") AFTER sending results
+5. **Next**: Check TaskList for more assigned tasks. If none, go idle.
+
+**Team Mode Rules:**
+- NEVER write to state.yaml (coordinator handles this)
+- ALWAYS SendMessage results to coordinator before TaskUpdate(completed)
+- Use **SendMessage** to communicate — plain text is not visible to teammates.
+
+</section>