@tyroneross/build-loop 0.30.3

package/skills/defenseclaw-bridge/references/dc-config-mapping.md

@@ -0,0 +1,162 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# DefenseClaw Config Mapping
+
+Field-by-field mapping from each agent-builder template to the DefenseClaw config row(s) it produces. The bridge skill (`SKILL.md`) walks this mapping when generating `<project>/.defenseclaw/generated/`.
+
+**Canonical agent-builder template paths** (when the plugin is installed locally):
+
+- `~/dev/git-folder/agent-builder/plugin/references/templates/agentic-handoff/tool-contract.md`
+- `~/dev/git-folder/agent-builder/plugin/references/templates/agentic-handoff/agent-manifest.md`
+- `~/dev/git-folder/agent-builder/plugin/references/templates/agentic-handoff/guardrail.md`
+- `~/dev/git-folder/agent-builder/plugin/references/templates/agentic-handoff/system-boundary.md`
+- `~/dev/git-folder/agent-builder/plugin/references/templates/agentic-handoff/flow-topology.md`
+- `~/dev/git-folder/agent-builder/plugin/references/templates/agentic-handoff/role-card.md`
+
+When the plugin is not installed locally, the project's own copies of these templates (filled in for the build) are the input. Filename match drives the bridge; plugin presence is not required.
+
+## Mapping reference (DefenseClaw schema)
+
+DefenseClaw's three-pillar model — **Govern / Inspect / Prove** — drives the config layout. Each agent-builder field maps to one of:
+
+- **Govern** — admission control: scanner profiles, install-source policies, allow/block lists, OPA Rego policies on tool calls.
+- **Inspect** — runtime guardrails: rule-pack entries that fire pre-call (against the prompt) or post-call (against the model output / tool output).
+- **Prove** — audit: sink configuration (SQLite, JSONL, OTLP, Splunk HEC, webhook), retention, log fields.
+
+The mapping matrix below uses these three column tags. A row may produce config in more than one pillar; both are listed.
+
+## tool-contract.md → DefenseClaw
+
+| Agent-builder field | Pillar | DefenseClaw artifact / field | Notes |
+|---|---|---|---|
+| `tool_contract.tool_id` | Govern | `scanner-profile.yaml :: tools[].id` | Stable identifier; used as the policies/<id>.rego filename |
+| `tool_contract.tool_name` | Govern | `scanner-profile.yaml :: tools[].name` | Human-readable label only |
+| `tool_contract.purpose` | (none) | (none — context only) | Goes in generated README |
+| `tool_contract.type` (function / MCP / hosted / shell / browser / external_api / agent) | Govern | `scanner-profile.yaml :: tools[].surface` | Drives which scanners apply (e.g., shell tools always get CodeGuard injection scan) |
+| `tool_contract.allowed_agents` | Govern | `policies/<tool_id>.rego :: data.defenseclaw.tools.<tool_id>.allowed_agents` | Rego predicate; agent IDs from agent-manifest's `agents:` block |
+| `tool_contract.input_schema` | Govern + Inspect | `policies/<tool_id>.rego` (input validation) + `rule-packs/inspect.yaml` (pre-call schema check) | Schema check happens twice — admission-time deny + runtime-time block |
+| `tool_contract.output_schema` | Inspect | `rule-packs/inspect.yaml :: post-call rule for <tool_id>` | If the schema is violated post-call, the rule fires |
+| `tool_contract.allowed_actions` / `forbidden_actions` | Govern | `policies/<tool_id>.rego :: allowed_actions` / `forbidden_actions` | Rego sets, intersected at request time |
+| `tool_contract.permission_tier` (T0–T5) | Govern + Inspect | Drives default scanner intensity AND default approval rule | T0–T2 → minimal scan, no approval. T3 → write-action approval gate. T4 → external-comms approval. T5 → strong-approval + diff-preview required |
+| `tool_contract.auth_scope` | Govern | `policies/<tool_id>.rego :: auth_scope` | Identity propagation gate; bridge writes `TODO:` if scope is "ambient agent credentials" (likely ASI03 finding) |
+| `tool_contract.data_access_scope` | Govern | `policies/<tool_id>.rego :: data_scope` | Tenant boundary check |
+| `tool_contract.rate_limits` | Inspect | `rule-packs/inspect.yaml :: rate-limit rule for <tool_id>` | Backstop for LLM04 (DoS) |
+| `tool_contract.timeout` | Inspect | Same row as rate_limits | |
+| `tool_contract.side_effects` | Prove | `dc-config.yaml :: audit.side_effect_capture: true` if any tool declares side effects | Always-on audit when side effects exist |
+| `tool_contract.requires_human_approval` | Govern | `policies/<tool_id>.rego :: requires_approval = true` | Hard gate |
+| `tool_contract.approval_preview_fields` | Govern | `policies/<tool_id>.rego :: preview_fields` | Operator UI consumes this |
+| `tool_contract.rollback_strategy` | (none) | (none — context only, in README) | Operations concern, not config |
+| `tool_contract.audit_log_fields` | Prove | `dc-config.yaml :: audit.fields` | Union of all tools' audit fields |
+| `tool_contract.failure_modes` / `error_behavior` | Inspect | `rule-packs/inspect.yaml :: post-call error-shape rule` | Detect deviations from declared error shape |
+| `tool_contract.examples` / `test_cases` | (none) | (none — used by other build-loop phases, not DefenseClaw) | |
+
+## agent-manifest.md → DefenseClaw
+
+| Agent-builder field | Pillar | DefenseClaw artifact / field | Notes |
+|---|---|---|---|
+| `agent_manifest.name` / `version` | (top) | `dc-config.yaml :: project.name` / `project.version` | |
+| `agent_manifest.mission` / `north_star_metric` | (none) | (none — context only) | |
+| `agent_manifest.users` | Govern | `dc-config.yaml :: tenancy.users` | If multi-user, drives per-user audit scoping |
+| `agent_manifest.autonomy_level` (A0–A4) | Govern | `dc-config.yaml :: autonomy_default` | Higher autonomy → stricter default rules |
+| `agent_manifest.architecture_pattern` | (none) | (context in README) | |
+| `agent_manifest.sdk_choice` | Govern | `dc-config.yaml :: sdk_hooks` | Drives which fetch interceptor / proxy adapter to wire |
+| `agent_manifest.model_routes` | Inspect + Prove | `dc-config.yaml :: providers[]` (per route) | Auth headers (`X-DC-Target-URL`, `X-AI-Auth`, `X-DC-Auth`) — bridge writes `TODO:` placeholders |
+| `agent_manifest.tools[]` | Govern | Each tool walks `tool-contract.md` mapping | One-to-many: the manifest lists tools, each has its own contract |
+| `agent_manifest.memory.{working_state, session_memory, long_term_memory}` | Govern + Inspect | `scanner-profile.yaml :: memory_scanners` + `rule-packs/inspect.yaml :: memory_write_rules` | Long-term memory always gets ASI06 detection rules |
+| `agent_manifest.protocols.mcp` / `agent_manifest.protocols.a2a` | Govern | `scanner-profile.yaml :: mcp_servers[]` / `a2a_peers[]` | MCP servers get install-source check + signature verification (when available); A2A peers get TODO for signing (ASI07 gap) |
+| `agent_manifest.guardrails.{input, tool, output, handoff}` | Inspect | Each guardrail walks `guardrail.md` mapping | |
+| `agent_manifest.human_checkpoints` | Govern | `policies/checkpoints.rego` | Human-in-loop predicates |
+| `agent_manifest.evals` | (none) | (context) | |
+| `agent_manifest.observability` | Prove | `dc-config.yaml :: sinks` | Default: SQLite + JSONL; OTLP if `observability.otlp_endpoint` set |
+| `agent_manifest.deployment` | (none) | (context) | |
+| `agent_manifest.deactivation` | (none) | (context — kill-switch path noted in README) | |
+| `agent_manifest.agents[]` (per-agent registry) | Govern | `policies/agents.rego :: data.defenseclaw.agents` | Agent IDs, autonomy, allowed_tools, can_handoff_to — drives the A2A handoff allow-graph |
+| `agent_manifest.agents[].review_required` | Govern | Per-agent `policies/agent-<id>.rego :: review_required` | When true, all decisions of that agent route through human approval |
+| `agent_manifest.security_posture` (when present, per security-references rec) | Govern + Inspect + Prove | Top-level coverage attestation in `dc-config.yaml :: risk_coverage` | Mirrors the `risk_coverage` block from the agent manifest verbatim |
+
+## guardrail.md → DefenseClaw
+
+| Agent-builder field | Pillar | DefenseClaw artifact / field | Notes |
+|---|---|---|---|
+| `guardrail_id` | Inspect | `rule-packs/inspect.yaml :: rules[].id` | Stable ID |
+| `name` | Inspect | `rule-packs/inspect.yaml :: rules[].name` | Human-readable |
+| `applies_to` (agent IDs) | Inspect | `rule-packs/inspect.yaml :: rules[].applies_to_agents` | Filter — rule fires only when the active agent is in scope |
+| `trigger` | Inspect | `rule-packs/inspect.yaml :: rules[].trigger.regex` (or `llm_judge_prompt` if non-regex) | Bridge writes regex placeholder; project-specific patterns are TODO |
+| `check` | Inspect | `rule-packs/inspect.yaml :: rules[].check` | Multi-step check description; lifecycle_phase derived from semantics |
+| `action` | Inspect | `rule-packs/inspect.yaml :: rules[].action` | "block" / "redact" / "log" / "approve_required" |
+| `severity` (low / medium / high) | Inspect | `rule-packs/inspect.yaml :: rules[].severity` | Drives default mode: high → action mode (block); low → observe mode (log only) |
+| `escalation` | Govern | `policies/escalation.rego :: escalations` | When the guardrail hits, who gets paged |
+| (new field rec) `lifecycle_phase` | Inspect | `rule-packs/inspect.yaml :: rules[].lifecycle_phase` | Required: pre-call / post-call / in-tool / post-handoff |
+| (new field rec) `enforcement_type` | Inspect | `rule-packs/inspect.yaml :: rules[].enforcement_type` | regex / policy / llm-judge / external-service |
+| (new field rec) `mode` | Inspect | `rule-packs/inspect.yaml :: rules[].mode` | observe / action |
+| (new field rec) `mapped_owasp_risks` | Inspect + Prove | `rule-packs/inspect.yaml :: rules[].mapped_risks` AND `dc-config.yaml :: risk_coverage` rolls up | Cross-cite for audit |
+
+## system-boundary.md → DefenseClaw
+
+| Agent-builder field | Pillar | DefenseClaw artifact / field | Notes |
+|---|---|---|---|
+| `system_boundary.in_scope_tasks` | Govern | `dc-config.yaml :: sandbox.allowed_surfaces` | Allow-list driver for OpenShell sandbox |
+| `system_boundary.out_of_scope_tasks` | Govern | `dc-config.yaml :: sandbox.blocked_surfaces` | Block-list driver |
+| Other fields (mission, users) | (none) | (context only) | |
+
+The bridge writes a `TODO: OpenShell sandbox config — system-boundary is too coarse to drive a precise sandbox profile. Refine in-scope/out-of-scope to filesystem paths, allowed network destinations, allowed syscalls.` in the generated README.
+
+## flow-topology.md → DefenseClaw
+
+| Agent-builder field | Pillar | DefenseClaw artifact / field | Notes |
+|---|---|---|---|
+| Agent-to-agent edges (who can hand off to whom) | Govern | `policies/handoffs.rego :: allowed_handoffs` | Mirrors `agent_manifest.agents[].can_handoff_to` |
+| Tool-call edges (which agent calls which tool) | Govern | (already covered by tool-contract.allowed_agents) | Cross-check; mismatch with manifest is a finding |
+| External system edges | Govern | `policies/egress.rego :: allowed_destinations` | Outbound URL allow-list |
+
+If `flow-topology.md` describes A2A edges, the bridge writes a `TODO: ASI07 — A2A trust model is project-specific. DefenseClaw does not provide a built-in inter-agent message-signing layer. Consider per-edge signing keys + nonces. Document the A2A trust model here.` in the generated README.
+
+## role-card.md → DefenseClaw
+
+| Agent-builder field | Pillar | DefenseClaw artifact / field | Notes |
+|---|---|---|---|
+| Role's allowed_tools | Govern | Cross-check vs `agent_manifest.agents[].allowed_tools` | Mismatch is a finding (role cards drift) |
+| Role's autonomy | Govern | Cross-check vs `agent_manifest.agents[].autonomy_level` | Mismatch is a finding |
+| Role's review_required | Govern | Cross-check vs `agent_manifest.agents[].review_required` | Mismatch is a finding |
+
+Role cards are mostly cross-validated; they don't add new config rows of their own. When they drift from the manifest, the bridge surfaces this as a `TODO:` in the README so the project can reconcile.
+
+## Permission-tier (T0–T5) → DefenseClaw scanner intensity
+
+| Permission tier | Default scanner profile | Default approval rule |
+|---|---|---|
+| T0 (no tool access) | none | n/a |
+| T1 (read-only local) | minimal — schema-only | none |
+| T2 (read external) | minimal + supply-chain check | none if data is in scope |
+| T3 (write reversible) | full CodeGuard (secrets, dangerous exec, deserialization, weak crypto, injection) | preview / undo required |
+| T4 (external comms) | full CodeGuard + outbound URL allowlist + payload PII scan | human approval required |
+| T5 (irreversible / high impact) | full CodeGuard + diff-preview + dual-control | strong human approval required |
+
+T0 and T1 produce the most minimal rule sets; T4 and T5 produce the most aggressive. The bridge uses these defaults; projects can tighten per-tool by editing the generated config.
+
+## Cross-source matrix → DefenseClaw column
+
+For each row in `skills/security-methodology/references/cross-source-matrix.md`, the DefenseClaw column names the operational control. The bridge consults this column when picking which rule-pack entries to generate for a guardrail whose `mapped_owasp_risks` covers a given row.
+
+## Lossy fields (intentionally not mapped)
+
+| Field | Why not mapped |
+|---|---|
+| `tool_contract.examples` / `test_cases` | Used by build-loop's eval phase, not by runtime enforcement |
+| `agent_manifest.north_star_metric` / `mission` | Strategic context, not operational policy |
+| `agent_manifest.architecture_pattern` | Architecture description, not policy input |
+| `agent_manifest.deactivation` | Operations runbook, not enforcement config |
+| `system_boundary.users_served` (verbose narrative) | Used in agent-manifest.users + role-cards instead |
+| `role_card.background` / freeform narrative | Documentation, not policy |
+
+These fields are referenced in the generated `README.md` for context but do not drive any config row. Operators should still write them in the source artifacts — they're part of the design record even when DefenseClaw doesn't consume them.
+
+## When the schema drifts
+
+DefenseClaw's `dc-config.yaml` schema evolves. This mapping is pinned to the schema as of canon-write time (May 2026). When the schema changes:
+
+1. The bridge's generated `README.md` includes a `# Schema version: <pinned>` line.
+2. Operators deploying to a newer DefenseClaw should validate the generated spec against the current schema before running.
+3. Schema drift in DefenseClaw is the project's responsibility to track; the bridge does not auto-update.
+
+For the live schema and config reference, see `https://github.com/cisco-ai-defense/defenseclaw`.

package/skills/defenseclaw-bridge/references/output-format.md

@@ -0,0 +1,108 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Output Format
+
+Where the bridge writes generated DefenseClaw spec, what each file contains, and what guarantees the spec carries.
+
+## Output directory
+
+```
+<project>/.defenseclaw/generated/
+├── README.md                         # Generated explanation; lists inputs, mapping, TODOs
+├── dc-config.yaml                    # Top-level DefenseClaw config skeleton
+├── scanner-profile.yaml              # Govern pillar — admission scanners
+├── policies/                         # OPA Rego stubs
+│   ├── tool-<tool_id>.rego           # One per tool contract
+│   ├── agents.rego                   # Per-agent registry policies
+│   ├── handoffs.rego                 # A2A handoff allow-graph (when flow-topology present)
+│   ├── egress.rego                   # Outbound URL allow-list (when flow-topology present)
+│   ├── checkpoints.rego              # Human-in-loop predicates (when manifest declares them)
+│   └── escalation.rego               # Guardrail escalation paths
+├── rule-packs/
+│   └── inspect.yaml                  # Inspect pillar — pre/post-call rules
+└── suppressions.yaml                 # Empty stub with documentation
+```
+
+## Why `.defenseclaw/generated/`
+
+- **`.defenseclaw/`** is DefenseClaw's namespace per the user-preference in `~/.claude/CLAUDE.md`: every plugin/tool stores data under `.<toolname>/`. If DefenseClaw is also installed in the project, its runtime state lives in the same directory tree (`.defenseclaw/audit.sqlite`, etc.) but never under `generated/`.
+- **`generated/`** signals that everything inside is regeneratable from the source artifacts. Operators can `rm -rf .defenseclaw/generated/` and re-run the bridge; nothing in here is ground truth.
+- **No collision** with DefenseClaw runtime files. The bridge never writes to `.defenseclaw/audit.sqlite`, `.defenseclaw/incidents/`, or any other path DefenseClaw owns directly.
+
+## File guarantees
+
+### `dc-config.yaml`
+
+- Header comment names the input artifacts and the bridge version.
+- Top-level keys: `project`, `tenancy`, `autonomy_default`, `sdk_hooks`, `providers`, `sinks`, `audit`, `mode`, `risk_coverage`.
+- Default `mode: observe` (log-only). Operators flip to `mode: action` only after tuning.
+- Default `sinks` write to `.defenseclaw/audit.sqlite` and `.defenseclaw/audit.jsonl`. OTLP and Splunk HEC sinks added only when the manifest's `observability` block names them.
+- `risk_coverage` block mirrors the agent-manifest's `security_posture.risk_coverage` (when present); empty when not.
+- YAML-1.1 valid; `python3 -c "import yaml; yaml.safe_load(open('dc-config.yaml'))"` succeeds.
+
+### `scanner-profile.yaml`
+
+- Header comment names the input artifacts.
+- Top-level keys: `tools`, `mcp_servers`, `a2a_peers`, `memory_scanners`.
+- One `tools[]` entry per tool listed in agent-manifest. Surface (`function`/`MCP`/`hosted`/`shell`/`browser`/`external_api`/`agent`) drives default scanner set per the permission-tier table in `dc-config-mapping.md`.
+- `mcp_servers[]` entries always include `install_source_check: true` and `signature_verification: TODO`.
+- `a2a_peers[]` entries include `TODO: ASI07 — message-signing model not yet defined.`
+
+### `policies/<tool>.rego`
+
+- One file per tool contract, named `tool-<tool_id>.rego` (lowercase, dashes).
+- Package convention: `package defenseclaw.tools.<tool_id_dotted>`.
+- Always begins with `default allow = false` so missing rules deny.
+- Predicates: `allowed_agents`, `allowed_actions`, `forbidden_actions`, `auth_scope`, `data_scope`, `requires_approval`, `preview_fields`.
+- `TODO:` markers where project-specific predicates are required (e.g., "what argument values count as a high-impact write").
+- Parses with `opa parse` when OPA is installed locally (not required; nice-to-have).
+
+### `policies/agents.rego`, `policies/handoffs.rego`, `policies/egress.rego`, `policies/checkpoints.rego`, `policies/escalation.rego`
+
+- Generated only when the corresponding source artifact provides material (manifest's `agents:`, flow-topology, etc.).
+- Same conventions: `default allow = false`, `package defenseclaw.<concern>`.
+- Each is a thin policy with TODO predicates where project-specific logic is required.
+
+### `rule-packs/inspect.yaml`
+
+- One `rules[]` entry per guardrail in `guardrail.md`.
+- Required fields per rule: `id`, `name`, `applies_to_agents`, `lifecycle_phase`, `enforcement_type`, `mode`, `severity`, `mapped_risks`, `trigger`, `check`, `action`.
+- `trigger.regex` is `TODO:` placeholder by default unless the source guardrail's `trigger:` field is itself a regex (rare).
+- `mapped_risks` always present, even if just `["TODO: cite OWASP/ASI/NIST IDs"]`.
+
+### `suppressions.yaml`
+
+- Empty `suppressions: []` by default.
+- Documentation comments explain when to add: known false positives, scoped exemptions, sunset dates.
+- Operators are expected to fill this file in over time.
+
+### `README.md`
+
+The README is the operator's entry point. Required sections:
+
+1. **Inputs** — list every source artifact the bridge consumed, with timestamps.
+2. **Mapping summary** — concise table of "this source artifact produced these output rows".
+3. **Coverage attestation** — which OWASP/ASI/NIST risks have a generated control; which are gaps.
+4. **TODOs** — every `TODO:` marker in the generated files, listed with file:row references for follow-up.
+5. **Schema version** — pinned DefenseClaw schema version this output targets.
+6. **Limitations** — explicit list of what the bridge does not generate (live patterns, sandbox config, runtime auth headers, LLM-judge config).
+7. **How to deploy** — pointer at `https://github.com/cisco-ai-defense/defenseclaw`. The bridge does not install DefenseClaw; it only writes spec.
+
+## Idempotency
+
+- Re-running the bridge against unchanged source artifacts produces byte-identical output.
+- Re-running against changed source artifacts overwrites only the affected output files (the bridge tracks which file produced which output via the README's mapping table).
+- The bridge **never deletes** files in `.defenseclaw/generated/` that it didn't author. If the directory contains a hand-edited file the bridge doesn't recognize, it warns and leaves the file alone.
+
+## Failure modes
+
+- **Source artifact malformed** (YAML syntax error in tool-contract): bridge emits a clear error citing the artifact + line number, writes nothing, exits non-zero.
+- **Multiple tools share the same `tool_id`**: bridge errors. tool_id is a stable identifier; collisions are upstream defects.
+- **Manifest references a tool that has no contract file**: bridge writes `policies/tool-<id>.rego` with a `TODO: tool contract missing — fill in input/output schema before deploying.` placeholder and surfaces the gap in the README.
+- **Reference file missing** (`dc-config-mapping.md` or `cross-source-matrix.md`): bridge errors per the standalone-fallback rule in `SKILL.md`. No partial output.
+
+## What this output is not
+
+- **Not a working DefenseClaw install.** Operators must clone DefenseClaw, install its dependencies, point its config loader at the generated `dc-config.yaml`, fill in TODOs, and tune in `observe` mode before flipping to `action`.
+- **Not an audit deliverable.** The risk-coverage attestation in the README is generated from the manifest's declared coverage; it does not certify that controls actually catch what they claim.
+- **Not a replacement for project-specific security review.** The bridge generates spec; the security team reviews it. Generated spec without review is no better than no spec.

package/skills/handoff/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: handoff
+description: "Compose a complete, durable build-loop handoff document from the current run state, and optionally launch a fresh session with it injected. Use when crossing a context boundary (context limit, planned restart, worktree GC). Triggers: 'hand off', 'handoff', 'new session', 'context limit', 'restart', 'fresh session', '/build-loop:handoff'."
+user-invocable: true
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Build-Loop Handoff
+
+Compose a complete, durable handoff document from the current build-loop run state,
+then (optionally) launch a fresh session in the STABLE checkout with that document injected.
+
+## When to use
+
+- Context window approaching limit mid-build.
+- Planned restart at a session boundary (e.g. deploying a plugin update requires a restart).
+- A worktree about to be GC'd — extract state before the folder disappears.
+- Handing off work to a peer agent or co-developer.
+
+## What it composes
+
+The handoff doc has eight fixed sections (always the same order; absent data renders as "n/a"):
+
+| # | Section | Source |
+|---|---------|--------|
+| 1 | North Star (intent) | `.build-loop/intent.md` |
+| 2 | Current Goal | `.build-loop/goal.md` |
+| 3 | Phase + Live Checklist | `.build-loop/state.json` (execution + runs[]) |
+| 4 | Git State | `git status` + `git log` |
+| 5 | Queues | `followup/`, `backlog/`, `ux-queue/`, `issues/` |
+| 6 | Gotchas / Lessons | `.build-loop/feedback.md` |
+| 7 | Last Run Summary | `state.json.runs[-1]` |
+| 8 | Resume Instructions | generated (workdir, phase context) |
+
+## Usage — no flag (emit doc)
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/handoff --workdir "$PWD"
+```
+
+Prints the handoff doc to stdout. Pipe to a file or share directly.
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/handoff --workdir "$PWD" --output handoff.md
+```
+
+Writes to a file instead.
+
+```bash
+python3 ${CLAUDE_PLUGIN_ROOT}/scripts/handoff --workdir "$PWD" --json
+```
+
+Emits a JSON envelope `{document, sources, errors, ts}` for programmatic use.
+
+## Usage — `--launch` (fresh session)
+
+The command surface (`/build-loop:handoff --launch`) handles this. The skill provides
+the doc; the command layer handles host-specific launch.
+
+**What `--launch` does:**
+1. Compose the handoff doc from the CURRENT run state.
+2. Write it to `.build-loop/handoff-latest.md` in the STABLE checkout.
+3. Start a fresh host session at the STABLE checkout root (not the worktree).
+4. Inject the handoff doc so the new session opens with full context.
+
+**Host behavior:**
+
+| Host | Launch method | Handoff injection |
+|------|--------------|-------------------|
+| Claude Code | `claude --print` with doc as initial prompt prefix | Inline in opening message |
+| Codex | `codex` with `--context` flag or stdin | Depends on Codex version |
+| Unknown / unsupported | Emit doc + print instructions, exit 0 | Manual paste |
+
+The `--launch` path always writes `.build-loop/handoff-latest.md` regardless of host
+support — the doc is the primary deliverable; launch is a convenience.
+
+**Important:** launch always targets the STABLE checkout (`git worktree list` → the
+`[bare]` or main entry), not the current worktree. Worktrees may be GC'd before the
+new session starts.
+
+## KISS/DRY note
+
+`scripts/handoff/__main__.py` reads `.build-loop/` using only `json`, `pathlib`,
+and `subprocess` from the standard library — no new dependencies. It does NOT
+re-implement state parsing; it reads `state.json` directly at the same paths the
+orchestrator already writes. Tests: `scripts/handoff/test_handoff.py` (13 tests).
+
+## Host-agnostic design
+
+The skill provides **structured data + instructions**. The host coding agent's LLM
+interprets and acts on the handoff doc. No vendor-specific API calls. The `--launch`
+CLI path uses the host's own CLI, isolated in `commands/handoff.md`'s conditional
+block — the skill logic is identical across Claude Code, Codex, and future hosts.

package/skills/ibr-bridge/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: build-loop:ibr-bridge
+description: Routing bridge to the IBR plugin for UI visual verification. Build-loop prefers IBR `scan` / `scan_macos` when the IBR plugin is installed; otherwise falls back to build-loop's own `native-ax-driver` / `ui-validator`. Never falls back to nm/strings.
+version: 0.3.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# IBR Bridge (Primary-When-Present, Native-Fallback)
+
+Build-loop routes UI visual verification through IBR when the IBR plugin is installed, and through its own native verifiers when it isn't. There is no third path — `nm`/`strings`/`git grep` over symbols never satisfies the visual-evidence gate (enforced by `skills/build-loop/scanners/require-visual-evidence.mjs` at chunk-close and Phase 4-B).
+
+The previous "explicit-only" policy was reversed 2026-06-04 because it left the macOS path without a default visual verifier in projects that didn't have IBR — the symbol-only escape hatch then carried briefs past the (prose-only) verify mandate.
+
+## Routing rule
+
+At Phase 1 Assess, the orchestrator reads `state.json.availablePlugins.ibr` (populated by `detect-plugins.mjs`).
+
+| Build-loop need | Primary (when `availablePlugins.ibr == true`) | Fallback (when IBR absent) |
+|---|---|---|
+| Web UI verify | IBR `scan` against the dev-server route | `ui-validator` agent + browser/screenshot tooling |
+| macOS UI verify | IBR `scan_macos` against the running `.app` | `native-ax-driver` (`skills/native-ax-driver/`) pid-anchored AX-tree + screenshot |
+| iOS sim UI verify | IBR `scan` against the booted sim (when supported) | `xcrun simctl io booted screenshot` + `idb ui` for interaction |
+| Visual-evidence at chunk-close | Whichever of the above ran | (same) |
+
+Subagent dispatch briefs MAY name `IBR scan` / `scan_macos` as the verifier — BUT only after the orchestrator has confirmed `availablePlugins.ibr == true`. When it is false, the brief MUST name the native-fallback verifier instead (per the [ME] guardrail in `agents/build-orchestrator.md` §"Phase 3 Execute" — never name a tool the implementer can't reach).
+
+## Allowed scope
+
+When the bridge is the primary route (IBR present):
+- Run `scan` / `scan_macos` against the running app or dev-server route, capture the result envelope, and pass it forward as the chunk's `evidence_paths` / `verification` text.
+- Use IBR token / design-system checks as comparison input.
+- Run a project-authored `.ibr-test.json` suite.
+- Generate `.ibr-test.json` drafts only when the build's plan explicitly authorizes IBR test generation.
+
+When the bridge is the fallback route (IBR absent):
+- Skip with a one-line note (`ibr: not installed; falling back to native-ax-driver / ui-validator`); do NOT write to `.ibr/`.
+- Do NOT install or download IBR mid-build.
+
+## Forbidden
+
+- Do NOT fall back to `nm` / `strings` / `git grep` over compiled symbols as UI verification. The BL-1 gate (`scanners/require-visual-evidence.mjs`) rejects this with exit 2 and routes the chunk back to Iterate.
+- Do NOT invoke IBR viewer / dashboard / UI surfaces from build-loop.
+- Do NOT write `.ibr/` unless the build's plan or the user's request requires an IBR output directory.
+
+## Output contract
+
+The bridge returns results in the same envelope shape regardless of which route fired:
+
+```json
+{
+  "status": "ran | skipped | failed",
+  "route": "ibr | native | fallback-skipped",
+  "verifier": "scan_macos | scan | native-ax-driver | ui-validator | none",
+  "artifacts": ["path-or-url-or-pid-anchor"],
+  "verification": "<freeform text suitable for the BL-1 gate envelope>",
+  "findings": [{"severity": "info|warn|blocker", "message": "..."}]
+}
+```
+
+The orchestrator forwards `verification` and `artifacts` to the BL-1 gate envelope as the chunk's `verification` and `evidence_paths` fields.
+
+## Status: 0.3.0 (2026-06-04)
+
+- Reversed the explicit-only default. IBR is now the preferred primary when present; build-loop-owned `native-ax-driver` / `ui-validator` is the always-available fallback.
+- The bridge stays `user-invocable: false` because it's part of the orchestrator's verify-path routing, not a manual user command.
+- Canonical build-loop design and validation artifacts remain `.build-loop/app-contract/*`, `ui-validator` envelopes, and Review-G outputs whichever route fires.

package/skills/knowledge/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: knowledge
+description: Canonical build-loop-memory framework. Use when the user asks to "record a decision", "log an ADR", "write an MADR", "capture this choice", "regenerate the decisions index", "validate knowledge", "migrate feedback to decisions", or "recall <topic>". Active durable writes go to `~/dev/git-folder/build-loop-memory`; legacy `.episodic/` paths are migration/archive inputs only.
+user-invocable: true
+when_to_use: |
+  - User wants to record a substantive choice with rationale
+  - User asks to regenerate canonical decision indexes or validate decision files
+  - User asks to validate frontmatter or supersession links
+  - User asks to migrate `.build-loop/feedback.md` into MADR files
+  - User asks to migrate playbooks to `.procedural/`
+  - User asks to recall prior decisions on a topic (Phase 2 retrieval)
+  - Auto-capture (Phase 3) and consolidation (Phase 4) are NOT yet
+    implemented; this skill covers Phase 1 (manual + scripted) and
+    Phase 2 (Postgres + pgvector retrieval) only.
+namespace: ~/dev/git-folder/build-loop-memory/ (canonical), .build-loop/events.jsonl (repo-local runtime), legacy .episodic/ (migration/archive only)
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Knowledge — Canonical Build-Loop Memory (Phases 1 + 2)
+
+This skill is the entrypoint for the four-memory-types framework. The
+full design lives at
+`~/dev/research/topics/repo-episodic-memory-framework/repo-episodic-memory-framework.md`
+(see §11–§14 for the four-memory-type taxonomy, extraction pipeline,
+and Postgres schema). Read it before making structural changes.
+
+## What lives where
+
+```
+~/dev/git-folder/build-loop-memory/
+├── projects/<project>/decisions/   # canonical MADR decisions + INDEX.md
+├── projects/<project>/lessons/     # project-specific lessons
+├── lessons/                        # cross-project lessons
+├── indexes/                        # generated canonical indexes
+└── db/                             # Postgres helper material
+
+<repo>/.build-loop/events.jsonl     # repo-local runtime timeline
+<repo>/.episodic/                   # legacy migration/archive input only
+```
+
+## Phase 1 surface — file-only operations
+
+| Need | Tool |
+|---|---|
+| Write a decision (file only) | `python3 scripts/write_decision/__main__.py …` |
+| Validate frontmatter + links | `python3 scripts/validate_knowledge.py …` |
+| Regenerate INDEX files | `python3 scripts/regenerate_knowledge_index.py …` |
+| Migrate `feedback.md` to MADR | `python3 scripts/migrate_feedback_to_decisions.py …` |
+| Migrate playbooks to procedural | `python3 scripts/migrate_playbooks_to_procedural.py …` |
+
+## Phase 2 surface — DB-backed retrieval
+
+`write_decision.py` dual-writes (file canonical + best-effort DB row +
+embedding via `embed_backend`). DB errors do NOT fail the file write — the DB
+is regenerable from files.
+
+| Need | Tool |
+|---|---|
+| Initialize schema | `psql -d agent_memory -f scripts/init_agent_memory_schema.sql` |
+| Recall decisions on a topic | `python3 scripts/recall.py --query "…" --limit 5 …` |
+| Rebuild DB from canonical files | `python3 scripts/sync_db_from_files.py --rebuild` |
+
+`recall.py` is the entry point for Phase 1 Assess to load only the most
+relevant prior memory rather than reading INDEX.md wholesale. See
+`references/recall-integration.md`.
+
+## Authoring a decision (manual)
+
+1. Read `.semantic/TAXONOMY.md` to pick `primary_tag`, secondary
+   `tags`, `entity`, and `confidence`.
+2. Run `write_decision.py` with the required flags. The script:
+   - Allocates the next sequential ID (zero-padded 4-digit).
+   - Writes the MADR to
+     `~/dev/git-folder/build-loop-memory/projects/<project>/decisions/<canonical-id>.md` using
+     `skills/knowledge/templates/madr-minimal.md` as the body
+     scaffold (filled from CLI flags).
+   - Regenerates the canonical decisions `INDEX.md`.
+   - Appends one event to `<repo>/.build-loop/events.jsonl`.
+   - Embeds the body via local Ollama and inserts a row into
+     `agent_memory.<schema>.semantic_facts` (best-effort; file
+     write succeeds even if DB is down).
+
+   File writes are atomic (lock + tempfile + replace).
+
+## Topic identity & overwrite rules
+
+`primary_tag + entity` is the topic-identity key. Two decisions sharing
+both fields describe the same topic; the writer enforces the
+overwrite ladder defined in `TAXONOMY.md` §3:
+
+- Higher confidence auto-supersedes lower (no flag needed).
+- Equal confidence requires `--supersedes <id>` (explicit user direction).
+- Lower confidence cannot displace higher.
+
+Superseded decisions move to `_history/<id>-v<N>.md`; INDEX shows only
+the current version.
+
+## Validation
+
+`validate_knowledge.py` checks:
+- Frontmatter shape (required keys, value types, enum membership)
+- `tags` and `primary_tag` against TAXONOMY's vocabulary
+- `supersedes` / `superseded_by` links resolve to existing files
+
+`write_decision.py` calls the validator as a pre-write gate; you can
+also run it standalone over the whole tree.
+
+## Postgres connection
+
+DB-side scripts read connection from
+`~/.config/agent-memory/connection.env` (DATABASE_URL=
+postgresql://tyroneross@localhost:5432/agent_memory). Per-project schema:
+this repo uses `build_loop_memory`. The schema name is configurable via
+the `--schema` flag on each DB-aware script.
+
+## What's NOT in this skill
+
+- Auto-capture from conversation — Phase 3 (`auto-decision-capture`
+  skill, Stop hook with `scan_transcript_for_decisions.py`)
+- Memory consolidation — Phase 4 (`consolidate_memory.py`)
+- `/knowledge:review` slash command — Phase 4
+- `derived/libraries.json` and `derived/CHANGELOG.md` generators —
+  Phase 1.5 / 4
+
+Use this skill only for Phase 1 (manual + scripted) and Phase 2
+(retrieval) operations.

package/skills/knowledge/references/recall-integration.md

@@ -0,0 +1,83 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Recall integration — Phase 1 Assess
+
+`scripts/recall.py` is the retrieval entry point for repo-local episodic
+memory. It runs hybrid search (cosine + pg_trgm + full-text) over
+`agent_memory.<schema>.semantic_facts` and `episode_events`, returning a
+compact text summary suitable for direct injection into Phase 1 Assess
+context.
+
+## Why this exists
+
+Phase 1 Assess today reads `INDEX.md`, `MEMORY.md`, recent
+`runs[]` and recent feedback files wholesale (~10–20K tokens). For
+small projects this is fine; once the corpus crosses ~50 decisions it
+dominates Assess context. `recall.py` replaces the wholesale read with
+a query-specific top-K plus neighbor expansion (~500–1500 tokens).
+
+The cost is one Ollama embedding call (~30 ms locally) plus one psql
+hybrid search (~10–50 ms with HNSW). Both are local; no cloud cost.
+
+## Status: documented but NOT wired (per brief)
+
+This document specifies the integration. **The orchestrator does NOT
+call `recall.py` yet.** Wiring Phase 1 Assess is a deliberate follow-up
+after pilot data shows the recall quality is high enough on real
+queries. The planned wiring is below for reference.
+
+## Planned wiring (do NOT implement until pilot data is in)
+
+In `agents/build-orchestrator.md` Phase 1 Assess, this now sits behind
+`scripts/context_bootstrap.py`. If the pilot graduates, replace the
+bootstrap's canonical-memory recall sub-step, not the whole context packet:
+
+```bash
+# Build-relevant recall: the goal text is the query.
+python3 scripts/recall.py \
+  --query "$GOAL_TEXT" \
+  --limit 8 \
+  --confidence-floor confirmed \
+  --neighbor-window 3 \
+  > .build-loop/recall.md
+```
+
+The orchestrator then loads `.build-loop/recall.md` instead of the full
+INDEX/MEMORY tree. The unfiltered files remain available for the user
+to inspect; recall.md is the agent-facing summary.
+
+## Trigger conditions
+
+`recall.py` makes sense when:
+
+- The agent is starting a new build/turn that needs prior context.
+- The query is well-defined (a specific topic or symptom).
+
+`recall.py` is NOT a substitute when:
+
+- The agent needs to enumerate ALL prior decisions on a topic
+  (use `INDEX.md` directly with `--confidence-floor inferred` to widen).
+- Auto-capture is in flight and `_candidates.jsonl` hasn't been
+  consolidated yet (Phase 4 concern).
+- The DB is unreachable (recall returns exit 2; orchestrator should
+  fall back to `INDEX.md` read).
+
+## Invariants
+
+1. The DB is the index, not the source of truth. `recall.py` returning
+   nothing useful does NOT mean the answer isn't in the corpus —
+   re-run `sync_db_from_files.py --rebuild` and try again. If recall
+   still misses, the underlying decision is missing from `.episodic/`.
+2. The summary is bounded by `--char-budget` (default 8K chars,
+   ~1500 tokens). Truncation is explicit ("[truncated to char budget]").
+3. Confidence floor is `confirmed` by default. Pass `--confidence-floor
+   inferred` to include lower-trust auto-captured decisions (Phase 3).
+
+## Pilot exit criteria
+
+Wire into Phase 1 Assess after:
+
+- 30+ decisions have been migrated/captured into the corpus
+- Manual sampling shows top-3 recall quality ≥ 80% on goal-shaped
+  queries
+- Token budget proves to be ≤ 1500 tokens on realistic queries