@tyroneross/build-loop 0.30.3

package/skills/knowledge/templates/madr-minimal.md

@@ -0,0 +1,56 @@
+---
+id: NNNN
+slug: kebab-case-slug
+title: Full sentence describing the decision
+type: decision
+status: proposed
+confidence: explicit
+date: YYYY-MM-DD
+tags: [primary-tag, secondary-tag]
+primary_tag: primary-tag
+entity: subject-of-decision
+# v2 metadata (added 2026-05-04). All required at write time; defaults are
+# applied by `scripts/write_decision.py` so manual MADR drafts can omit them.
+project: project-name
+tool: claude-code
+model: claude-opus-4-7
+task_category: feature
+author: tyroneross
+source: manual
+related_runs: []
+related_decisions: []
+supersedes: null
+superseded_by: null
+bookmark_snapshot_id: null
+captured_turn_excerpt: null
+last_validated: null
+last_accessed: null
+files_touched: []
+closing_commit: null
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# {Title}
+
+## Context
+
+(1–3 sentences. What problem are we solving? What forced this choice now?)
+
+## Decision
+
+(1 sentence. The choice in active voice: "We will use X.")
+
+## Alternatives considered
+
+- **Option A** — short description. Pros: …. Cons: …. Why not chosen: ….
+- **Option B** — short description. Pros: …. Cons: …. Why not chosen: ….
+
+## Consequences
+
+- (1–3 bullets. What follows from this choice? Trade-offs accepted? Future
+  work this enables or precludes?)
+
+## Notes
+
+(Optional. Implementation pointers, related links, supersession context.)

package/skills/knowledge-review/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: knowledge-review
+description: Repo-local episodic memory review surface. Use when the user asks to "review my decisions", "show review queue", "check decision rot", "list open conflicts", "find stale procedures", or runs `/knowledge:review`. Read-only — never auto-resolves.
+user-invocable: false
+when_to_use: |
+  - User runs `/knowledge:review` or asks to surface review-needing items
+  - User wants to see decisions older than the staleness threshold
+  - User wants to see `_review/` queue items awaiting promotion
+  - User wants to see open `fact_conflicts` rows
+  - User wants to see procedures whose `depends_on` symbols are missing from the codebase
+namespace: .episodic/decisions/_review/, .episodic/decisions/, .procedural/, agent_memory.<schema>.fact_conflicts
+companion_scripts:
+  - scripts/knowledge_review.py — aggregates all four sections into a markdown report
+  - scripts/detect_decision_rot.py — drives the rot section
+  - scripts/procedural_governance.py — drives the stale-procedures section (validate-symbols mode)
+  - scripts/consolidate_memory.py — referenced as the next-step action when surface items accumulate
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# knowledge-review — surface review-needing items
+
+`/knowledge:review` is the read-only review surface for the four-memory-types
+framework (Working / Episodic / Semantic / Procedural). It does NOT modify
+any data; it lists what humans need to decide on.
+
+The full design lives at
+`~/dev/research/topics/repo-episodic-memory-framework/repo-episodic-memory-framework.md`
+(see §11–§14).
+
+## What it surfaces
+
+```
+┌────────────────────────────────────────────────────────────────┐
+│ knowledge_review.py — four sections                            │
+├────────────────────────────────────────────────────────────────┤
+│ 1. Review queue        — `.episodic/decisions/_review/`        │
+│                          Tier-3 captures awaiting promotion    │
+│ 2. Decision rot        — decisions older than threshold        │
+│                          (default 90 days)                     │
+│ 3. Open conflicts      — fact_conflicts rows resolved=FALSE    │
+│                          (skipped when DB unavailable)         │
+│ 4. Stale procedures    — depends_on symbols missing from code  │
+└────────────────────────────────────────────────────────────────┘
+```
+
+Each item carries a suggested action. The user takes the action via
+existing scripts:
+
+| Section | Action | Script |
+|---|---|---|
+| Review queue | promote | `mv .episodic/decisions/_review/<file> .episodic/decisions/` then `python3 scripts/sync_db_from_files.py` |
+| Review queue | dismiss | `rm .episodic/decisions/_review/<file>` |
+| Decision rot | mark-validated | edit frontmatter to add `last_validated: YYYY-MM-DD` |
+| Decision rot | supersede | `python3 scripts/supersede_decision.py --old-id <id> ...` |
+| Decision rot | revoke | `python3 scripts/revoke_decision.py --id <id> --reason ...` |
+| Open conflicts | resolve | `UPDATE` one row in `semantic_facts` to `status='superseded'`; set `fact_conflicts.resolved=TRUE` |
+| Stale procedures | re-verify | edit `depends_on[].last_verified` after confirming symbol still works |
+| Stale procedures | revoke | move `.procedural/<name>/` to `.procedural/_archive/<name>/` |
+
+## How to invoke
+
+Slash command:
+
+```
+/knowledge:review [--rot-threshold-days N] [--no-db]
+```
+
+Direct script:
+
+```bash
+python3 scripts/knowledge_review.py \
+  --workdir "$PWD" \
+  --rot-threshold-days 90 \
+  --symbol-paths scripts,src,app
+```
+
+Useful flags:
+
+- `--rot-threshold-days <N>` — change the staleness threshold (default 90)
+- `--symbol-paths <csv>` — codebase paths to grep for `depends_on` symbols
+- `--no-db` — skip the conflicts section (faster; useful when DB is down)
+- `--schema <name>` — Postgres schema to query (default `build_loop_memory`)
+
+## Cross-reference: consolidation
+
+When the review queue grows large, run consolidation to merge
+mature candidates into `semantic_facts`:
+
+```bash
+# Inspect what would happen
+python3 scripts/consolidate_memory.py --workdir "$PWD" --dry-run
+
+# Apply
+python3 scripts/consolidate_memory.py --workdir "$PWD"
+```
+
+Consolidation reads `.semantic/_candidates.jsonl` (typically populated by
+the auto-capture batch sweep), dedupes against existing facts, and
+records the action in `.semantic/_candidates_history.jsonl`.
+
+## Read-only contract
+
+This skill never:
+- promotes items from `_review/` (user does the `mv`)
+- mutates `last_validated` (user edits the file)
+- resolves conflicts (user updates the rows)
+- modifies procedure frontmatter (user edits or runs `--rewrite` on validate-symbols)
+
+The reason: review/promotion decisions need human judgment about whether
+a captured inference matches the user's intent. Auto-promotion would
+poison the trusted set.

package/skills/logging-tracer/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: logging-tracer
+description: Use when the user asks to "add logging", "add tracing", "improve observability", "OpenTelemetry", "structured logging", or reports silent failures or no runtime visibility. Generates stack-appropriate logging with optional OTel.
+version: 1.0.0
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Logging & Tracing Code Generation
+
+Generate structured logging and tracing code tailored to the project's stack. Follow a tiered approach: start with zero dependencies, escalate only when the user needs distributed tracing.
+
+## Stack Detection
+
+Before generating code, detect the project's stack and existing logging:
+
+1. Check for `package.json` (Node.js/TypeScript), `requirements.txt`/`pyproject.toml` (Python), `go.mod` (Go), `Cargo.toml` (Rust), `Gemfile` (Ruby)
+2. Check for existing logging frameworks:
+   - Node.js: winston, pino, bunyan, console
+   - Python: logging, loguru, structlog
+   - Go: zap, zerolog, logrus, slog
+3. Check for existing tracing: OpenTelemetry SDK, Sentry SDK, Datadog agent
+4. Detect the application type: API server, CLI tool, web app, worker/queue processor
+
+If existing logging exists, extend it rather than replacing it. If uncertain about the stack, ask the user before generating code.
+
+## Tiered Code Generation
+
+### Tier 1: Zero-Dependency Structured Logging (Default)
+
+Generate a single logger module using only built-in language features. Output structured JSON to stderr (not stdout, which may be used for data or protocols).
+
+**Key requirements:**
+- Log levels: debug, info, warn, error
+- Configurable minimum level via environment variable
+- Structured JSON output with: timestamp, level, message, and arbitrary context fields
+- Operation name for every log entry
+- Duration tracking for async operations
+
+Refer to `references/stack-templates.md` for full implementation templates per language.
+
+### Tier 2: File-Based Logging
+
+When the user needs persistent logs or the debugger's `read_logs` tool should discover them:
+
+- Write logs to `logs/app.jsonl` in the project root (JSONL format, append-only)
+- Use standard field names: `ts` (Unix ms), `level`, `msg`, `op` (operation name)
+- Add log rotation at 10MB with 2 rotated files maximum
+- These locations are auto-discoverable by the debugger's `read_logs` MCP tool
+
+### Tier 3: OpenTelemetry + Free Backends
+
+When the user explicitly requests distributed tracing or mentions OTel/Jaeger/SigNoz:
+
+- Install the OTel SDK for their language
+- Create a tracing initialization module with:
+  - Graceful degradation when no collector is running
+  - Hot-reload safety (prevent duplicate initialization)
+  - Smart sampling: 100% in development, 10% in production (100% for errors/slow operations)
+- Wrap key operations in spans
+- Recommend free backends: Jaeger (local), SigNoz (self-hosted), or Grafana Tempo
+
+## Where to Add Logging
+
+Guide the user on strategic placement. Log at these points:
+
+1. **Function entry/exit** for key operations (API handlers, service methods, data pipelines)
+2. **External calls** — every HTTP request, database query, cache operation, file I/O
+3. **Error handlers** — always log error name, message, stack, and the operation that failed
+4. **State transitions** — authentication changes, workflow steps, queue processing stages
+5. **Decision points** — when code takes a branch based on runtime data (cache hit/miss, feature flag, fallback)
+
+Avoid logging:
+- Every iteration of a loop (use summary: "processed 150 items in 230ms")
+- Sensitive data (passwords, tokens, PII) — redact before logging
+- Redundant information already captured by the framework (e.g., Express request logging middleware)
+
+## Ephemeral-by-default (mandatory for diagnostic instrumentation)
+
+When this skill is invoked **reactively** to repair an evidence gap during a debugging session — not proactively at the user's standing request for permanent observability — the instrumentation **must not land in the final diff unless the user explicitly approves it**. Log/tracer patches that survive into commits alter timing, IO, and snapshot behavior — masking rather than fixing the original failure.
+
+Two enforcement mechanisms; choose per invocation. Default to Mechanism A.
+
+### Mechanism A — Runtime gate (preferred)
+
+Wrap every new diagnostic log statement so it is inert unless `DEBUG_TRACE=1` is set:
+
+```typescript
+const __trace = process.env.DEBUG_TRACE === "1";
+function trace(msg: string, meta: Record<string, unknown> = {}) {
+  if (!__trace) return;
+  const entry = { ts: new Date().toISOString(), level: "trace", msg, ...meta };
+  process.stderr.write(JSON.stringify(entry) + "\n");
+}
+```
+
+```python
+import os, json, sys, datetime
+_TRACE = os.environ.get("DEBUG_TRACE") == "1"
+def trace(msg, **meta):
+    if not _TRACE: return
+    entry = {"ts": datetime.datetime.utcnow().isoformat() + "Z", "level": "trace", "msg": msg, **meta}
+    print(json.dumps(entry), file=sys.stderr)
+```
+
+Re-run the failing criterion with `DEBUG_TRACE=1 <test-command>`. Output flows to stderr for `read_logs` MCP to capture. Production paths never execute trace code in normal builds.
+
+### Mechanism B — Throwaway patch
+
+When the change cannot be wrapped in a runtime gate (e.g. language without env access at the call site, or the instrumentation requires structural changes like adding request IDs or new fields to types), apply the change as a `git stash` patch BEFORE re-running:
+
+```bash
+# After the code changes land
+git stash push -u -m "build-loop:trace/<session-id>"
+# Stash applied in-place
+git stash show stash@{0}
+# Re-run the failing criterion
+<test-command>
+# Diagnostics captured in .build-loop/logs/
+# Revert after the capture completes
+git stash drop stash@{0}
+```
+
+The orchestrator tracks the stash entry in `.build-loop/state.json.observability.interventions[].stash_id`. At Review-F the orchestrator MUST verify no stash entries remain with `build-loop:trace/` prefix; if any do, revert them before writing the scorecard.
+
+### Keep-in-diff approval (opt-in only)
+
+To keep instrumentation in the final diff (e.g. the user wants ongoing observability), the caller must invoke `AskUserQuestion`:
+
+```
+Question: "Keep the diagnostic logging added to <files> in the final diff?"
+Options:
+  - "Revert — instrumentation was diagnostic only" (default, recommended)
+  - "Keep — convert to permanent observability (remove DEBUG_TRACE gate or unstash)"
+  - "Keep with gate — leave DEBUG_TRACE wrapping in place"
+```
+
+Default answer on user absence: **revert**. No silent retention. If the user picks "keep", remove the env-flag guard (Mechanism A) or apply the stash and drop the reference (Mechanism B).
+
+## Code placement rules (diagnostic instrumentation)
+
+When adding instrumentation reactively to repair an evidence gap:
+
+- Insert at function entry/exit for functions the investigation flagged — not the whole codebase
+- Never silently catch + log (`catch { log(...) }` without rethrow is an anti-pattern that turns errors into lost signal)
+- Include the variable that was `undefined` / `null` / `nil` in the log entry — bare "error in X" is useless
+- Add exactly ONE trace call per function added; no spam
+- All calls go through the `trace()` helper (Mechanism A) or live in a throwaway stash (Mechanism B) — no unguarded log/print/eprintln statements added to the codebase
+
+## Re-validate after adding
+
+After the instrumentation lands:
+
+1. Re-run the failing criterion with `DEBUG_TRACE=1` (Mechanism A) or stash applied (Mechanism B)
+2. If tests now fail WITH informative output → return the log evidence to the caller as fresh context for the next fix attempt
+3. If tests still fail silently → instrumentation did not solve the visibility problem; escalate to user
+4. **Always revert** at session end unless the user explicitly approved keep-in-diff via the prompt above. The orchestrator (or caller) verifies no `build-loop:trace/` stash entries remain and no unguarded trace calls landed.
+
+## Extended capability — escalate to standalone supporting plugin
+
+If the bundled tier selection / codegen / placement isn't enough (e.g., the project requires a tracer backend or placement intelligence that lives in the standalone supporting plugin only, or you need cross-build log correlation), invoke the bridge:
+
+```
+Skill("build-loop:logging-tracer-bridge") with input { symptom, target_files, tier_hint, calledBy: "logging-tracer" }
+```
+
+The bridge pre-flights `availablePlugins.codingDebugger`. If standalone Coding Debugger is installed, it delegates to extended observability tooling there. If not installed, returns `{ delegated: false }` and this skill continues with bundled-only Tier 1/2/3 codegen.
+
+## Log Analysis Guidance
+
+When the user has logs but needs help interpreting them, follow this diagnostic sequence:
+
+1. **Start with errors** — filter for error/fatal level, read newest first
+2. **Check timing** — look for operations that took >2s or showed sudden duration spikes
+3. **Look for patterns** — repeated errors, cascading failures, periodic spikes
+4. **Correlate timestamps** — align logs across services/components for the same time window
+5. **Diagnose missing logs** — if expected log entries are absent, the code path wasn't reached or the logger isn't configured
+
+Refer to `references/log-analysis.md` for common error signatures and diagnostic checklists.
+
+## Integration with Debugger
+
+Generated logging code integrates with the debugger's `read_logs` MCP tool when:
+
+- Logs are written to discoverable locations (`logs/`, `*.log`, `*.jsonl` in project root)
+- JSONL format uses standard fields (`ts`, `level`, `msg`)
+- Error entries include structured error objects (`error.name`, `error.message`, `error.stack`)
+
+After adding logging, tell the user they can read logs using:
+```
+Use the debugger read_logs tool with source "project" to view these logs.
+```
+
+## Output Format
+
+When generating logging code:
+
+1. Generate the logger module first (single file)
+2. Show 2-3 examples of how to use it in existing code
+3. Mention the environment variable for log level configuration
+4. If Tier 2+, note the log file location and rotation behavior

package/skills/logging-tracer/references/log-analysis.md

@@ -0,0 +1,128 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# Log Analysis — Common Patterns & Diagnostic Checklists
+
+## Error Signature Reference
+
+### Connection Errors
+
+| Signature | Likely Cause | Action |
+|-----------|-------------|--------|
+| `ECONNREFUSED` | Service not running / wrong port | Check if target service is up, verify host:port |
+| `ETIMEDOUT` | Network unreachable / firewall | Check network connectivity, DNS resolution |
+| `ECONNRESET` | Remote closed connection | Check server logs, look for OOM or crash |
+| `EPIPE` | Writing to closed socket | Handle connection lifecycle, add retry logic |
+| `ENOTFOUND` | DNS resolution failed | Verify hostname, check DNS config |
+
+### Database Errors
+
+| Signature | Likely Cause | Action |
+|-----------|-------------|--------|
+| `P2002` (Prisma) | Unique constraint violation | Check for duplicate data, review upsert logic |
+| `P2025` (Prisma) | Record not found | Add existence check before update/delete |
+| `connection pool exhausted` | Too many concurrent queries | Increase pool size or add connection timeouts |
+| `deadlock detected` | Concurrent conflicting transactions | Review transaction isolation, add retry logic |
+| `relation does not exist` | Missing migration | Run pending migrations |
+
+### HTTP Errors
+
+| Code | Pattern | Common Cause |
+|------|---------|-------------|
+| 400 | Repeated from same endpoint | Schema validation failing — check request shape |
+| 401 | After period of success | Token expired — check refresh logic |
+| 403 | Specific routes only | Permission/role check — verify user permissions |
+| 404 | After deployment | Route changed — check routing config |
+| 429 | Burst pattern | Rate limit hit — add backoff/queue |
+| 500 | Correlates with deploy | Regression — check recent changes |
+| 502/503 | Periodic spikes | Upstream health — check dependent services |
+
+### Memory & Performance
+
+| Pattern | Likely Cause | Action |
+|---------|-------------|--------|
+| Steadily increasing RSS | Memory leak | Profile with --inspect, check for uncleared timers/listeners |
+| Periodic CPU spikes | GC pauses or cron jobs | Check GC stats, review scheduled tasks |
+| Sudden latency jump | Resource exhaustion | Check file descriptors, connections, thread pool |
+| Gradual latency increase | Data growth | Check query plans, add indexes, paginate |
+
+## Diagnostic Checklists
+
+### "Application is slow"
+
+1. Check error logs for timeouts or connection failures
+2. Filter for operations with `dur_ms > 2000`
+3. Group slow operations by type (db, http, cache)
+4. Check if slowness correlates with time of day (traffic) or specific operations
+5. Look for N+1 query patterns (many fast DB queries in sequence)
+6. Check external API response times
+7. Review memory usage trends for GC pressure
+
+### "Intermittent failures"
+
+1. Filter errors by frequency — find the most common error message
+2. Check if errors correlate with time patterns (cron, traffic spikes, deployments)
+3. Look for resource exhaustion (pool size, rate limits, file descriptors)
+4. Check for race conditions (concurrent requests to same resource)
+5. Verify retry logic — is it making the problem worse?
+6. Check for environmental differences (works in staging, fails in production)
+
+### "No logs at expected point"
+
+1. Verify the code path is reached — add a log before the expected point
+2. Check log level configuration — is `LOG_LEVEL` set too high?
+3. Verify logger is initialized before first use
+4. Check for swallowed exceptions (empty catch blocks)
+5. If async: verify await chains are complete, no fire-and-forget promises
+6. Check log output destination — stderr vs stdout vs file
+
+### "After deployment regression"
+
+1. Compare error rates before/after deploy timestamp
+2. Filter for new error messages (not seen before deploy)
+3. Check for environment variable changes
+4. Verify database migrations ran successfully
+5. Check for dependency version changes
+6. Compare request/response shapes if API changed
+7. Look for feature flag changes
+
+## Reading JSONL Logs Efficiently
+
+### With the debugger
+
+```
+Use the debugger read_logs tool:
+- source: "project" to auto-discover project logs
+- source: "debugger" for internal operation logs
+- since: "1h" for last hour
+- level: "error" for errors only
+- keyword: "timeout" to search
+```
+
+### Command-line quick reference
+
+```bash
+# Last 20 errors
+grep '"level":"error"' logs/app.jsonl | tail -20 | jq .
+
+# Operations slower than 2 seconds
+jq 'select(.dur_ms > 2000)' logs/app.jsonl
+
+# Count errors by operation
+jq -r 'select(.level == "error") | .op' logs/app.jsonl | sort | uniq -c | sort -rn
+
+# Errors in last hour (Unix timestamp)
+SINCE=$(($(date +%s) * 1000 - 3600000))
+jq "select(.ts > $SINCE and .level == \"error\")" logs/app.jsonl
+
+# Time range
+jq 'select(.ts > 1710000000000 and .ts < 1710003600000)' logs/app.jsonl
+```
+
+## Anti-Patterns
+
+1. **Logging sensitive data** — Never log passwords, tokens, credit card numbers, or PII. Redact before logging.
+2. **Console.log in production** — Use structured logging. Console.log has no levels, no timestamps, no structure.
+3. **Logging in tight loops** — Log summaries ("processed 150 items") not per-iteration ("processing item 1", "processing item 2"...).
+4. **Multiple logging systems** — Pick one logger per service. Don't mix console.log, winston, and pino.
+5. **Swallowing errors** — Empty catch blocks hide failures. At minimum, log the error.
+6. **Over-logging success paths** — Log entry/exit at debug level, errors at error level. Don't flood info with every successful operation.