mindforge-cc 11.2.1 → 11.3.1

package/.mindforge/integrations/slack.md

@@ -0,0 +1,41 @@
+# MindForge — Slack Integration
+
+## Purpose
+Send operational notifications for phase completion, blockers, security events,
+ milestone completion, and approvals.
+
+## Supported notifications
+
+| Event | Behaviour |
+|---|---|
+| phase complete | Send summary notification |
+| security finding HIGH/CRITICAL | Send urgent alert and optional mention |
+| approval needed | Post request summary with approval file reference |
+| blocker added | Post concise blocker notice |
+| milestone complete | Post release summary |
+
+## Message safety
+Sanitise all dynamic values inserted into JSON payloads. Escape double quotes,
+ backslashes, and newlines before building Block Kit payloads. Never use
+ `curl -v` with Slack tokens.
+
+## Thread management
+Store thread references in `.planning/slack-threads.json`:
+
+```json
+{
+  "schema_version": "1.0.0",
+  "channel_id": "C01234ABCDE",
+  "threads": {
+    "phase-1": "1710931200.123456"
+  },
+  "_warning": "Do not store tokens in this file."
+}
+```
+
+If Slack rejects an existing `thread_ts`, clear that entry and create a new
+ thread instead of retrying the invalid timestamp.
+
+## Undelivered critical alerts
+If Slack is unconfigured or the channel is invalid during a CRITICAL security
+ event, write the alert into `.planning/STATE.md` under `Undelivered alerts`.

package/.mindforge/intelligence/antipattern-detector.md

@@ -0,0 +1,75 @@
+# MindForge Intelligence — Anti-Pattern Detection Engine
+
+## Purpose
+Detect architecture, database, security, code-quality, and testing anti-patterns
+at plan, execute, and review checkpoints.
+
+## Key patterns
+- A01 God object / service
+- A02 Circular dependencies
+- A03 Distributed monolith
+- A04 Hardcoded configuration
+- B01 `SELECT *`
+- B02 Missing FK indexes
+- B03 Unbounded queries
+- C01 Auth bypass via type coercion
+- C02 Missing authorization
+- C03 Sensitive data in URL
+- D01 Callback/pyramid complexity
+- D02 Magic strings
+- D03 Swallowed errors
+- E01 Tests tied to internals
+- E02 Flaky test indicators
+
+## C01 false positive prevention
+Exclude from C01 scanning:
+```bash
+grep -rn "==\s*null\|==\s*undefined\|==\s*false\|==\s*0" src/ \
+  --include="*.ts" --include="*.js" \
+  --exclude="*.test.ts" --exclude="*.spec.ts" --exclude="*.test.js" --exclude="*.spec.js"
+```
+
+Do not flag:
+- assertions in test files (`tests/**`, `*.test.*`, `*.spec.*`)
+- intentional type-guard nullish checks (`x == null`) in type-guard functions
+
+Only treat C01 as critical in auth/middleware/security-sensitive paths.
+
+## B03 cursor pagination exception
+Cursor-based pagination is exempt from unbounded query check.
+Recognize exemptions:
+- Prisma `cursor:` parameter
+- query with both `orderBy:` and `cursor:`
+- SQL tuple cursor predicates (`WHERE (..., ...) < (..., ...)`)
+
+```bash
+grep -rn "findMany\\b" src/ --include="*.ts" | python3 - <<'PY'
+import sys
+for line in sys.stdin:
+    l = line.lower()
+    if 'cursor:' in l or '< :cursor' in l or '<(' in l:
+        continue
+    if 'take:' not in l and 'limit:' not in l:
+        print('B03 candidate:', line.strip())
+PY
+```
+
+## D01 executable line counting
+Use executable-line heuristic for God-object thresholding, not raw `wc -l`.
+
+```bash
+count_executable_lines() {
+  local f="$1"
+  grep -v '^\s*$' "$f" | grep -v '^\s*//' | grep -v '^\s*\*' | grep -v '^\s*@' | wc -l
+}
+```
+
+Apply threshold to executable count (e.g., `>500`) plus dependency fan-in signal.
+
+## Trigger points
+- Plan phase: architecture patterns (A*)
+- Execute phase: implementation/security patterns (B*, C*, D03)
+- Review phase: full library
+
+## Report format
+Include id, severity, location, and exact remediation advice.

package/.mindforge/intelligence/difficulty-scorer.md

@@ -0,0 +1,55 @@
+# MindForge Intelligence — Phase Difficulty Scorer
+
+## Purpose
+Score phase complexity before planning so decomposition and verification rigor
+match risk.
+
+## Dimensions
+- Technical complexity (35%)
+- Risk level (30%)
+- Ambiguity (20%)
+- Dependencies (15%)
+
+Composite:
+`(Technical*0.35) + (Risk*0.30) + (Ambiguity*0.20) + (Dependencies*0.15)`
+
+## Signal detection
+### Technical complexity context handling
+Keyword matching must include local context windows.
+
+- `migration` near `database` or `schema` => technical `4`
+- `migration` near `code` or `framework` => technical `3`
+
+### Risk amplifiers
+Add +1 for each relevant amplifier (cap 5):
+- missing test baseline in touched area
+- external integration without sandbox
+- shared module blast radius (`>3` consumers)
+- unclear rollback path
+- prior related incidents
+
+For prior incidents, inspect `AUDIT.jsonl`:
+- `task_failed` events with file-path overlap with expected touched files
+- `security_finding` events in overlapping domains (auth/payments/database)
+
+## Score bands
+- `1.0-2.0` Easy => `2-3` tasks
+- `2.1-3.0` Moderate => `4-6` tasks
+- `3.1-4.0` Challenging => `6-10` tasks
+- `4.1-5.0` Hard => `10-15` tasks
+
+If composite `> 4.5`: recommend split into `Phase N-A` (lowest-risk)
+and `Phase N-B` (highest-risk), and offer:
+`/mindforge:discuss-phase [N] --split`
+
+## Feedback loop: score -> granularity
+The planner must read `DIFFICULTY-SCORE-[N].md` before creating plans.
+
+| Composite | Granularity instruction |
+|---|---|
+| 1.0-2.0 | 1 task = complete feature component |
+| 2.1-3.0 | 1 task = significant module/function |
+| 3.1-4.0 | 1 task = specific function/endpoint |
+| 4.1-5.0 | 1 task = narrow change in 3-4 files max |
+
+This creates explicit feedback: difficulty -> decomposition -> execution quality.

package/.mindforge/intelligence/health-engine.md

@@ -0,0 +1,208 @@
+# MindForge Intelligence — Health Engine
+
+## Purpose
+Run a comprehensive health check across installation, context, skills, personas,
+state, integrations, and security. Detect drift and provide safe auto-repair.
+
+## Categories
+1. Installation integrity
+2. Context file health
+3. Skills registry health
+4. Persona system health
+5. State consistency
+6. Integration connectivity
+7. Security configuration
+
+## Category 1 — Installation integrity
+
+### Required files checklist
+```bash
+REQUIRED_FILES=(
+  ".claude/CLAUDE.md"
+  ".agent/CLAUDE.md"
+
+  ".claude/commands/mindforge/help.md"
+  ".claude/commands/mindforge/init-project.md"
+  ".claude/commands/mindforge/plan-phase.md"
+  ".claude/commands/mindforge/execute-phase.md"
+  ".claude/commands/mindforge/verify-phase.md"
+  ".claude/commands/mindforge/ship.md"
+  ".claude/commands/mindforge/next.md"
+  ".claude/commands/mindforge/quick.md"
+  ".claude/commands/mindforge/status.md"
+  ".claude/commands/mindforge/debug.md"
+  ".claude/commands/mindforge/skills.md"
+  ".claude/commands/mindforge/review.md"
+  ".claude/commands/mindforge/security-scan.md"
+  ".claude/commands/mindforge/map-codebase.md"
+  ".claude/commands/mindforge/discuss-phase.md"
+  ".claude/commands/mindforge/audit.md"
+  ".claude/commands/mindforge/milestone.md"
+  ".claude/commands/mindforge/complete-milestone.md"
+  ".claude/commands/mindforge/approve.md"
+  ".claude/commands/mindforge/sync-jira.md"
+  ".claude/commands/mindforge/sync-confluence.md"
+  ".claude/commands/mindforge/health.md"
+  ".claude/commands/mindforge/retrospective.md"
+  ".claude/commands/mindforge/profile-team.md"
+  ".claude/commands/mindforge/metrics.md"
+
+  ".mindforge/engine/wave-executor.md"
+  ".mindforge/engine/dependency-parser.md"
+  ".mindforge/engine/context-injector.md"
+  ".mindforge/engine/compaction-protocol.md"
+  ".mindforge/engine/verification-pipeline.md"
+  ".mindforge/engine/skills/registry.md"
+  ".mindforge/engine/skills/loader.md"
+  ".mindforge/engine/skills/versioning.md"
+  ".mindforge/engine/skills/conflict-resolver.md"
+
+  ".mindforge/skills/security-review/SKILL.md"
+  ".mindforge/skills/code-quality/SKILL.md"
+  ".mindforge/skills/api-design/SKILL.md"
+  ".mindforge/skills/testing-standards/SKILL.md"
+  ".mindforge/skills/documentation/SKILL.md"
+  ".mindforge/skills/performance/SKILL.md"
+  ".mindforge/skills/accessibility/SKILL.md"
+  ".mindforge/skills/data-privacy/SKILL.md"
+  ".mindforge/skills/incident-response/SKILL.md"
+  ".mindforge/skills/database-patterns/SKILL.md"
+
+  ".mindforge/personas/analyst.md"
+  ".mindforge/personas/architect.md"
+  ".mindforge/personas/developer.md"
+  ".mindforge/personas/qa-engineer.md"
+  ".mindforge/personas/security-reviewer.md"
+  ".mindforge/personas/tech-writer.md"
+  ".mindforge/personas/debug-specialist.md"
+  ".mindforge/personas/release-manager.md"
+
+  ".mindforge/intelligence/health-engine.md"
+  ".mindforge/intelligence/difficulty-scorer.md"
+  ".mindforge/intelligence/antipattern-detector.md"
+  ".mindforge/intelligence/skill-gap-analyser.md"
+  ".mindforge/intelligence/smart-compaction.md"
+
+  ".mindforge/governance/change-classifier.md"
+  ".mindforge/governance/approval-workflow.md"
+  ".mindforge/governance/compliance-gates.md"
+
+  ".mindforge/org/ORG.md"
+  ".mindforge/org/CONVENTIONS.md"
+  ".mindforge/org/SECURITY.md"
+  ".mindforge/org/TOOLS.md"
+  ".mindforge/org/skills/MANIFEST.md"
+  ".mindforge/org/integrations/INTEGRATIONS-CONFIG.md"
+
+  ".planning/HANDOFF.json"
+  ".planning/STATE.md"
+  ".planning/AUDIT.jsonl"
+)
+```
+
+`MINDFORGE.md` is optional and is not in required files.
+If `MINDFORGE.md` exists, validate:
+- no unknown skills (must exist in `.mindforge/org/skills/MANIFEST.md`)
+- no invalid model names (fallback to `inherit` + warning)
+- no attempted overrides of governance primitives
+
+### Version check
+- Validate `package.json` semver is `>= 0.5.0`.
+
+### CLAUDE parity
+- `.claude/CLAUDE.md` and `.agent/CLAUDE.md` must be identical.
+- All commands under `.claude/commands/mindforge/` must exist in `.agent/mindforge/`.
+
+## Category 2 — Context file health
+- `PROJECT.md` has tech stack, v1 scope, success criteria, and no placeholders.
+- `REQUIREMENTS.md` has FR entries with acceptance criteria and scope tags.
+- `STATE.md` has recent `Last updated` timestamp and coherent status.
+- `HANDOFF.json` is valid JSON with required fields and no secrets.
+- `ARCHITECTURE.md` exists with stack and decision references.
+
+## Category 3 — Skills registry health
+- `MANIFEST.md` exists; all 10 core skills listed with valid semver.
+- Every manifest skill path exists.
+- Every `SKILL.md` includes frontmatter: `name`, `version`, `status`, `triggers`.
+- Trigger conflict check runs and reports count.
+
+## Category 4 — Persona system health
+- Each persona has Identity, Pre-task checklist, Escalation, DoD.
+- Persona files are non-stub (>500 bytes).
+- Override files contain no prompt-injection markers.
+
+## Category 5 — State consistency
+- For every phase in ROADMAP: directory + required artifacts match phase status.
+- Explicit check: if `STATE.md` marks phase complete and summaries exist but `VERIFICATION.md` is missing, flag as error.
+- `AUDIT.jsonl` lines parse as JSONL and timestamps are chronological.
+- Commit hygiene:
+  - conventional commit format in recent history
+  - on `main`, only flag commits whose subject starts with `wip` (case-insensitive)
+
+## Category 6 — Integration connectivity
+For configured integrations, run lightweight auth checks and report:
+- `available`
+- `invalid_credentials`
+- `unreachable`
+- `unconfigured` (informational only)
+
+## Category 7 — Security configuration
+- `.gitignore` covers env files and keys.
+- Secret scan covers:
+  - `.planning/`
+  - `.mindforge/`
+  - root-level `MINDFORGE.md`, `.env.example`, `*.config.js`
+- `SECURITY.md` has no placeholders.
+- Governance approval files are not stale beyond SLA.
+
+## Auto-repair protocol
+
+### Auto-repairable
+- sync `.agent/CLAUDE.md` from `.claude/CLAUDE.md`
+- mirror missing command files from `.claude` to `.agent`
+- add missing `Last updated` in `STATE.md`
+- create `.planning/approvals/` if missing
+- mark expired approvals and audit them
+- trigger AUDIT archive protocol when threshold exceeded
+
+### AUDIT.jsonl corruption handling (updated)
+**Never delete lines from `AUDIT.jsonl`.**
+
+```bash
+python3 - <<'PY'
+import json
+from pathlib import Path
+
+audit = Path('.planning/AUDIT.jsonl')
+if not audit.exists():
+    raise SystemExit(0)
+
+invalid = []
+for i, raw in enumerate(audit.read_text().splitlines(), 1):
+    s = raw.strip()
+    if not s:
+        continue
+    try:
+        json.loads(s)
+    except Exception:
+        invalid.append({"line": i, "raw": s})
+
+if invalid:
+    qf = Path('.planning/AUDIT.jsonl.quarantine')
+    with qf.open('a', encoding='utf-8') as f:
+        for row in invalid:
+            f.write(json.dumps(row) + "\n")
+    print(f"Quarantined {len(invalid)} invalid lines to {qf}")
+PY
+
+echo "{\"event\":\"audit_quarantine\",\"quarantine_file\":\".planning/AUDIT.jsonl.quarantine\"}" >> .planning/AUDIT.jsonl
+```
+
+### Non-auto-repairable
+- missing core skill files
+- invalid credentials
+- secrets found in `HANDOFF.json`
+- prompt-injection patterns in persona overrides
+
+## Health report format
+Provide summary by category with errors, warnings, info, and exact next fixes.

package/.mindforge/intelligence/skill-gap-analyser.md

@@ -0,0 +1,40 @@
+# MindForge Intelligence — Skill Gap Analyser
+
+## Purpose
+Identify required/recommended skills for a phase, compare with installed
+skills, and report gaps before planning.
+
+## Run points
+1. `/mindforge:plan-phase` start
+2. `/mindforge:discuss-phase`
+3. `/mindforge:health`
+
+## Analysis flow
+1. Extract work signals from roadmap/context/requirements/architecture.
+2. Map work categories to required/recommended skills.
+3. Validate skills in manifest + filesystem + status.
+4. Report missing/deprecated required skills and mitigation options.
+
+## Category -> skill mapping
+- UI/UX -> accessibility (required), performance (recommended)
+- Database changes -> database-patterns (required), data-privacy (if PII)
+- API endpoints -> api-design (required), security-review (if auth)
+- Auth/payments/PII -> security-review (required), data-privacy (required for PII)
+- Performance work -> performance (required)
+- New feature -> testing-standards (required), documentation (recommended)
+
+## Gap definition
+A required skill is a gap if:
+- not present in MANIFEST
+- manifest path missing
+- marked deprecated with no replacement
+
+## Output
+Produce `Skill Gap Analysis` section with:
+- required skills table
+- recommended skills table
+- explicit gap count and options
+
+## Health mode
+In `/mindforge:health`, include org-level recommendation list using recent
+phase patterns and missing capability frequencies.

package/.mindforge/intelligence/smart-compaction.md

@@ -0,0 +1,71 @@
+# MindForge Intelligence — Smart Context Compaction
+
+## Purpose
+Replace truncation with structured extraction so future sessions preserve reasoning,
+constraints, and in-progress state.
+
+## Triggering and level selection
+Day 2 threshold (`70%`) remains valid and now invokes Day 5 Level 1.
+Level selection uses both context usage and session depth.
+
+- Light session (`<5` tasks): use Level 1 even when context is high.
+- Moderate session (`5-10` tasks): use Level 2 at `80%+`.
+- Deep session (`10+` tasks): use Level 2 at `75%+`.
+- Level 3 at `90%+` or urgent near-limit state.
+
+## Levels
+### Level 1 — Lightweight
+Quick checkpoint: update `STATE.md` and `HANDOFF.json` with next task.
+
+### Level 2 — Structured extraction
+Capture:
+- decisions made
+- discoveries
+- implicit knowledge
+- quality signals
+- precise in-progress state
+
+### Level 3 — Emergency extraction
+Capture minimum viable continuation context before hard limit.
+
+## Level 2 extraction protocol
+### Block A — Decisions made
+For each decision: what, why, alternatives ruled out, impact area, ADR need.
+
+### Block B — Discoveries
+For each finding: fact, location, significance, assumption impact.
+
+### Block C — Current task state
+Record plan id, completed steps, remaining steps, current file, and inconsistency state.
+
+### Block D — Implicit knowledge
+Capture quirks, environment facts, and workarounds.
+
+A knowledge item qualifies as a **quirk** if either:
+1. It contradicts documentation or expected tool behavior.
+2. A new agent reading only plans/personas would not infer it.
+
+### Block E — Quality signals
+Capture failed assumptions, friction patterns, quality gate root causes, and next-plan suggestions.
+
+## Level 2 HANDOFF schema additions
+- `decisions_made[]`
+- `discoveries[]`
+- `implicit_knowledge[]`
+- `quality_signals[]`
+- `in_progress.current_state`
+
+## Session restart protocol
+When loading Level 2 handoff:
+1. Print compact summary counts.
+2. Preload `implicit_knowledge` before plan execution.
+3. If `in_progress.current_state` is inconsistent, block execution and ask to resolve first.
+4. If user asks to inspect first, print first 50 lines of the inconsistent file inline.
+
+## Compaction quality metric
+Write one entry to `.mindforge/metrics/compaction-quality.jsonl`:
+- `decisions_captured`
+- `discoveries_captured`
+- `implicit_knowledge_items`
+- `quality_signals_captured`
+- `next_session_continuation_success` (auto-inferred from next session, nullable initially)

package/.mindforge/memory/MEMORY-SCHEMA.md

@@ -0,0 +1,155 @@
+# MindForge v2 — Knowledge Graph Schema
+
+## Overview
+
+The MindForge knowledge graph is built from five JSONL files — all append-only,
+all at `.mindforge/memory/`. Every entry has a consistent base schema plus
+type-specific fields.
+
+## Base schema (all entry types)
+
+```json
+{
+  "id":               "kb-uuid-v4",
+  "timestamp":        "ISO-8601",
+  "type":             "architectural_decision|code_pattern|bug_pattern|team_preference|domain_knowledge",
+  "topic":            "Short title (≤ 80 chars)",
+  "content":          "Full knowledge content (no limit)",
+  "source":           "Where this was captured: 'Phase 3 retro', 'Debug session 2026-01', 'Manual entry'",
+  "project":          "project-name from PROJECT.md",
+  "confidence":       0.0,
+  "tags":             ["tag1", "tag2"],
+  "linked_adrs":      ["ADR-007"],
+  "times_referenced": 0,
+  "last_referenced":  null,
+  "deprecated":       false,
+  "deprecated_by":    null
+}
+```
+
+## Type-specific schemas
+
+### `architectural_decision`
+
+Extended fields:
+
+```json
+{
+  "decision":     "Use argon2id for password hashing",
+  "rationale":    "bcrypt is showing its age; argon2id is the modern standard",
+  "alternatives": ["bcrypt", "scrypt", "pbkdf2"],
+  "phase_number": 3,
+  "adr_reference": "ADR-007"
+}
+```
+
+Capture trigger: Phase completion (ADR files extracted), `/mindforge:discuss-phase`
+
+### `code_pattern`
+
+Extended fields:
+
+```json
+{
+  "pattern_type": "good|anti-pattern",
+  "language":     "typescript",
+  "example_good": "// Code showing the correct pattern",
+  "example_bad":  "// Code showing the incorrect pattern (for anti-patterns)",
+  "applies_to":   ["auth", "database", "api"]
+}
+```
+
+Capture trigger: Smart compaction Block D, debug session root cause
+
+### `bug_pattern`
+
+Extended fields:
+
+```json
+{
+  "bug_category":   "auth|database|api|ui|performance|security",
+  "symptom":        "Login works in tests but fails in production with cookie errors",
+  "root_cause":     "httpOnly cookies require HTTPS; dev server was HTTP",
+  "fix":            "Enable HTTPS in dev or use secure: false in development only",
+  "prevention":     "Always configure cookie settings per-environment",
+  "severity_when_missed": "HIGH",
+  "recurrence_count": 1
+}
+```
+
+Capture trigger: Debug session completion, security findings, retrospective "what went wrong"
+
+### `team_preference`
+
+Extended fields:
+
+```json
+{
+  "preference_type": "style|tool|process|convention|architecture",
+  "applies_when":    "When implementing auth",
+  "preference":      "Always use argon2id, never bcrypt. See ADR-007.",
+  "strength":        "strong|moderate|weak",
+  "override_allowed": true
+}
+```
+
+Capture trigger: Retrospective "what should we keep doing", steering instructions,
+MINDFORGE.md changes from retrospective
+
+### `domain_knowledge`
+
+Extended fields:
+
+```json
+{
+  "domain":     "JWT security",
+  "tech_stack": ["node.js", "typescript"],
+  "knowledge":  "JWT access tokens should be short-lived (15 min). Refresh tokens in httpOnly cookies, not localStorage. Never decode JWT without verifying signature.",
+  "source_url": "https://auth0.com/docs/secure/tokens/json-web-tokens",
+  "verified_at": "2026-01-15"
+}
+```
+
+Capture trigger: Research engine output, `/mindforge:remember --add`
+
+## Confidence scoring
+
+Confidence (0.0–1.0) represents how strongly this knowledge should be applied:
+
+| Confidence | Meaning | How set |
+| :--- | :--- | :--- |
+| 0.9–1.0 | Strong team decision — always apply | Manual entry, strong steering, ADR |
+| 0.7–0.9 | Clear pattern — apply unless there's a reason not to | Retrospective, debug session |
+| 0.5–0.7 | Observed pattern — consider but verify | Smart compaction Block D |
+| 0.3–0.5 | Weak signal — informational only | Single observation |
+| < 0.3 | Hypothesis — don't apply proactively | Auto-captured, unverified |
+
+## Confidence reinforcement
+
+Each time an entry is referenced (retrieved and the advice was followed):
+
+```bash
+confidence = min(1.0, confidence + 0.05)
+times_referenced += 1
+```
+
+Each time an entry is contradicted (a different decision was made):
+
+```bash
+confidence = max(0.0, confidence - 0.10)
+```
+
+## Deprecation
+
+When a knowledge entry becomes outdated (e.g., team switches from argon2id to Passkeys):
+
+```json
+{
+  "deprecated": true,
+  "deprecated_by": "kb-uuid-of-newer-entry",
+  "deprecated_reason": "Superseded by WebAuthn/Passkeys approach (ADR-031)"
+}
+```
+
+Deprecated entries are never deleted — they are excluded from active retrieval
+but available for historical queries.

package/.mindforge/memory/engine/capture-protocol.md

@@ -0,0 +1,36 @@
+# MindForge v2 — Knowledge Capture Protocol
+
+## Purpose
+
+The Capture Engine automatically extracts valuable engineering knowledge from session artifacts to ensure that project-specific wisdom is preserved beyond a single handoff.
+
+## Capture Triggers
+
+MindForge monitors the following lifecycle events for knowledge extraction:
+
+1. **Phase Completion**: Extracting architectural decisions from `PROJECT.md` and phase retrospectives.
+2. **Hardened Debugging**: Capturing "root cause -> fix" patterns from completed debug reports.
+3. **Manual Command**: Using `/mindforge:remember --add` to explicitly record team preferences or domain knowledge.
+4. **ADR Generation**: Parsing newly created Architecture Decision Records.
+
+## Extraction Logic
+
+The extraction process (via `knowledge-capture.js`) involves:
+
+- **Structural Parsing**: Identifying standardized headings (e.g., "Decision", "Root Cause", "Pattern").
+- **Deduplication**: Checking for existing entries with similar content to prevent knowledge bloat.
+- **Initial Confidence**: Assigning a default confidence score (usually 0.5) to newly captured entries.
+- **Auto-Tagging**: Inferring tags based on the file path and content context (e.g., `#nodejs`, `#security`).
+
+## Inhibitors (What NOT to capture)
+
+To prevent the knowledge base from becoming "noisy", the system ignores:
+
+- Transient session state (e.g., local file counts).
+- Intermediate debugging steps that didn't lead to a fix.
+- Content marked with `#no-capture` or inside blocks labeled "Confidential".
+
+## Retention Policy
+
+- **Append-only**: Entries are never physically deleted.
+- **Deprecation**: Outdated entries are marked as `deprecated: true` and replaced by newer entries with the same `source_id`.