baldart 3.6.2

package/framework/agents/llm-wiki-methodology.md

@@ -0,0 +1,216 @@
+# LLM Wiki Overlay — Methodology
+
+## Purpose
+
+Document the methodology for building a **derived LLM wiki** on top of
+canonical SSOT docs. The overlay is a non-canonical, human-and-agent-friendly
+layer of compiled pages (concepts, syntheses, dashboards, reading guides) that
+makes retrieval cheaper and reasoning more stable, **without ever becoming
+source-of-truth**.
+
+This module describes the contract, file layout, lifecycle, and auto-learning
+loop. The agent that maintains the overlay is `wiki-curator`. The skill that
+captures synthesis pages from live conversations is `/capture`.
+
+## Layered Knowledge Stack
+
+The wiki overlay sits on top of an existing retrieval stack. A typical layout:
+
+| Layer | Role | Authority |
+|-------|------|-----------|
+| Canonical SSOT (`${paths.references_dir}/**`, `${paths.adrs_dir}/**`, code itself) | Source of truth | **Canonical** — never override from below |
+| External human knowledge (Obsidian vault, Notion, Confluence) | Human-readable narrative; optional | Mirrors canonical with extra context |
+| RAG / search layer (e.g. LightRAG, vector DB, full-text index) | Recall + cross-document discovery | Operational, not canonical |
+| **Wiki overlay** (`${paths.wiki_dir}/**`) | Compiled, navigable, stable | **Derived** — always cites canonical refs |
+
+Rules:
+
+1. The wiki never creates canonical truth.
+2. SSOT changes propagate down; wiki pages must be recompiled when canonicals
+   change.
+3. If a wiki page conflicts with SSOT, SSOT wins and the wiki page is rewritten.
+4. The RAG layer is fed both canonicals and wiki pages, but query verdicts
+   reveal **gaps** in the canonical layer, which become candidates for new
+   wiki syntheses (see § Auto-Learning Loop).
+
+## Page Types
+
+A complete overlay typically contains five page types:
+
+| Type | Folder | Purpose |
+|------|--------|---------|
+| **Concept** | `${paths.wiki_dir}/concepts/` | Explanatory pages that define a term, pattern, or system component |
+| **Synthesis** | `${paths.wiki_dir}/syntheses/` | Multi-source distillation of cross-document reasoning (often captured via `/capture`) |
+| **Dashboard** | `${paths.wiki_dir}/dashboards/` | Current-state snapshots (status of an epic, freshness of a SSOT, validator output) |
+| **Reading Guide** | `${paths.wiki_dir}/reading-guides/` | Ordered paths into the corpus for specific tasks (onboarding, incident response) |
+| **Index** | `${paths.wiki_dir}/index.md` | Single navigation entry point listing the other pages |
+
+The `${paths.wiki_dir}/log.md` file is the **append-only event log** used by the
+auto-learning loop (see below).
+
+## Frontmatter Discipline (MANDATORY)
+
+Every wiki page MUST carry frontmatter so agents and validators can route and
+trust the page:
+
+```yaml
+---
+doc_type: synthesis | concept | dashboard | reading-guide | log | index
+domain: <e.g. platform | booking | payments | …>
+canonicality: derived          # NEVER `canonical` — that's the SSOT layer's contract
+owner: <agent or team>
+status: active | draft | deprecated
+freshness_status: fresh | stale | needs-rebuild
+confidence: high | medium | low
+source_refs:                   # explicit canonical doc paths the page synthesizes
+  - ${paths.adrs_dir}/<ADR>.md
+  - ${paths.references_dir}/<ref>.md
+last_verified_from_code: YYYY-MM-DD
+canonical_refs:                # broader canonicals this page is consistent with
+  - ${paths.references_dir}/ssot-registry.md
+  - ${paths.references_dir}/project-status.md
+---
+```
+
+Run a frontmatter validator (typically `npm run validate:frontmatter` or
+equivalent) before committing wiki edits.
+
+## Anchor & Cross-Reference Discipline
+
+- Markdown slugification: lowercase, spaces → dashes, strip punctuation except
+  dashes (GitHub-flavored).
+- For every `[text](#some-anchor)` link, the corresponding heading must exist
+  with the slugified form `some-anchor`.
+- For every `[text](../foo.md#anchor)` link, the heading must exist in
+  `foo.md`.
+- The `wiki-curator` agent flags `WIKI_ANCHOR_BROKEN` on mismatch and fixes
+  it in the same invocation when possible.
+
+## Auto-Learning Loop (the core idea)
+
+The overlay is not static. It feeds itself from agent activity, closing a loop
+that surfaces documentation gaps and turns them into stable pages.
+
+```
+        ┌──────────────┐
+        │ Agents query │
+        │ RAG / search │
+        └──────┬───────┘
+               │  (instrumented: every search_docs call tags the invoker)
+               ▼
+        ┌──────────────┐
+        │ Telemetry log│  (${paths.wiki_dir}/log.md — append-only)
+        └──────┬───────┘
+               │  (verdicts: useful | weak | empty | fallback_degraded)
+               ▼
+   ┌────────────────────────────┐
+   │ Nightly wiki-review job    │
+   │ runs `wiki-curator` agent  │
+   └──────┬─────────────────────┘
+          │  (proposes synthesis candidates from weak/empty verdicts)
+          ▼
+   ┌────────────────────────────┐
+   │ /capture skill writes      │
+   │ a new synthesis page after │
+   │ user approval              │
+   └──────┬─────────────────────┘
+          │
+          ▼
+        New wiki page → next RAG query gets a strong verdict.
+```
+
+### Tap points (instrumentation)
+
+Every agent that queries the RAG layer MUST pass an `invoker_agent` tag on its
+search calls, so telemetry attributes the query to the right agent. After each
+call, the agent inspects the telemetry verdict and — if it is `weak`, `empty`,
+or `fallback_degraded` — appends one entry to `${paths.wiki_dir}/log.md` via the
+project's log helper (e.g. `tools/<rag-impl>/wiki_log.py`).
+
+```python
+from wiki_log import append_entry  # project-specific helper
+append_entry(
+  entry_type="query",
+  title=<query_short>,
+  agent=<invoker>,
+  context={"verdict": verdict, "top_score": top_score, "count": count},
+  refs=[],
+  outcome=verdict,
+)
+```
+
+**Graceful degrade**: if the helper fails or is missing, emit one stderr line
+and continue. Telemetry must never block real work.
+
+### Synthesis candidates (nightly review)
+
+The `wiki-curator` agent, running on a schedule (typically nightly), scans:
+
+- ADRs and PRDs from the last 14 days with significant architectural impact
+  (touches >3 modules, provider swap, schema change, auth change, API
+  contract) → propose a synthesis page.
+- PRD-led multi-card epics (≥4 cards in same parent epic) → propose an
+  overview synthesis.
+- RAG queries with `verdict=weak|empty` repeated ≥3 times in
+  `${paths.wiki_dir}/log.md` → the topic is a documentation gap, propose synthesis.
+
+Candidates are appended to `${paths.wiki_dir}/log.md` with
+`entry_type: synthesis_candidate` and a small payload (title, source refs,
+expected scope, triggering agent).
+
+### `/capture` skill (manual + proactive)
+
+The `/capture` skill turns a recent multi-turn synthesis (cross-document
+reasoning done in a conversation) into a durable synthesis page under
+`${paths.wiki_dir}/syntheses/<slug>.md`. Two modes:
+
+| Mode | When | How |
+|------|------|-----|
+| **Manual** | User runs `/capture` explicitly | Skill reads pending queue + recent turns, proposes a synthesis |
+| **Proactive** | A `Stop`-event hook detected a synthesis-worthy turn and queued a candidate | Next `/capture` invocation surfaces the candidate first |
+
+Manual mode always works. Proactive mode is a convenience layer the user can
+disable with a kill-switch file (`touch .claude/capture-queue/.disabled`).
+
+The skill requires explicit user approval before writing. Acceptance and
+rejection are both logged.
+
+## Graph Community Synthesis (optional, advanced)
+
+If the project's RAG layer ships a community-detection layer (e.g.
+Leiden/Louvain) on top of the entity graph, cluster summaries can be produced
+weekly and exposed via dedicated MCP tools. These cluster summaries are
+candidate inputs to `concept` pages.
+
+## Roles & Responsibilities
+
+| Role | Owns | Edits |
+|------|------|-------|
+| `wiki-curator` agent | Overlay quality, drift detection, candidate proposal | `${paths.wiki_dir}/**` |
+| `/capture` skill | Synthesis page creation from live conversations | `${paths.wiki_dir}/syntheses/**` |
+| `doc-reviewer` agent | Canonical SSOT integrity (downstream of the overlay) | `${paths.references_dir}/**`, `${paths.adrs_dir}/**` |
+| Project-specific knowledge-sync agent (optional) | Mirror to external corpus (Obsidian/Notion/Confluence) | External corpus only |
+
+## Adoption Checklist (for a new project)
+
+To install the LLM wiki overlay in a new project:
+
+1. Create `${paths.wiki_dir}/` with the five page-type folders and an `index.md`.
+2. Add the frontmatter validator (or adapt your existing one) to check
+   wiki frontmatter compliance.
+3. Decide on a RAG layer (LightRAG, vector DB, or full-text). If using one,
+   instrument every `search_docs` call with `invoker_agent` and a `wiki_log`
+   append helper.
+4. Schedule the `wiki-curator` agent to run on a nightly cadence
+   (cron / Claude Code remote agent / GitHub Action).
+5. Enable the `/capture` skill for users and (optionally) the proactive hook.
+6. Add `${paths.wiki_dir}/log.md` as an append-only log file under version control,
+   with rotation rules if it grows large.
+7. Document the overlay in your repo README so contributors know it exists
+   and is non-canonical.
+
+## Related
+
+- Agent: [`.claude/agents/wiki-curator.md`](../.claude/agents/wiki-curator.md)
+- Skill: [`.claude/skills/capture/SKILL.md`](../.claude/skills/capture/SKILL.md)
+- Doc-writer agent: [`.claude/agents/doc-reviewer.md`](../.claude/agents/doc-reviewer.md)

package/framework/agents/maintenance-protocol.md

@@ -0,0 +1,305 @@
+# Maintenance Protocol
+
+## Purpose
+
+Define routine maintenance tasks and procedures.
+
+## Scope
+
+**In**: Dependency updates, database maintenance, cleanup tasks, health checks.
+**Out**: Emergency procedures (see agents/deployment-protocol.md).
+
+## Do
+
+- Schedule regular maintenance
+- Test updates in staging first
+- Document maintenance activities
+- Keep dependencies up to date
+
+## Do Not
+
+- Skip maintenance windows
+- Update production directly
+- Ignore security updates
+
+## Maintenance Schedule
+
+### Daily
+
+- [ ] Check error logs
+- [ ] Monitor system health
+- [ ] Review performance metrics
+- [ ] Check disk space
+
+### Weekly
+
+- [ ] Review security advisories
+- [ ] Check for dependency updates
+- [ ] Analyze slow queries
+- [ ] Review recent deployments
+
+### Monthly
+
+- [ ] Update dependencies
+- [ ] Database optimization
+- [ ] Review access logs
+- [ ] Clean up old data
+- [ ] Review backup procedures
+- [ ] Test disaster recovery
+
+### Quarterly
+
+- [ ] Security audit
+- [ ] Performance review
+- [ ] Capacity planning
+- [ ] Documentation review
+- [ ] Dependency major version updates
+
+### Annually
+
+- [ ] Comprehensive security review
+- [ ] Architecture review
+- [ ] Technology stack evaluation
+- [ ] Disaster recovery drill
+- [ ] SSL certificate renewal
+
+## Dependency Management
+
+### Checking for Updates
+
+```bash
+# Check for outdated packages
+[command - e.g., npm outdated, pip list --outdated]
+```
+
+### Update Strategy
+
+1. **Patch updates** (x.x.X): Apply immediately
+2. **Minor updates** (x.X.x): Test in staging, deploy within week
+3. **Major updates** (X.x.x): Plan, test thoroughly, may require code changes
+
+### Update Process
+
+1. Check changelog for breaking changes
+2. Update in development
+3. Run tests
+4. Deploy to staging
+5. Test critical flows
+6. Deploy to production
+7. Monitor for issues
+
+## Database Maintenance
+
+### Regular Tasks
+
+```bash
+# Analyze tables (example for PostgreSQL)
+ANALYZE;
+
+# Vacuum database
+VACUUM;
+
+# Check database size
+[command]
+
+# Optimize tables (if applicable)
+[command]
+```
+
+### Index Maintenance
+
+- Review slow query log
+- Identify missing indexes
+- Remove unused indexes
+- Rebuild fragmented indexes
+
+### Data Cleanup
+
+- Archive old records
+- Delete soft-deleted records
+- Clean up orphaned data
+- Purge expired sessions
+
+## Log Management
+
+### Log Rotation
+
+- Rotate logs daily/weekly
+- Compress old logs
+- Delete logs older than retention period
+- Archive important logs
+
+### Log Analysis
+
+- Review error patterns
+- Identify slow operations
+- Check for security issues
+- Monitor resource usage
+
+## Backup Verification
+
+### Regular Checks
+
+```bash
+# List recent backups
+[command]
+
+# Test backup restoration
+[command]
+
+# Verify backup integrity
+[command]
+```
+
+### Backup Schedule
+
+- **Database**: Daily, keep 30 days
+- **Files**: Weekly, keep 12 weeks
+- **Full system**: Monthly, keep 12 months
+- **Critical data**: Real-time replication
+
+## Security Maintenance
+
+### SSL Certificates
+
+- Monitor expiration dates
+- Renew 30 days before expiry
+- Test after renewal
+- Update certificate pinning if used
+
+### Access Review
+
+- Review user accounts
+- Remove inactive users
+- Review permissions
+- Rotate API keys/secrets
+
+### Security Patches
+
+- Monitor security advisories
+- Apply critical patches immediately
+- Test non-critical patches in staging
+- Document all security updates
+
+## Performance Optimization
+
+### Regular Reviews
+
+- Analyze slow queries
+- Review API response times
+- Check resource usage trends
+- Identify bottlenecks
+
+### Cache Management
+
+```bash
+# Clear cache
+[command]
+
+# Warm cache
+[command]
+
+# Review cache hit rate
+[command]
+```
+
+## Health Checks
+
+### System Health
+
+```bash
+# Check service status
+[command]
+
+# Check disk space
+[command]
+
+# Check memory usage
+[command]
+
+# Check CPU usage
+[command]
+```
+
+### Application Health
+
+```bash
+# Health endpoint
+curl [health-check-url]
+
+# Database connection
+[command]
+
+# External service status
+[command]
+```
+
+## Incident Prevention
+
+### Monitoring
+
+- Set up alerts for:
+  - High error rates
+  - Slow response times
+  - High resource usage
+  - Failed health checks
+  - Security events
+
+### Proactive Actions
+
+- Scale before reaching capacity
+- Fix issues before they become critical
+- Update before forced by security issues
+- Document before knowledge is lost
+
+## Maintenance Windows
+
+### Planning
+
+1. Announce maintenance window
+2. Schedule during low-traffic period
+3. Prepare rollback plan
+4. Test procedures in staging
+
+### During Maintenance
+
+1. Put site in maintenance mode (if applicable)
+2. Perform maintenance tasks
+3. Run health checks
+4. Verify functionality
+5. Return to normal operation
+
+### After Maintenance
+
+1. Monitor for issues
+2. Document what was done
+3. Review if maintenance was successful
+4. Schedule next maintenance
+
+## Documentation
+
+Maintain maintenance log:
+
+```markdown
+## YYYY-MM-DD: [Maintenance Type]
+
+**Performed by**: [Name]
+**Duration**: [Time]
+**Tasks completed**:
+- [Task 1]
+- [Task 2]
+
+**Issues encountered**: [None or description]
+**Follow-up actions**: [Any actions needed]
+```
+
+## Emergency Maintenance
+
+For critical issues requiring immediate maintenance:
+
+1. Notify team
+2. Document issue
+3. Perform fix
+4. Test immediately
+5. Monitor closely
+6. Post-mortem after resolution

package/framework/agents/observability.md

@@ -0,0 +1,162 @@
+# Observability
+
+## Purpose
+
+Define logging, monitoring, and alerting strategies.
+
+## Scope
+
+**In**: Logging standards, metrics, tracing, alerting.
+**Out**: Performance optimization (see agents/performance.md).
+
+## Do
+
+- Log important events with context
+- Monitor key metrics
+- Set up alerts for critical issues
+- Implement distributed tracing if applicable
+
+## Do Not
+
+- Log sensitive data (passwords, tokens, PII)
+- Over-log (creates noise)
+- Ignore warning signs
+
+## Logging
+
+### Log Levels
+
+- **ERROR**: Application errors requiring immediate attention
+- **WARN**: Warning conditions that should be reviewed
+- **INFO**: Important business events
+- **DEBUG**: Detailed diagnostic information
+
+### Log Format
+
+Use structured logging:
+
+```json
+{
+  "timestamp": "2026-02-13T10:00:00Z",
+  "level": "INFO",
+  "message": "User logged in",
+  "userId": "123",
+  "context": {
+    "ip": "192.168.1.1",
+    "userAgent": "..."
+  }
+}
+```
+
+### What to Log
+
+- Authentication attempts
+- Authorization failures
+- API requests/responses (sanitized)
+- Database errors
+- External service calls
+- Business-critical events
+- Performance anomalies
+
+### What NOT to Log
+
+- Passwords
+- API keys/tokens
+- Credit card numbers
+- PII (unless required and encrypted)
+- Large payloads
+
+## Metrics
+
+### Application Metrics
+
+- Request count
+- Response times
+- Error rates
+- Active users
+- Business metrics (signups, conversions, etc.)
+
+### Infrastructure Metrics
+
+- CPU usage
+- Memory usage
+- Disk I/O
+- Network I/O
+- Database connections
+
+### Custom Metrics
+
+Define project-specific metrics:
+
+- [Business metric 1]
+- [Business metric 2]
+- [Technical metric 1]
+
+## Tracing (if applicable)
+
+- Implement distributed tracing for microservices
+- Trace IDs through request lifecycle
+- Track latency across services
+- Identify bottlenecks
+
+## Alerting
+
+### Alert Levels
+
+- **Critical**: Immediate action required (page on-call)
+- **High**: Requires attention within hours
+- **Medium**: Review during business hours
+- **Low**: Informational
+
+### Alert Criteria
+
+Define when to alert:
+
+| Metric | Threshold | Level |
+|--------|-----------|-------|
+| Error rate | > 5% | Critical |
+| Response time (p95) | > 2s | High |
+| CPU usage | > 80% | High |
+| Disk space | < 10% | Critical |
+| [Custom metric] | [Threshold] | [Level] |
+
+### Alert Channels
+
+- [On-call system - e.g., PagerDuty]
+- [Team chat - e.g., Slack]
+- [Email]
+- [SMS for critical]
+
+## Dashboards
+
+Create dashboards for:
+
+- System health overview
+- Application performance
+- Business metrics
+- Error tracking
+- User activity
+
+## Incident Response
+
+1. Alert fires
+2. On-call acknowledges
+3. Investigate using logs/metrics
+4. Mitigate issue
+5. Create post-mortem
+6. Implement preventive measures
+
+## Tools
+
+- **Logging**: [e.g., ELK, Loki, CloudWatch]
+- **Metrics**: [e.g., Prometheus, Datadog, CloudWatch]
+- **Tracing**: [e.g., Jaeger, Zipkin, X-Ray]
+- **Alerting**: [e.g., PagerDuty, Opsgenie, Grafana]
+- **Dashboards**: [e.g., Grafana, Kibana, Datadog]
+
+## Log Retention
+
+- [Production logs retention - e.g., 30 days]
+- [Error logs retention - e.g., 90 days]
+- [Audit logs retention - e.g., 1 year]
+- [Archive policy]