Michelkerkmeester Opencode Spec Kit Framework System Spec Kit

Spec Kit - Mandatory Conversation Documentation

Orchestrates mandatory spec folder creation for all conversations involving file modifications. Ensures proper documentation level selection (1-3+), template usage, and context preservation through AGENTS.md-enforced workflows.

1. WHEN TO USE

What is a Spec Folder?

A spec folder is a numbered directory (e.g., 007-auth-feature/) that contains documentation for a single feature/task or a coordinated packet of related phase work:

Spec folders may also be nested as coordination-root packets with direct-child phase folders (e.g., specs/02--track/022-feature/011-phase/002-child/).

• Purpose: Track specifications, plans, tasks, and decisions for one unit of work
• Location: Under specs/ using either ###-short-name/ at the root or nested packet paths for phased coordination
• Contents: Markdown files (spec.md, plan.md, tasks.md) plus optional memory/ and scratch/ subdirectories

Think of it as a "project folder" for AI-assisted development - it keeps context organized and enables session continuity.

Activation Triggers

MANDATORY for ALL file modifications:

• Code files: JS, TS, Python, CSS, HTML
• Documentation: Markdown, README, guides
• Configuration: JSON, YAML, TOML, env templates
• Templates, knowledge base, build/tooling files

Request patterns that trigger activation:

• "Add/implement/create [feature]"
• "Fix/update/refactor [code]"
• "Modify/change [configuration]"
• Any keyword: add, implement, fix, update, create, modify, rename, delete, configure, analyze, phase

Example triggers:

• "Add email validation to the signup form" → Level 1-2
• "Refactor the authentication module" → Level 2-3
• "Fix the button alignment bug" → Level 1
• "Implement user dashboard with analytics" → Level 3

When NOT to Use

• Pure exploration/reading (no file modifications)
• Single typo fixes (<5 characters in one file)
• Whitespace-only changes
• Auto-generated file updates (package-lock.json)
• User explicitly selects Option D (skip documentation)

Rule of thumb: If modifying ANY file content → Activate this skill. Status: ✅ This requirement applies immediately once file edits are requested.

Agent Exclusivity

⛔ CRITICAL: @speckit is the ONLY agent permitted to create or substantively write spec folder documentation (*.md files).

• Requires @speckit: spec.md, plan.md, tasks.md, checklist.md, decision-record.md, implementation-summary.md, and any other *.md in spec folders
• Exceptions:
  • memory/ → uses generate-context.js script
  • scratch/ → temporary workspace, any agent
  • handover.md → @handover agent only
  • research/research.md → @deep-research agent only
  • debug-delegation.md → @debug agent only

Routing to @general, @write, or other agents for spec documentation is a hard violation. See constitutional memory: speckit-exclusivity.md

Utility Template Triggers

Rule: When detected, proactively suggest the appropriate action.

2. SMART ROUTING

Resource Domains

The router discovers markdown resources recursively from references/ and assets/ and then applies intent scoring from RESOURCE_MAP. Keep this section domain-focused rather than static file inventories.

• references/memory/ for context retrieval, save workflows, trigger behavior, and indexing.
• references/templates/ for level selection, template composition, and structure guides.
• references/validation/ for checklist policy, verification rules, decision formats, and template compliance contracts.
• references/structure/ for folder organization and sub-folder versioning.
• references/workflows/ for command workflows and worked examples.
• references/debugging/ for troubleshooting and root-cause methodology.
• references/config/ for runtime environment configuration.

Template and Script Sources of Truth

• Level definitions and template size guidance: level_specifications.md
• Template usage and composition rules: template_guide.md
• Use templates/level_N/ for operational templates; core/ and addendum/ remain composition inputs.
• Use templates/changelog/ for packet-local nested changelog generation at completion time.
• Script architecture, build outputs, and runtime entrypoints: scripts/README.md
• Memory save JSON schema and workflow contracts: save_workflow.md
• Nested packet changelog workflow: nested_changelog.md

Primary operational scripts:

• spec/validate.sh
• spec/create.sh
• spec/archive.sh
• spec/check-completion.sh
• spec/recommend-level.sh
• templates/compose.sh

Resource Loading Levels

references/workflows/quick_reference.md is the primary first-touch command surface. Keep the compact spec_kit and memory command map there, and use this file only to point readers to it rather than duplicating the full matrix.

Smart Router Pseudocode

The authoritative routing logic for scoped loading, weighted intent scoring, and ambiguity handling.

from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets")
DEFAULT_RESOURCE = "references/workflows/quick_reference.md"

INTENT_SIGNALS = {
    "PLAN": {"weight": 3, "keywords": ["plan", "design", "new spec", "level selection", "option b"]},
    "RESEARCH": {"weight": 3, "keywords": ["investigate", "explore", "analyze", "prior work", "evidence"]},
    "IMPLEMENT": {"weight": 3, "keywords": ["implement", "build", "execute", "workflow"]},
    "DEBUG": {"weight": 4, "keywords": ["stuck", "error", "not working", "failed", "debug"]},
    "COMPLETE": {"weight": 4, "keywords": ["done", "complete", "finish", "verify", "checklist"]},
    "MEMORY": {"weight": 4, "keywords": ["memory", "save context", "resume", "checkpoint", "context"]},
    "HANDOVER": {"weight": 4, "keywords": ["handover", "continue later", "next session", "pause"]},
    "PHASE": {"weight": 4, "keywords": ["phase", "decompose", "split", "workstream", "multi-phase", "phased approach", "phased", "multi-session"]},
    "RETRIEVAL_TUNING": {"weight": 3, "keywords": ["retrieval", "search tuning", "fusion", "scoring", "pipeline"]},
    "EVALUATION": {"weight": 3, "keywords": ["evaluate", "ablation", "benchmark", "baseline", "metrics"]},
    "SCORING_CALIBRATION": {"weight": 3, "keywords": ["calibration", "scoring", "normalization", "decay", "interference"]},
    "ROLLOUT_FLAGS": {"weight": 3, "keywords": ["feature flag", "rollout", "toggle", "enable", "disable"]},
    "GOVERNANCE": {"weight": 3, "keywords": ["governance", "shared memory", "tenant", "retention", "audit"]},
}

RESOURCE_MAP = {
    "PLAN": [
        "references/templates/level_specifications.md",
        "references/templates/template_guide.md",
        "references/validation/template_compliance_contract.md",
    ],
    "RESEARCH": [
        "references/workflows/quick_reference.md",
        "references/workflows/worked_examples.md",
        "references/memory/epistemic_vectors.md",
    ],
    "IMPLEMENT": [
        "references/validation/validation_rules.md",
        "references/validation/template_compliance_contract.md",
        "references/templates/template_guide.md",
    ],
    "DEBUG": [
        "references/debugging/troubleshooting.md",
        "references/workflows/quick_reference.md",
        "manual_testing_playbook/MANUAL_TESTING_PLAYBOOK.md",
    ],
    "COMPLETE": [
        "references/validation/validation_rules.md",
        "references/workflows/nested_changelog.md",
    ],
    "MEMORY": [
        "references/memory/memory_system.md",
        "references/memory/save_workflow.md",
        "references/memory/trigger_config.md",
    ],
    "HANDOVER": [
        "references/workflows/quick_reference.md",
    ],
    "PHASE": [
        "references/structure/phase_definitions.md",
        "references/structure/sub_folder_versioning.md",
        "references/validation/phase_checklists.md",
    ],
    "RETRIEVAL_TUNING": [
        "references/memory/embedding_resilience.md",
        "references/memory/trigger_config.md",
    ],
    "EVALUATION": [
        "references/memory/epistemic_vectors.md",
        "references/config/environment_variables.md",
        "manual_testing_playbook/MANUAL_TESTING_PLAYBOOK.md",
    ],
    "SCORING_CALIBRATION": [
        "references/config/environment_variables.md",
    ],
    "ROLLOUT_FLAGS": [
        "references/config/environment_variables.md",
        "feature_catalog/19--feature-flag-reference/",
    ],
    "GOVERNANCE": [
        "references/config/environment_variables.md",
    ],
}

COMMAND_BOOSTS = {
    "/spec_kit:plan": "PLAN",
    "/spec_kit:implement": "IMPLEMENT",
    "/spec_kit:debug": "DEBUG",
    "/spec_kit:complete": "COMPLETE",
    "/spec_kit:handover": "HANDOVER",
    "/spec_kit:plan :with-phases": "PHASE",
    "/memory:search": "MEMORY",
    "/memory:save": "MEMORY",
    "/memory:manage": "MEMORY",
    "/memory:learn": "MEMORY",
    "/spec_kit:resume": "MEMORY",
    "/memory:manage shared": "GOVERNANCE",
}

LOADING_LEVELS = {
    "ALWAYS": [DEFAULT_RESOURCE],
    "ON_DEMAND_KEYWORDS": ["deep dive", "full validation", "full checklist", "full template"],
    "ON_DEMAND": [
        "references/validation/phase_checklists.md",
        "references/templates/template_guide.md",
    ],
}

def _task_text(task) -> str:
    parts = [
        str(getattr(task, "query", "")),
        str(getattr(task, "text", "")),
        " ".join(getattr(task, "keywords", []) or []),
        str(getattr(task, "command", "")),
    ]
    return " ".join(parts).lower()

def _guard_in_skill(relative_path: str) -> str:
    """Allow markdown loads only within this skill folder."""
    resolved = (SKILL_ROOT / relative_path).resolve()
    resolved.relative_to(SKILL_ROOT)
    if resolved.suffix.lower() != ".md":
        raise ValueError(f"Only markdown resources are routable: {relative_path}")
    return resolved.relative_to(SKILL_ROOT).as_posix()

def discover_markdown_resources() -> set[str]:
    """Recursively discover routable markdown docs for this skill only."""
    docs = []
    for base in RESOURCE_BASES:
        if base.exists():
            docs.extend(p for p in base.rglob("*.md") if p.is_file())
    return {doc.relative_to(SKILL_ROOT).as_posix() for doc in docs}

def score_intents(task) -> dict[str, float]:
    """Weighted scoring from request text, keywords, and explicit command boosts."""
    text = _task_text(task)
    scores = {intent: 0.0 for intent in INTENT_SIGNALS}

    for intent, cfg in INTENT_SIGNALS.items():
        for keyword in cfg["keywords"]:
            if keyword in text:
                scores[intent] += cfg["weight"]

    command = str(getattr(task, "command", "")).lower()
    for prefix, intent in COMMAND_BOOSTS.items():
        if command.startswith(prefix):
            scores[intent] += 6

    return scores

def select_intents(scores: dict[str, float], ambiguity_delta: float = 1.0, max_intents: int = 2) -> list[str]:
    """Return primary intent and secondary intent when scores are close."""
    ranked = sorted(scores.items(), key=lambda item: item[1], reverse=True)
    if not ranked or ranked[0][1] <= 0:
        return ["IMPLEMENT"]

    selected = [ranked[0][0]]
    if len(ranked) > 1:
        primary_score = ranked[0][1]
        secondary_intent, secondary_score = ranked[1]
        if secondary_score > 0 and (primary_score - secondary_score) <= ambiguity_delta:
            selected.append(secondary_intent)

    return selected[:max_intents]

def route_speckit_resources(task):
    """Scoped, recursive, weighted, ambiguity-aware routing."""
    inventory = discover_markdown_resources()
    intents = select_intents(score_intents(task), ambiguity_delta=1.0)
    loaded = []
    seen = set()

    def load_if_available(relative_path: str) -> None:
        guarded = _guard_in_skill(relative_path)
        if guarded in inventory and guarded not in seen:
            load(guarded)
            loaded.append(guarded)
            seen.add(guarded)

    # ALWAYS: base references for every invocation
    for relative_path in LOADING_LEVELS["ALWAYS"]:
        load_if_available(relative_path)

    # CONDITIONAL: intent-scored resources
    for intent in intents:
        for relative_path in RESOURCE_MAP.get(intent, []):
            load_if_available(relative_path)

    # ON_DEMAND: explicit deep-dive requests
    text = _task_text(task)
    if any(keyword in text for keyword in LOADING_LEVELS["ON_DEMAND_KEYWORDS"]):
        for relative_path in LOADING_LEVELS["ON_DEMAND"]:
            load_if_available(relative_path)

    if not loaded:
        load_if_available(DEFAULT_RESOURCE)

    return {"intents": intents, "resources": loaded}

3. HOW IT WORKS

Gate 3 Integration

See AGENTS.md Section 2 for the complete Gate 3 flow. This skill implements that gate.

When file modification detected, AI MUST ask:

**Spec Folder** (required): A) Existing | B) New | C) Update related | D) Skip | E) Phase folder (e.g., specs/NNN-name/001-phase/)

Enforcement: Constitutional-tier memory surfaces automatically via memory_match_triggers().

Coordination Roots: For large multi-phase efforts, the root spec.md serves as a coordination document with point-in-time snapshots of directory counts and phase status. Current tree truth takes precedence over historical synthesis (ref: ADR-001 pattern).

Complexity Detection (Option B Flow)

When user selects B) New, AI estimates complexity and recommends a level:

1. Estimate LOC, files affected, risk factors
2. Recommend level (1, 2, 3, or 3+) with rationale
3. User accepts or overrides
4. Run ./scripts/spec/create.sh --level N

Level Guidelines:

See: quick_reference.md for detailed examples.

CLI Tool:

# Create spec folder with level 2 templates
./scripts/spec/create.sh "Add OAuth2 with MFA" --level 2

# Create spec folder with level 3+ (extended) templates
./scripts/spec/create.sh "Major platform migration" --level 3+

3-Level Progressive Enhancement (CORE + ADDENDUM v2.2)

Higher levels ADD VALUE, not just length. Each level builds on the previous:

Level 1 (Core):         Essential what/why/how (~455 LOC)
         ↓ +Verify
Level 2 (Verification): +Quality gates, NFRs, edge cases (~875 LOC)
         ↓ +Arch
Level 3 (Full):         +Architecture decisions, ADRs, risk matrix (~1090 LOC)
         ↓ +Govern
Level 3+ (Extended):    +Enterprise governance, AI protocols (~1075 LOC)

Level Selection Examples:

Override Factors (can push to higher level):

• High complexity or architectural changes
• Risk (security, config cascades, authentication)
• Multiple systems affected (>5 files)
• Integration vs unit test requirements

Decision rule: When in doubt → choose higher level. Better to over-document than under-document.

Checklist as Verification Tool (Level 2+)

The checklist.md is an ACTIVE VERIFICATION TOOL, not passive documentation:

AI Workflow:

1. Load checklist.md at completion phase
2. Verify items in order: P0 → P1 → P2
3. Mark [x] with evidence for each verified item
4. Cannot claim "done" until all P0/P1 items verified

Evidence formats:

• [Test: npm test - all passing]
• [File: src/auth.ts:45-67]
• [Commit: abc1234]
• [Screenshot: evidence/login-works.png]
• (verified by manual testing)
• (confirmed in browser console)

Example checklist entry:

## P0 - Blockers
- [x] Auth flow working [Test: npm run test:auth - 12/12 passing]
- [x] No console errors [Screenshot: evidence/console-clean.png]

## P1 - Required  
- [x] Unit tests added [File: tests/auth.test.ts - 8 new tests]
- [ ] Documentation updated [DEFERRED: Will complete in follow-up PR]

Folder Naming Convention

Format: specs/###-short-name/

Rules:

• 2-3 words (shorter is better)
• Lowercase, hyphen-separated
• Action-noun structure
• 3-digit padding: 001, 042, 099 (no padding past 999)

Good examples: fix-typo, add-auth, mcp-code-mode, cli-codex Bad examples: new-feature-implementation, UpdateUserAuthSystem, fix_bug

Find next number:

ls -d specs/[0-9]*/ | sed 's/.*\/\([0-9]*\)-.*/\1/' | sort -n | tail -1

Sub-Folder Versioning

When reusing spec folders with existing content:

• Trigger: Option A selected + root-level content exists
• Pattern: 001-original/, 002-new-work/, 003-another/
• Memory: Each sub-folder has independent memory/ directory
• Tracking: Saves pass the target spec folder alongside structured JSON via the generate-context script

Example structure:

specs/007-auth-system/
├── 001-initial-implementation/
│   ├── spec.md
│   ├── plan.md
│   └── memory/
├── 002-oauth-addition/
│   ├── spec.md
│   ├── plan.md
│   └── memory/
└── 003-security-audit/
    ├── spec.md
    └── memory/

Full documentation: See sub_folder_versioning.md

Context Preservation

Manual context save (MANDATORY workflow):

• Trigger: /memory:save, "save context", or "save memory"
• MUST use: node .opencode/skill/system-spec-kit/scripts/dist/memory/generate-context.js
• NEVER: Create memory files manually via Write/Edit (AGENTS.md Memory Save Rule)
• JSON mode (PREFERRED): AI composes structured JSON → pass via --json, --stdin, or temp file. The AI has strictly better information about its own session than any DB query.
• Structured JSON fields: The JSON payload supports optional structured summary fields that improve memory quality:
  • toolCalls[] — AI-composed tool call records (tool, inputSummary, outputSummary, status)
  • exchanges[] — Key conversation turns (userInput, assistantResponse, timestamp)
  • preflight / postflight — Epistemic baseline snapshots (knowledgeScore, uncertaintyScore, contextScore, gaps[], confidence)
  • sessionSummary — Free-text session narrative (used for conversation synthesis when conversation prompts are sparse)
  • The AI has strictly better information about its own session than any DB extraction; these fields provide richer context at source.
• Location: specs/###-folder/memory/
• Filename: DD-MM-YY_HH-MM__topic.md (auto-generated by script)
• Content includes: PROJECT STATE SNAPSHOT with Phase, Last Action, Next Action, Blockers

Subfolder Support:

The generate-context script supports nested spec folder paths (parent/child format):

# Full nested path (parent/child)
node .opencode/skill/system-spec-kit/scripts/dist/memory/generate-context.js --json '{"specFolder":"system-spec-kit/121-script-audit","sessionSummary":"..."}' system-spec-kit/121-script-audit

# Bare child name (auto-searches all parents for unique match)
node .opencode/skill/system-spec-kit/scripts/dist/memory/generate-context.js --json '{"specFolder":"121-script-audit","sessionSummary":"..."}' 121-script-audit

# With specs/ prefix
node .opencode/skill/system-spec-kit/scripts/dist/memory/generate-context.js --json '{"specFolder":"specs/system-spec-kit/121-script-audit","sessionSummary":"..."}' specs/system-spec-kit/121-script-audit

# Flat folder
node .opencode/skill/system-spec-kit/scripts/dist/memory/generate-context.js --json '{"specFolder":"system-spec-kit","sessionSummary":"..."}' system-spec-kit

Memory files are always saved to the child folder's memory/ directory (e.g., specs/system-spec-kit/121-script-audit/memory/). If a bare child name matches multiple parents, the script reports an error and requires the full parent/child path.

Memory File Structure:

## Project Context
[Auto-generated summary of conversation and decisions]

## Project State Snapshot
- Phase: Implementation
- Last Action: Completed auth middleware
- Next Action: Add unit tests for login flow
- Blockers: None

## Key Artifacts
- Modified: src/middleware/auth.ts
- Created: src/utils/jwt.ts

Spec Kit Memory System (Integrated)

Context preservation across sessions via 5-channel hybrid retrieval (vector, FTS5, BM25, graph, and degree) with Reciprocal Rank Fusion, intent-aware routing, and post-fusion reranking/filtering.

Server: @spec-kit/mcp-server v1.7.2 — context-server.ts with 43 MCP tools across 7 layers. The tool surface is defined in mcp_server/tool-schemas.ts.

Memory Commands: 4 memory slash commands (/memory:save, /memory:manage, /memory:learn, /memory:search) cover the memory command surface, with shared-memory operations available under /memory:manage shared, while /spec_kit:resume owns session recovery through the broader memory/session recovery stack. The /memory:search command covers all analysis and retrieval workflows. See .opencode/command/memory/ and .opencode/command/spec_kit/resume.md for command documentation.

MCP Tools (18 most-used of 43 total — see memory_system.md for full reference):

Search architecture: The search pipeline uses a 4-stage architecture (candidate generation → fusion → reranking → filtering). Current retrieval uses five channels, normalizes fallback thresholds correctly, keeps disabled channels disabled through fallback, defers irreversible confidence truncation until after reranking, and enforces token budgets using actual post-truncation counts. See search/README.md for pipeline details, scoring algorithms, and graph signal features.

memory_context() — Mode Routing:

memory_search() — Key Rules:

• REQUIRED: query (string) OR concepts (2-5 strings). specFolder alone causes E040 error.
• Use anchors with includeContent: true for token-efficient section retrieval (~90% savings).
• Intent weights auto-adjust scoring: fix_bug boosts recency, security_audit boosts importance, refactor/understand boost similarity.
• Full parameter reference: See memory_system.md

memory_save() — Save-Time Processing:

• Runs a pre-storage quality gate (threshold 0.4 signal density). Low-quality saves receive warnings or rejection when strict. See SPECKIT_SAVE_QUALITY_GATE flag.
• An exception path allows short decision-type memories to bypass the length gate when SPECKIT_SAVE_QUALITY_GATE_EXCEPTIONS=true and at least two structural signals are present.
• Similar existing memories are auto-merged via reconsolidation (≥0.88 similarity). The save may update an existing memory instead of creating a new one. See SPECKIT_RECONSOLIDATION flag.
• A verify-fix-verify loop auto-corrects trigger phrases, anchors, and token budget (up to 2 retries).
• Preflight parses are revalidated inside the write lock when file contents change, and duplicate short-circuits verify stored content before trusting a stale hash hit.
• Delete and replacement paths now treat vector cleanup and projection replacement as integrity-critical instead of best-effort, so stale vector/projection rows do not silently survive successful writes.
• Entities are extracted and linked cross-document at save time. See SPECKIT_AUTO_ENTITIES and SPECKIT_ENTITY_LINKING flags.
• Governed save and retrieval flows can carry tenantId, userId, agentId, and sharedSpaceId so private, agent-scoped, and shared-space memory boundaries stay aligned end to end.
• Shared-memory collaboration is opt-in: use /memory:manage shared to enable rollout, create spaces, and manage deny-by-default memberships before relying on shared-space save or retrieval flows.

Epistemic Learning: Use task_preflight() before and task_postflight() after implementation to measure knowledge gains. Learning Index: LI = (KnowledgeDelta × 0.4) + (UncertaintyReduction × 0.35) + (ContextImprovement × 0.25). Review trends via memory_get_learning_history(). See epistemic_vectors.md.

Key Concepts:

• Constitutional tier — 3.0x search boost + 2.0x importance multiplier; merged into normal scoring pipeline
• Document-type scoring — 10 indexed document types with multipliers: spec (1.4x), plan (1.3x), constitutional (2.0x), decision_record (1.4x), tasks (1.1x), implementation_summary (1.1x), scratch (0.6x), checklist (1.0x), handover (1.0x), memory (1.0x). README files and skill-doc trees (sk-*, including references/ and assets/) are excluded from memory indexing.
• Decay scoring — FSRS v4 power-law model; recent memories rank higher
• Import-path hardening — MCP import paths are validated for memory runtime modules (context server and attention decay wiring)
• Metadata preservation — memory_save update/reinforce paths preserve document_type and spec_level with synchronized vector-index metadata
• Descriptive memory titles — MEMORY_TITLE is derived from the content slug via generateContentSlug() and slugToTitle(), producing unique and deterministic H1 headings. The parser falls back to feature/overview content when the top heading is generic
• Causal edge stability — conflict-update semantics maintain stable causal edge IDs during re-link and graph maintenance
• Real-time sync — Use memory_save or memory_index_scan after creating files
• Checkpoints — Gzip-compressed JSON snapshots of memory_index + working_memory; max 10 stored; transaction-wrapped restore
• Indexing persistence — After generate-context.js, call memory_index_scan() or memory_save() for immediate MCP visibility
• Artifact routing — 9 artifact classes (spec, plan, tasks, checklist, decision-record, implementation-summary, memory, research, unknown) with per-type retrieval strategies applied at query time
• Adaptive fusion — Intent-aware weighted RRF with 7 task-type profiles (fix_bug, add_feature, understand, refactor, security_audit, find_spec, find_decision), plus corrected channel fallback and normalization behavior in the live hybrid pipeline
• Adaptive ranking — Feedback-driven shadow ranking that accumulates access/outcome/correction signals and applies bounded score deltas (±0.08 max) per memory. Each signal event carries an optional query field for per-query attribution. Runs silently in shadow mode by default; promote to active ranking via SPECKIT_MEMORY_ADAPTIVE_MODE=promoted. Thresholds persist to SQLite with last_tune_watermark idempotency. Enable with SPECKIT_MEMORY_ADAPTIVE_RANKING=true.
• Causal graph diagnostics — memory_drift_why() now wraps traversal reads in a read transaction and returns truncation metadata when per-node edge caps make lineage incomplete
• Eval guardrails — Ablation reporting preserves per-channel dashboard breakdowns, treats missing query IDs explicitly, and avoids persisting synthetic zeroed token-usage snapshots as if they were measured results
• Runtime-resolved flags — Long-lived MCP processes re-read rollout and scoring flags at runtime for graph-walk rollout, co-activation, relation handling, and related search toggles instead of freezing values at import time
• Retrieval trace — Typed ContextEnvelope wraps every retrieval response with pipeline stages and a DegradedModeContract describing fallback behavior
• Mutation ledger — Append-only audit trail for all memory mutations (create, update, delete, reinforce); implemented via SQLite triggers; queryable for compliance and rollback
• Retrieval telemetry — 4-dimension metrics (latency, retrieval mode, fallback activation, quality score) plus Hydra architecture metadata. Enabled only when SPECKIT_EXTENDED_TELEMETRY=true (default: off)
• Hydra roadmap metadata — SPECKIT_MEMORY_ROADMAP_PHASE / SPECKIT_HYDRA_PHASE plus canonical SPECKIT_MEMORY_* and legacy SPECKIT_HYDRA_* capability flags annotate telemetry, eval baselines, and migration checkpoint sidecars. Note: SPECKIT_MEMORY_ADAPTIVE_RANKING=true does affect live retrieval (shadow or promoted ranking stage); the remaining roadmap flags are metadata-only.
• Feature catalog — 291 documented features across 22 categories (feature_catalog/01--retrieval/ through 22--context-preservation-and-code-graph/) document every MCP server feature with current-reality status, source files, and catalog references. Use for audit, alignment checks, and understanding what exists. See feature_catalog/
• Manual testing playbook — Operator-facing validation matrix covering existing (EX-*) and new (NEW-*) features with deterministic prompts, execution sequences, and pass/fail triage. Includes review protocol and subagent utilization ledger. See manual_testing_playbook/
• Validation scoring — wasUseful=false applies a demotion penalty to memory scores; 5+ positive validations may promote a memory's importance tier
• Tree-thinning threshold — 150 tokens with merge group cap of 3 for improved file visibility in memory context
• JSON-mode conversation synthesis — When conversation prompts are sparse (e.g., JSON-mode captures with minimal exchange data), conversation content is synthesized from sessionSummary field
• Decision deduplication — String-form decisions produce deduplicated CONTEXT/RATIONALE/CHOSEN values in memory output
• Structural blocker detection — Structural pattern detection identifies blockers (avoiding false positives from broad keyword matching)

Feature Flags:

Flags below describe live runtime behavior. Several retrieval and scoring controls are resolved at call time rather than captured once at module import, so changing process.env affects long-running MCP processes without a code reload.

…(truncated)