@tyroneross/build-loop 0.30.3

package/skills/debugging-memory/references/pattern-extraction.md

@@ -0,0 +1,163 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Pattern Extraction Guide
+
+Patterns are reusable solution templates automatically extracted from similar incidents.
+
+## What Are Patterns?
+
+When 3+ incidents share similar symptoms and fixes, the memory system can extract a pattern. Patterns represent proven solutions with higher confidence than individual incidents.
+
+**Pattern vs Incident:**
+| Aspect | Incident | Pattern |
+|--------|----------|---------|
+| Source | Single debugging session | Multiple similar incidents |
+| Confidence | Variable (0.5-0.95) | High (0.9+) |
+| Reusability | Context-specific | Generalized |
+| Priority | Lower in search | First checked |
+
+## Pattern Structure
+
+```json
+{
+  "pattern_id": "PTN_REACT_HOOKS_DEPENDENCY",
+  "name": "React Hook Dependency Array Fix",
+  "description": "Fixes issues caused by unstable references in React hook dependency arrays",
+  "detection_signature": [
+    "infinite render",
+    "useEffect loop",
+    "useMemo dependency",
+    "useCallback",
+    "re-render",
+    "reference unstable"
+  ],
+  "applicable_to": ["coder", "refactorer"],
+  "solution_template": "1. Identify the hook with unstable dependencies\n2. Wrap callbacks in useCallback\n3. Wrap computed values in useMemo\n4. Update dependency arrays with stable references",
+  "code_example": "// Before: unstable callback\nuseEffect(() => {...}, [callback]);\n\n// After: stable callback\nconst stableCallback = useCallback(callback, [deps]);\nuseEffect(() => {...}, [stableCallback]);",
+  "tags": ["react", "hooks", "performance", "useEffect", "useMemo", "useCallback"],
+  "related_patterns": ["PTN_REACT_STATE_BATCHING"],
+  "success_rate": 0.92,
+  "usage_history": {
+    "total_uses": 15,
+    "successful_uses": 14,
+    "by_agent": {"coder": 12, "refactorer": 3},
+    "recent_incidents": ["INC_20241220_...", "INC_20241218_..."]
+  },
+  "caveats": [
+    "May not apply if the callback intentionally needs fresh closure",
+    "Consider whether memoization overhead is worth it for simple callbacks"
+  ]
+}
+```
+
+## Automatic Extraction
+
+Patterns are extracted automatically when conditions are met:
+
+### Extraction Criteria
+
+1. **Minimum incidents**: 3+ similar incidents required
+2. **Similarity threshold**: 70%+ symptom similarity
+3. **Fix consistency**: Similar approaches across incidents
+4. **Success rate**: Fixes verified as working
+
+### Triggering Extraction
+
+Use build-loop's native incident notes to preview and extract patterns.
+
+Local workflow:
+
+```bash
+find .build-loop/issues -type f -name '*.md' 2>/dev/null
+```
+
+Standalone Coding Debugger can provide richer pattern APIs when explicitly installed and requested. Programmatic examples should import that package from the standalone repo, not from build-loop.
+
+```typescript
+import { extractPatterns } from '<coding-debugger-package>';
+
+const patterns = await extractPatterns({
+  min_incidents: 3,
+  min_similarity: 0.7,
+  auto_store: true
+});
+```
+
+## Pattern Matching
+
+During debugging, patterns are checked first:
+
+1. System extracts keywords from symptom
+2. Matches against `detection_signature` of all patterns
+3. Patterns with 90%+ match are presented first
+4. If no pattern matches, falls back to incident search
+
+## Using Patterns
+
+When a pattern matches your bug:
+
+### 1. Review the Pattern
+
+Check:
+- `description`: Does it match your situation?
+- `solution_template`: Understand the approach
+- `caveats`: Note any limitations
+
+### 2. Apply the Solution
+
+Follow the `solution_template` steps:
+- Adapt for your specific codebase
+- Use `code_example` as reference
+- Check `related_patterns` for additional context
+
+### 3. Verify
+
+- Confirm the fix works
+- Run relevant tests
+- The incident still gets stored, linked to the pattern
+
+## Pattern Quality
+
+Patterns track their own reliability:
+
+- **success_rate**: Percentage of successful applications
+- **usage_history**: How often used, by which agents
+- **recent_incidents**: Links to incidents that used this pattern
+
+Low success rate patterns may indicate:
+- Over-generalized pattern
+- Context-dependent solution
+- Need for refinement or splitting
+
+## Creating Patterns Manually
+
+While automatic extraction is preferred, create patterns manually for well-understood solutions:
+
+```typescript
+import { storePattern } from '<coding-debugger-package>';
+
+await storePattern({
+  pattern_id: 'PTN_CATEGORY_NAME',
+  name: 'Human Readable Name',
+  description: 'What this pattern solves',
+  detection_signature: ['keyword1', 'keyword2'],
+  applicable_to: ['coder'],
+  solution_template: 'Step-by-step approach',
+  tags: ['tag1', 'tag2'],
+  success_rate: 1.0,
+  usage_history: {
+    total_uses: 0,
+    successful_uses: 0,
+    by_agent: {},
+    recent_incidents: []
+  }
+});
+```
+
+## Best Practices
+
+1. **Let extraction happen naturally** - Don't force patterns from few incidents
+2. **Review extracted patterns** - Ensure they generalize well
+3. **Update caveats** - Add warnings when patterns fail
+4. **Monitor success rates** - Refine patterns with low success
+5. **Split over-broad patterns** - If a pattern covers too many cases, split it

package/skills/debugging-memory/references/subagent-integration.md

@@ -0,0 +1,312 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Subagent Integration Guide
+
+This guide explains how to integrate build-loop native debugging memory with custom subagents, third-party agents, and multi-agent workflows.
+
+## Overview
+
+The debugging memory system works best when all agents in a workflow can access it. However, not all subagents have the necessary tool access. This guide covers:
+
+1. How to give subagents direct access
+2. How to proxy debugging memory for restricted agents
+3. How to coordinate multiple debugging agents
+4. How to handle limitations transparently
+
+## Direct Integration
+
+### Requirements
+
+For a subagent to directly access debugging memory, it needs **one of**:
+
+| Access Method | When to Use | Tools Needed |
+|---------------|-------------|--------------|
+| **MCP tools** (preferred) | Agent runs within Claude Code plugin context | MCP tool access |
+| **CLI fallback** | Agent only has Bash, no MCP access | `Bash` |
+| **Proxy** | Agent has no direct access | None (parent pre-queries) |
+
+### Direct Integration via MCP (Preferred)
+
+When the debugger plugin is installed, agents can call MCP tools directly:
+
+- `debugger search` — search past incidents by symptom
+- `debugger detail` — get full incident details
+- `debugger store` — store new incidents
+- `debugger patterns` — view extracted patterns
+
+### CLI Fallback for Restricted Agents
+
+For agents that only have Bash access (no MCP), use CLI commands:
+
+```yaml
+---
+name: my-debugging-agent
+description: Custom debugging agent with memory access
+tools: ["Bash", "Read", "Grep"]
+---
+```
+
+Add this to the agent's system prompt:
+
+```markdown
+## Debugging Memory
+
+This project uses build-loop native debugging memory.
+
+**Before investigating any bug:**
+\`\`\`
+Skill("build-loop:debugging-memory-search") with input { symptom: "<symptom description>" }
+\`\`\`
+
+**Interpret results:**
+- High confidence (>70%): Apply documented fix directly
+- Medium confidence (40-70%): Use as investigation starting point
+- Low/no match (<40%): Investigate fresh, document afterward
+
+**After fixing a bug:**
+Write an incident note to `.build-loop/issues/INC_YYYYMMDD_HHMMSS_xxxx.md`
+
+This ensures fixes are remembered for future similar issues.
+```
+
+> Note: pass memory context from the parent when the subagent lacks direct skill or filesystem access.
+
+## Proxy Integration
+
+When subagents cannot directly access debugging memory (no Bash tool, sandboxed, external MCP), use proxy integration.
+
+### Pre-Query Pattern
+
+```
+1. Parent agent searches memory
+2. Parent includes results in subagent prompt
+3. Subagent investigates with context
+4. Parent stores any new findings
+```
+
+### Implementation
+
+**Step 1: Search before spawning**
+
+Use `build-loop:debugging-memory-search` with the symptom description. If the subagent cannot invoke skills, the parent reads `.build-loop/issues/` and passes compact matches:
+
+```
+Skill("build-loop:debugging-memory-search") with input { symptom: "user login failing with 401" }
+```
+
+**Step 2: Format context for subagent**
+
+```markdown
+DEBUGGING MEMORY CONTEXT:
+
+Similar incidents found (2):
+1. INC_20241215_auth_401 (confidence: 0.82)
+   - Symptom: 401 errors after token refresh
+   - Root cause: Token expiry check using wrong timezone
+   - Fix: Use UTC for all token comparisons
+
+2. INC_20241201_login_fail (confidence: 0.65)
+   - Symptom: Intermittent login failures
+   - Root cause: Race condition in session creation
+   - Fix: Add mutex lock around session write
+
+Relevant pattern: PTN_auth_token_issues
+- Common causes: timezone mismatch, clock skew, token format changes
+- Recommended: Check token generation and validation code paths
+```
+
+**Step 3: Include in subagent prompt**
+
+```
+Investigate the 401 error on user login.
+
+[DEBUGGING MEMORY CONTEXT from above]
+
+Given this prior knowledge, focus your investigation on:
+1. Token handling differences from past incidents
+2. Any recent changes to auth code
+3. New causes not covered by past incidents
+```
+
+**Step 4: Store new findings**
+
+After subagent completes, if new root cause discovered, write incident JSON:
+
+```bash
+mkdir -p .claude/memory/incidents
+# Then write JSON file: .claude/memory/incidents/INC_YYYYMMDD_HHMMSS_xxxx.json
+```
+
+See `skills/debugging-memory/examples/incident-example.json` for full schema.
+
+## Multi-Agent Coordination
+
+### Parallel Assessment Pattern
+
+When multiple domain-specific agents investigate simultaneously:
+
+```
+┌─────────────────────────────────────────────────────┐
+│                 Parent Agent                         │
+│  1. Search memory once                              │
+│  2. Spawn assessors with relevant context           │
+└──────────┬──────────┬──────────┬──────────┬────────┘
+           │          │          │          │
+           ▼          ▼          ▼          ▼
+      ┌────────┐ ┌────────┐ ┌────────┐ ┌────────┐
+      │Database│ │Frontend│ │  API   │ │ Perf   │
+      │Assessor│ │Assessor│ │Assessor│ │Assessor│
+      └────┬───┘ └────┬───┘ └────┬───┘ └────┬───┘
+           │          │          │          │
+           └──────────┴──────────┴──────────┘
+                          │
+                          ▼
+              ┌───────────────────────┐
+              │   Aggregate Results    │
+              │   Store Unified Fix    │
+              └───────────────────────┘
+```
+
+### Context Distribution
+
+Give each assessor only relevant context:
+
+```javascript
+// Pseudo-code for context distribution
+const memoryResults = searchMemory(symptom);
+
+const dbContext = memoryResults.filter(i =>
+  i.tags.some(t => ['database', 'prisma', 'sql', 'query'].includes(t))
+);
+
+const apiContext = memoryResults.filter(i =>
+  i.tags.some(t => ['api', 'endpoint', 'auth', 'middleware'].includes(t))
+);
+
+// Spawn with filtered context
+spawnAgent('database-assessor', { context: dbContext });
+spawnAgent('api-assessor', { context: apiContext });
+```
+
+### Result Aggregation
+
+After all assessors complete:
+
+1. Rank by confidence score
+2. Identify consensus (multiple agents pointing to same area)
+3. Note conflicts for user decision
+4. Store unified incident with attribution
+
+```json
+{
+  "symptom": "App slow and returning wrong search results",
+  "diagnosis": {
+    "primary": {
+      "domain": "database",
+      "confidence": 0.85,
+      "assessor": "database-assessor",
+      "cause": "Missing index on search column"
+    },
+    "secondary": {
+      "domain": "api",
+      "confidence": 0.45,
+      "assessor": "api-assessor",
+      "cause": "Possible caching issue"
+    }
+  },
+  "recommended_sequence": [
+    "Add index to search column",
+    "Monitor performance",
+    "Investigate caching if still slow"
+  ]
+}
+```
+
+## Handling Limitations
+
+### Detection
+
+Identify when debugging memory cannot be fully utilized:
+
+| Scenario | Detection | Action |
+|----------|-----------|--------|
+| No Bash tool | Check agent tool list | Use proxy pattern |
+| External MCP | Agent uses MCP tools | Pre-query and inject |
+| Third-party agent | Not in project agents/ | Inform user |
+| Sandboxed | Environment restrictions | Pre-query and inject |
+
+### User Communication Templates
+
+**When using proxy integration:**
+```
+Note: I'm searching debugging memory before spawning the subagent,
+as it doesn't have direct access. Found [X] relevant incidents
+that I'll include in its investigation context.
+```
+
+**When no integration possible:**
+```
+Note: The [agent-name] agent cannot access this project's debugging
+memory. I recommend running `/debugger "<symptom>"` first to check
+for similar past issues before proceeding.
+```
+
+**When third-party agent used:**
+```
+Note: This third-party debugging tool operates independently of your
+project's debugging memory. After it completes, consider documenting
+any new findings with `/debugger-scan` to capture this session.
+```
+
+## Best Practices
+
+1. **Always pre-query for restricted agents** - Don't let knowledge gaps form
+
+2. **Include confidence scores** - Help subagents calibrate their investigation depth
+
+3. **Attribute findings** - Track which agent discovered what for learning
+
+4. **Store unified incidents** - One incident per bug, not one per agent
+
+5. **Be transparent** - Always inform users when memory access is limited
+
+6. **Use tags consistently** - Enable effective context filtering
+
+7. **Document proxy patterns** - Note in incidents when proxy integration was used
+
+## Example: Complete Multi-Agent Flow
+
+```markdown
+User: "The checkout is broken - showing wrong totals and timing out"
+
+Claude Code:
+1. Searches memory via `debugger search` MCP tool: "checkout wrong totals timeout"
+   - Found: INC_20241210_checkout_math (confidence: 0.72)
+   - Found: PTN_timeout_database (confidence: 0.58)
+
+2. Spawns parallel assessors:
+   - database-assessor: receives timeout pattern context
+   - api-assessor: receives both contexts
+   - frontend-assessor: receives math incident context
+
+3. Informs user:
+   "Checking debugging memory... Found 1 similar incident and 1 relevant pattern.
+   Running parallel assessment across database, API, and frontend domains."
+
+4. Aggregates results:
+   - database-assessor: 0.80 confidence - slow cart total query
+   - api-assessor: 0.45 confidence - possible middleware timeout
+   - frontend-assessor: 0.70 confidence - floating point rounding
+
+5. Reports:
+   "Assessment complete. Primary issue: database query for cart totals
+   (0.80 confidence). Secondary: frontend rounding display (0.70).
+   This matches past incident INC_20241210_checkout_math.
+
+   Recommended fix sequence:
+   1. Optimize cart total query (add index)
+   2. Fix frontend decimal display
+   3. Increase API timeout as buffer"
+
+6. After fix, stores unified incident with all findings
+```

package/skills/defenseclaw-bridge/SKILL.md

@@ -0,0 +1,156 @@
+---
+name: build-loop:defenseclaw-bridge
+description: Use when the user is working on the defenseclaw project and build-loop's Phase 1 detects defenseclaw-specific files (CLAUDE.md indicates the bridge target). Bridges build-loop's orchestrator to defenseclaw's eval/test conventions; otherwise no-op.
+version: 0.1.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# DefenseClaw Bridge
+
+Lets build-loop emit a runtime-security spec that downstream operators can hand to Cisco DefenseClaw (`github.com/cisco-ai-defense/defenseclaw`) — Apache 2.0, the cleanest production-shape implementation of the **Govern / Inspect / Prove** operational pattern. This bridge **only writes spec**; it does not run scanners, does not install the gateway sidecar, does not produce TypeScript plugins.
+
+## Cherry-pick principle
+
+**DefenseClaw remains an independent tool and repository.** This bridge does not embed, install, or run DefenseClaw — it only writes config files DefenseClaw consumes:
+
+- Reads the project's `tool-contract.md`, `agent-manifest.md`, `guardrail.md`, `system-boundary.md`, `flow-topology.md`, `role-card.md` artifacts (when present).
+- Reads the build-loop security canon — `skills/security-methodology/references/cross-source-matrix.md`.
+- Writes to `<project>/.defenseclaw/generated/` — bridge's own namespace; never touches DefenseClaw runtime state if DefenseClaw is also installed in the project.
+
+What this bridge does NOT do:
+
+- Run DefenseClaw scanners, gateway, sandbox, or any other DefenseClaw component.
+- Install DefenseClaw or its dependencies.
+- Test the generated config end-to-end.
+- Block the build if DefenseClaw is not installed — this skill only writes spec; whether the project adopts DefenseClaw is a separate decision.
+- Generate a working enforcement layer. The output is a spec skeleton with placeholder rule-pack entries; production use requires the project's security team to fill in concrete patterns and policies.
+
+## When to load
+
+- **Auto-loaded** by the build-orchestrator after Phase 3 Execute when *any* of the following artifacts exist or were modified during the build:
+  - `*tool-contract*.md`
+  - `*agent-manifest*.md`
+  - `*guardrail*.md`
+  - `*system-boundary*.md`
+  - `*flow-topology*.md`
+  - `*role-card*.md`
+  (Filename-glob match; the artifacts come from the agent-builder template set.)
+- **User-invocable** standalone: ask "generate the DefenseClaw spec from this manifest", "what runtime guardrails would map to these tool contracts", or invoke `Skill("build-loop:defenseclaw-bridge")` directly.
+
+## Inputs
+
+| Input | Source | Used for |
+|---|---|---|
+| `tool-contract.md` (one or more) | project filesystem | Per-tool scanner profile + permission-tier policy + Rego rule stub |
+| `agent-manifest.md` | project filesystem | Top-level dc-config sinks, modes, audit retention; risk-coverage attestation block |
+| `guardrail.md` (one or more) | project filesystem | Inspect rule-pack entries — pre-call / post-call / in-tool gates |
+| `system-boundary.md` | project filesystem | OpenShell sandbox profile (in-scope vs out-of-scope tasks → allowed vs blocked surfaces) |
+| `flow-topology.md` | project filesystem | A2A trust map (which agent can hand off to which); flagged when ASI07 row is hit |
+| `role-card.md` (one or more) | project filesystem | Per-role admission-control config (which scanners apply to which agent's allowed tools) |
+| `cross-source-matrix.md` | `skills/security-methodology/references/` | Risk → DefenseClaw control column lookup |
+| `dc-config-mapping.md` | `references/` (this skill) | Field-by-field mapping from each agent-builder template to DefenseClaw config |
+| `output-format.md` | `references/` (this skill) | Output file layout, naming, where each artifact lands |
+
+If the agent-builder plugin is not installed, the skill still works as long as the project's filesystem has files matching the glob patterns above. Filename matching (not plugin presence) is the trigger.
+
+## Outputs
+
+Written to `<project>/.defenseclaw/generated/`:
+
+| File | Purpose |
+|---|---|
+| `dc-config.yaml` | Top-level DefenseClaw config skeleton: sinks (audit, OTLP, SQLite path), modes (observe vs action), retention. |
+| `scanner-profile.yaml` | Govern pillar — admission scanner profiles, one per tool / MCP server / skill listed in the agent manifest. |
+| `policies/<name>.rego` (multiple) | OPA Rego policy stubs, one per tool contract, encoding the permission-tier and approval rules. |
+| `rule-packs/inspect.yaml` | Inspect pillar — pre-call and post-call rule-pack entries, one per guardrail in `guardrail.md`. |
+| `suppressions.yaml` | Template suppression list — empty by default, with comments explaining when to add entries. |
+| `README.md` | Generated explanation of which artifacts produced which config rows, plus open-questions/limitations. |
+
+The generated files are skeletons: structurally valid, with placeholder rule patterns and explicit `TODO:` markers where project-specific policy must be filled in by the security team.
+
+## Pre-flight
+
+Before generating, this skill checks:
+
+```bash
+# Look for any agent-builder-style artifact in the project
+find . -maxdepth 4 -type f \( \
+  -iname '*tool-contract*.md' -o \
+  -iname '*agent-manifest*.md' -o \
+  -iname '*guardrail*.md' -o \
+  -iname '*system-boundary*.md' -o \
+  -iname '*flow-topology*.md' -o \
+  -iname '*role-card*.md' \
+\) 2>/dev/null | head -20
+```
+
+If no artifacts are found, this skill emits a one-line note and exits cleanly — generating an empty DefenseClaw spec is worse than not generating one.
+
+If artifacts exist, read each, then walk `references/dc-config-mapping.md` row by row to populate the output files.
+
+## Steps
+
+1. **Load** `references/dc-config-mapping.md` and `references/output-format.md`. Also load `skills/security-methodology/references/cross-source-matrix.md` from the sibling skill.
+2. **Inventory** the project's agent-builder artifacts (filenames matched by the glob above). Group by template type: tool-contracts, manifests, guardrails, system-boundary, flow-topology, role-cards.
+3. **Parse each artifact**. Use a minimal YAML parser for the `yaml` blocks; for narrative-only artifacts, fall back to grep against the documented section headers (Risk control matrix, Permission tier reference, etc.).
+4. **Generate top-level `dc-config.yaml`** from the agent-manifest's `observability:`, `deployment:`, and (if present) `security_posture:` blocks. Default sinks: SQLite at `.defenseclaw/audit.sqlite`, JSONL at `.defenseclaw/audit.jsonl`. Default mode: `observe` (log only) — operators flip to `action` (block) only after tuning.
+5. **Generate `scanner-profile.yaml`** by walking each tool in the manifest's `tools:` block, looking up its `permission_tier` from the matching tool-contract, and mapping to the Govern column of the cross-source matrix. T0–T2 tools get a minimal scanner profile (read-only checks); T3–T5 get the full CodeGuard-equivalent set (secrets, dangerous exec, unsafe deserialization, weak crypto, injection patterns, risky file access).
+6. **Generate one `policies/<tool-name>.rego` per tool contract**. Each Rego stub encodes: who is allowed to call (`allowed_agents`), what arguments are accepted (input schema), what's forbidden (`forbidden_actions`), and the approval gate (`requires_human_approval`). Stubs are syntactically valid OPA but contain `TODO:` markers where the project must add concrete predicates (e.g., "what counts as a high-impact write to this resource").
+7. **Generate `rule-packs/inspect.yaml`** by walking each guardrail. Each guardrail's `trigger`, `check`, `action`, `severity` → an Inspect rule entry with `lifecycle_phase` (pre-call / post-call / in-tool / post-handoff) inferred from the guardrail's `applies_to` and `mode` (observe / action) inherited from the top-level config.
+8. **Generate `suppressions.yaml`** as an empty stub with documentation comments.
+9. **Generate `README.md`** that lists which input artifact produced which output row, names the open questions and `TODO:` markers, and points operators at the source matrix.
+10. **Write everything to `<project>/.defenseclaw/generated/`**, creating the directory if needed. Never overwrite a non-`generated/` path. Never touch any existing `.defenseclaw/audit.sqlite` or other DefenseClaw runtime state.
+
+## Generated YAML / JSON validity
+
+All generated YAML files must:
+
+- Parse with `python3 -c "import yaml; yaml.safe_load(open(path))"` (assuming PyYAML is available; otherwise use any YAML 1.1 parser).
+- Validate against DefenseClaw's documented config schema where applicable (DefenseClaw publishes JSON Schema for `dc-config.yaml`; check `https://github.com/cisco-ai-defense/defenseclaw` for the current schema URL — version drift is real, prefer the schema URL pinned at canon-write time over training-data assumption).
+- Open with a `# Generated by build-loop:defenseclaw-bridge` comment naming the input artifacts.
+
+OPA Rego stubs must:
+
+- Parse with `opa parse` (when OPA is available locally; not required for the spec to be valid, only nice-to-have).
+- Use the package convention `defenseclaw.tools.<tool_name>`.
+- Include explicit `default allow = false` so a missing rule denies rather than allows.
+
+## What this bridge does NOT generate
+
+- Working rule patterns. Every Rego rule and every Inspect rule-pack entry has `TODO:` placeholders where the project's security team fills in concrete predicates.
+- Sandbox configuration for OpenShell (DefenseClaw's Linux sandbox). The system-boundary template is too coarse to drive sandbox config; the bridge writes a TODO pointing at the relevant DefenseClaw doc.
+- Provider auth headers (`X-DC-Target-URL`, `X-AI-Auth`, `X-DC-Auth`). Those are runtime config, not spec; the bridge writes a `TODO:` block with placeholders.
+- LLM-judge configuration. DefenseClaw supports an optional LLM-as-judge layer on top of regex rule packs; whether to enable it is a project decision, not a spec generation.
+
+## Coverage gaps (spec-level)
+
+The bridge does not fully cover:
+
+- **ASI07 (Insecure Inter-Agent Communication)**. The cross-source matrix marks this row `(gap)`; no clean DefenseClaw control. The bridge surfaces this as a `TODO: ASI07 — A2A trust model is project-specific; consider message signing + nonces; DefenseClaw does not provide a built-in solution.` in the generated `README.md`.
+- **NIST policy-level risk areas (CBRN, Environmental, IP, Obscene, Violent)**. These are not engineering surfaces; bridge does not generate config for them.
+- **Bias / homogenization**. Project-specific eval; no DefenseClaw analog.
+
+## Standalone fallback
+
+If `references/dc-config-mapping.md` or the security-methodology cross-source matrix are missing (skill installed corrupt or partially), the bridge does not silently degrade. It emits:
+
+```
+defenseclaw-bridge: missing reference file <path>. Cannot generate DefenseClaw spec without the mapping. Reinstall the security-methodology skill or fall back to writing the DefenseClaw config by hand from `https://github.com/cisco-ai-defense/defenseclaw`.
+```
+
+…and exits without writing partial output.
+
+## Limitations
+
+- ⚠️ DefenseClaw config schema evolves. The mapping file in `references/dc-config-mapping.md` is pinned to the schema as of canon-write time. Operators deploying to a newer DefenseClaw should validate the generated spec against the current schema before running.
+- ⚠️ The bridge's input is template-shaped; if a project uses a different agent-spec format (e.g., raw YAML in a single file, custom agent registry), the bridge will not match. Custom-format support is out of scope; reformat to agent-builder templates first.
+- ⚠️ The mapping is **lossy**. Some agent-builder fields don't have a DefenseClaw analog (autonomy_level, north_star_metric, deactivation procedure); those fields are referenced in the generated `README.md` for context but don't drive any config row.
+- ❓ The "DefenseClaw publishes JSON Schema for dc-config.yaml" claim in the validity section is based on the repo at canon-write time; if the schema has been removed or relocated upstream, the bridge will fail validity checks gracefully (warn, don't error) and let operators inspect.
+
+## Related references
+
+- `~/dev/research/topics/product-dev/product-dev.agentic-systems-security-references.md` — the security canon citing DefenseClaw as a T1 reference implementation, plus the three-pillar Govern / Inspect / Prove model.
+- `~/dev/research/topics/product-dev/product-dev.agentic-systems-original-synthesis.md` — recommends adding DefenseClaw to the agent-builder catalog as the security-governance reference architecture.
+- `https://github.com/cisco-ai-defense/defenseclaw` — DefenseClaw repo. Apache 2.0. Cisco-backed.