agent-method 1.5.12

package/docs/internal/feature-registry.yaml

@@ -0,0 +1,1643 @@
+# Feature Registry — Operational Specification
+#
+# This is NOT just a catalog. It is the agent's behavioral protocol
+# AND the computable source of truth for routing automation.
+# Four layers:
+#   1. Feature catalog — WHAT each capability is
+#   2. Guided workflows — HOW features compose into task patterns
+#   3. Agent protocol — WHY the agent does what it does
+#   4. Routing rules — HOW queries map to features automatically
+#
+# The entry point, scoping rules, and cascade table in any project
+# are concrete implementations derived from this registry.
+# Tools read this file to generate entry points, classify queries,
+# and validate behavior.
+
+version: v1.6
+
+# ============================================================
+# LAYER 1: FEATURE CATALOG
+# What each capability is, when it triggers, what it touches
+# ============================================================
+
+domains:
+  - id: CTX
+    name: Context management
+    purpose: Build and maintain the agent's understanding of the project so every session starts informed
+    project_types: [universal]
+  - id: QRY
+    name: Query routing
+    purpose: Ensure the agent reads the right files and only the right files for each task
+    project_types: [universal]
+  - id: STT
+    name: State management
+    purpose: Preserve decisions, uncertainties, and position across sessions so nothing is lost
+    project_types: [universal]
+  - id: TSK
+    name: Task execution
+    purpose: Structure work into verifiable units so progress is measurable and auditable
+    project_types: [universal]
+  - id: HAI
+    name: Human-agent interaction
+    purpose: Give the human control over agent autonomy and keep both audiences served
+    project_types: [universal]
+  - id: TPL
+    name: Template and bootstrap
+    purpose: Get a new project from zero to working agent collaboration in minutes
+    project_types: [universal]
+  - id: EXP
+    name: Data exploration
+    purpose: Build structured understanding of user-submitted data and provide interactive access
+    project_types: [data]
+
+  - id: SCAN
+    name: Project discovery
+    purpose: Inventory, map, and assess existing projects so the agent builds understanding before contributing
+    project_types: [universal]
+
+features:
+  # --- Context management ---
+  - id: CTX-01
+    name: initContext
+    domain: CTX
+    project_types: [universal]
+    description: Initialize the .context/ structure for a new or existing project
+    trigger: Project bootstrap (first session after template copy)
+    reads: [PROJECT.md, project directory structure]
+    writes: [.context/BASE.md]
+    options:
+      mode: [greenfield, brownfield]
+    dependencies: [TPL-01]
+    stage: on_demand
+    version: v1
+    type_variants:
+      code: Scan directory tree, map modules, technology stack, build system
+      data: Scan data sources, build data inventory, identify schemas
+      analytical: Discover chains, map components, identify pipeline stages
+    agent_directive: >
+      On first session, detect whether this is a new or existing project.
+      For greenfield: create BASE.md with empty project map ready to fill.
+      For brownfield: scan the project structure and populate the map
+      so future sessions understand the project immediately.
+
+  - id: CTX-02
+    name: refreshContext
+    domain: CTX
+    project_types: [universal]
+    description: Rescan the project and update .context/ files to match current reality
+    trigger: User requests context refresh; agent detects stale context; return after significant external changes
+    reads: [".context/*", "project directory structure", "recent git changes"]
+    writes: [".context/BASE.md", ".context/{affected specialists}", "entry point"]
+    options:
+      scope: [full, incremental]
+    dependencies: [CTX-05]
+    stage: on_demand
+    version: v1
+    type_variants:
+      code: Compare codebase map against directory structure, updated deps
+      data: Compare data map against data sources for new data, schema changes
+      analytical: Compare pipeline map against system state for new stages, changed rules
+    agent_directive: >
+      Projects evolve between sessions. Context files that don't match reality
+      cause the agent to make wrong assumptions. When triggered, compare
+      what .context/ says against what actually exists. Update the project
+      map, flag drift, and ensure future sessions start with accurate context.
+
+  - id: CTX-03
+    name: pairContext
+    domain: CTX
+    project_types: [universal]
+    description: Load the appropriate context pair (BASE + specialist) for a query type
+    trigger: Every query after cold start
+    reads: ["entry point scoping table", ".context/BASE.md", ".context/{matched specialist}"]
+    writes: []
+    dependencies: [QRY-02]
+    stage: scope
+    version: v1
+    type_variants:
+      code: "BASE + code specialist (API.md, DATABASE.md, TESTING.md, etc.)"
+      data: "BASE + data specialist (SCHEMA.md, DOCUMENTS.md, RELATIONSHIPS.md)"
+      analytical: "BASE + domain specialist (COMPOSITION.md, EVALUATION.md, EXECUTION.md, etc.)"
+    agent_directive: >
+      Never load all context files. Load BASE.md (always) plus exactly one
+      specialist matched to the query type. This keeps context focused and
+      prevents the agent from being overwhelmed with irrelevant information.
+
+  - id: CTX-04
+    name: growContext
+    domain: CTX
+    project_types: [universal]
+    description: Create a new specialist context file when a new domain area is identified
+    trigger: Agent recognizes recurring domain not covered by existing specialists; user explicitly requests
+    reads: [.context/BASE.md, entry point, relevant source files]
+    writes: [".context/{SPECIALIST}.md", ".context/BASE.md", "entry point"]
+    dependencies: [CTX-01]
+    stage: execute
+    version: v1
+    type_variants:
+      code: New code domain → new specialist (e.g., SECURITY.md when auth code grows)
+      data: New data dimension → new specialist or expanded existing
+      analytical: New pipeline stage → new specialist
+    agent_directive: >
+      As a project grows, new domain areas emerge that need their own context.
+      When you notice recurring questions about a domain not covered by existing
+      specialists, propose a new specialist file. This makes future sessions
+      in that domain more efficient.
+
+  - id: CTX-05
+    name: mapProject
+    domain: CTX
+    project_types: [universal]
+    description: Generate or update the project map section in BASE.md
+    trigger: CTX-01 bootstrap, CTX-02 refresh, cascade from project structure change
+    reads: [project directory structure, package files, key source files]
+    writes: [.context/BASE.md]
+    options:
+      mode: [codebase, data-sources, domain-chains]
+      depth: [shallow, deep]
+    dependencies: []
+    stage: execute
+    version: v1.1
+    type_variants:
+      codebase: Walk directory tree, record path/purpose/patterns/dependencies
+      data-sources: Scan data sources, record source/type/size/keys/dimensions
+      domain-chains: Trace input→transformation→output flows, record chains/components
+    agent_directive: >
+      The project map is the agent's working memory of the project structure.
+      For code: walk directories, record what each does and what patterns it uses.
+      For data: scan sources, record schemas, relationships, and dimensions.
+      For analytical systems: trace transformation chains and map components.
+      This map is what allows the agent to navigate without re-exploring every session.
+
+  - id: CTX-06
+    name: manageScale
+    domain: CTX
+    project_types: [universal]
+    description: Monitor file size, restructure into index + components when threshold exceeded, maintain navigation registry
+    trigger: After any file write that increases an intelligence layer file beyond 300 lines; after any file split, creation, deletion, or rename
+    reads: [affected file, .context/REGISTRY.md]
+    writes: [affected file (rewritten as index), new component subdirectory/files, .context/REGISTRY.md]
+    options:
+      threshold: [300]
+      grouping: [semantic, chronological]
+    dependencies: [QRY-03]
+    stage: execute
+    version: v1.2
+    type_variants:
+      all: >
+        Index keeps active/current content + navigation table linking to components.
+        Components are archived sections grouped by semantic boundary (phases, domains, time periods).
+        Subdirectory named after the file stem (e.g., SUMMARY.md -> summary/).
+        Navigation registry (.context/REGISTRY.md) tracks all files, topics, and structural changes.
+    agent_directive: >
+      After writing to an intelligence layer file, check its line count.
+      If it exceeds 300 lines, restructure: keep active content in the
+      original file (now an index with navigation table), move archived
+      sections to a subdirectory named after the file stem. Group archived
+      content by semantic boundaries. The index must remain self-sufficient
+      for current work — components hold history, not active state.
+      After ANY structural change (split, create, delete, rename), update
+      .context/REGISTRY.md: file tree (add/remove entries, update line counts),
+      topic index (add/redirect/remove entries), structural log (record what
+      happened and why). The registry is the agent's fast-lookup map — one
+      read gives the full picture of where content lives.
+
+  # --- Query routing ---
+  - id: QRY-01
+    name: coldStart
+    domain: QRY
+    project_types: [universal]
+    description: Two-file initialization protocol for every new session
+    trigger: Session start (always)
+    reads: [entry point, STATE.md]
+    writes: []
+    dependencies: []
+    stage: initialize
+    version: v1
+    agent_directive: >
+      Every session begins by reading exactly two files: the entry point
+      and STATE.md. This gives you scoping rules, cascade table, conventions,
+      current position, prior decisions, and open questions. Do not load
+      anything else until a query arrives.
+
+  - id: QRY-02
+    name: scopeQuery
+    domain: QRY
+    project_types: [universal]
+    description: Classify a human query and load the appropriate file set
+    trigger: Every human query after cold start
+    reads: [entry point scoping table]
+    writes: []
+    dependencies: [QRY-01]
+    stage: scope
+    version: v1
+    agent_directive: >
+      Match the user's query against the scoping table. Load the read-set.
+      Constrain writes to the write-set. If the query doesn't match any row
+      cleanly, ask the user to clarify before loading files. Tables are
+      your routing logic — follow them deterministically.
+
+  - id: QRY-03
+    name: cascadeUpdate
+    domain: QRY
+    project_types: [universal]
+    description: After a file change, propagate updates through the dependency chain
+    trigger: Any file change during execute or close stages
+    reads: [entry point cascade table]
+    writes: [dependent files per cascade rules]
+    dependencies: [QRY-02]
+    stage: execute
+    version: v1
+    agent_directive: >
+      After EVERY file change, check the cascade table. If the change matches
+      a trigger, update the dependent files in the same response. Deferred
+      cascades don't happen. Check for secondary cascades up to 2 levels deep.
+
+  # --- State management ---
+  - id: STT-01
+    name: recordDecision
+    domain: STT
+    project_types: [universal]
+    description: Capture decisions in STATE.md immediately when made
+    trigger: Agent makes or recognizes a decision during any stage
+    reads: [STATE.md]
+    writes: [STATE.md]
+    dependencies: []
+    stage: execute
+    version: v1
+    agent_directive: >
+      When you make a decision, write it to STATE.md in the SAME RESPONSE
+      as the work that produced it. Never defer. If deferred, it's lost.
+
+  - id: STT-02
+    name: flagUncertainty
+    domain: STT
+    project_types: [universal]
+    description: Track open questions as first-class artifacts in STATE.md
+    trigger: Agent encounters an ambiguity, unknown, or needs human input
+    reads: [STATE.md]
+    writes: [STATE.md]
+    dependencies: []
+    stage: plan
+    version: v1
+    agent_directive: >
+      When you're unsure, write it as an open question in STATE.md.
+      Do not guess silently. When resolved, strike through and add
+      resolution text — don't delete.
+
+  - id: STT-03
+    name: trackPosition
+    domain: STT
+    project_types: [universal]
+    description: Maintain the current phase and status in STATE.md
+    trigger: Phase transitions, task completion, session close
+    reads: [STATE.md]
+    writes: [STATE.md]
+    dependencies: [TSK-03]
+    stage: close
+    version: v1
+    agent_directive: >
+      STATE.md "Current position" must always reflect: what phase, what status
+      within it, what comes next, and what context is active.
+
+  # --- Task execution ---
+  - id: TSK-01
+    name: planTask
+    domain: TSK
+    project_types: [universal]
+    description: Create a structured PLAN.md with substeps and verification criteria
+    trigger: Start of a new task (plan stage)
+    reads: [REQUIREMENTS.md, ROADMAP.md, relevant .context/]
+    writes: [PLAN.md]
+    options:
+      detail: [minimal, standard, detailed]
+    dependencies: [HAI-01]
+    stage: plan
+    version: v1
+    agent_directive: >
+      Produce a plan with: objective, prerequisites, steps with read/produce
+      specs, and verification criteria. Plans are atomic — one task at a time.
+      Propose and wait for approval before executing.
+
+  - id: TSK-02
+    name: verifyTask
+    domain: TSK
+    project_types: [universal]
+    description: Check completed work against embedded verification criteria
+    trigger: Verify stage (after execution)
+    reads: [PLAN.md]
+    writes: [verification results in SUMMARY.md]
+    dependencies: [TSK-01]
+    stage: verify
+    version: v1
+    agent_directive: >
+      Read verification criteria from PLAN.md. Check each against completed
+      work. Report pass/fail with specific evidence.
+
+  - id: TSK-03
+    name: closeSession
+    domain: TSK
+    project_types: [universal]
+    description: Execute the close stage - SUMMARY, STATE, ROADMAP updates
+    trigger: Task or session completion
+    reads: [SUMMARY.md, STATE.md, ROADMAP.md]
+    writes: [SUMMARY.md, STATE.md, ROADMAP.md]
+    dependencies: [TSK-04, QRY-03]
+    stage: close
+    version: v1
+    agent_directive: >
+      Write SUMMARY.md entry. Update STATE.md position. Mark ROADMAP.md
+      if phase complete. Non-negotiable phase completion cascade.
+
+  - id: TSK-04
+    name: auditTrail
+    domain: TSK
+    project_types: [universal]
+    description: Maintain SUMMARY.md in the standard session entry format
+    trigger: TSK-03 closeSession
+    reads: [session work products, STATE.md]
+    writes: [SUMMARY.md]
+    dependencies: []
+    stage: close
+    version: v1
+    agent_directive: >
+      Each SUMMARY entry: date, plan, outcome, files created/updated,
+      decisions captured, next. The "Next" field bridges to the following session.
+
+  # --- Human-agent interaction ---
+  - id: HAI-01
+    name: checkpoint
+    domain: HAI
+    project_types: [universal]
+    description: Surface a plan proposal for human approval before execution
+    trigger: Plan stage (skipped at autonomous level)
+    reads: [proposed plan]
+    writes: []
+    dependencies: [HAI-02]
+    stage: plan
+    version: v1
+    agent_directive: >
+      Present your plan and WAIT for human approval. This is the PRIMARY
+      CHECKPOINT. A wrong plan executed perfectly is still failure.
+
+  - id: HAI-02
+    name: setInteractionLevel
+    domain: HAI
+    project_types: [universal]
+    description: Configure the checkpoint density for a session
+    trigger: Entry point mode setting read during cold start
+    reads: [entry point]
+    writes: []
+    options:
+      level: [autonomous, checkpoint, collaborative, supervised]
+    dependencies: [QRY-01]
+    stage: initialize
+    version: v1
+    agent_directive: >
+      Read the mode setting. It controls how often you pause. Default
+      is checkpoint. Respect the configured level.
+
+  - id: HAI-03
+    name: dualAudience
+    domain: HAI
+    project_types: [universal]
+    description: Maintain separation between agent-facing and human-facing files
+    trigger: Any file write during execute or close stages
+    reads: [entry point docs trigger mapping]
+    writes: [agent files, human files per trigger mapping]
+    dependencies: [HAI-04]
+    stage: execute
+    version: v1
+    agent_directive: >
+      Agent files (STATE.md, .context/) are for machine parsing.
+      Human files (docs/) use visual formats. Never mix audiences.
+
+  - id: HAI-04
+    name: docsTrigger
+    domain: HAI
+    project_types: [universal]
+    description: Update docs/ based on the trigger mapping in the entry point
+    trigger: Structural changes matching entry point docs maintenance table
+    reads: [entry point docs trigger table]
+    writes: [specific docs/ files per trigger]
+    dependencies: [HAI-03]
+    stage: close
+    version: v1
+    agent_directive: >
+      When structural changes match a trigger, update specified docs/ files.
+      Typo fixes and internal adjustments do NOT trigger docs updates.
+
+  - id: HAI-05
+    name: modelCapabilityCheck
+    domain: HAI
+    project_types: [universal]
+    description: Detect when the agent consistently fails methodology requirements due to model capability limitations
+    trigger: Agent detects repeated pattern failures (missed cascades, forgotten decisions, shallow context, incomplete discovery)
+    reads: [STATE.md, entry point, session history]
+    writes: [STATE.md (open question with capability warning)]
+    dependencies: []
+    stage: execute
+    version: v1
+    degradation_signals:
+      - pattern: Cascade misses — file changed but dependent files not updated in same response
+        threshold: 2+ misses in a session
+        recommendation: Switch to Sonnet or higher for this task type
+      - pattern: Decision recording failures — decisions made but not written to STATE.md
+        threshold: Any deferred decision recording
+        recommendation: Simpler model may not handle simultaneous work + recording
+      - pattern: Shallow context — .context/ files populated with generic content lacking project-specific detail
+        threshold: Context quality score < 3 (from protocol tools)
+        recommendation: Discovery tasks (WF-08) require Sonnet+; use Haiku only for greenfield/simple workflows
+      - pattern: Incomplete discovery — SCAN features produce shallow inventories missing architectural patterns
+        threshold: Brownfield scan misses >30% of project structure
+        recommendation: WF-08 requires Sonnet+ capability; Haiku cannot handle discovery
+      - pattern: Instruction loss — agent stops following entry point conventions mid-session
+        threshold: Conventions violated after being followed earlier in same session
+        recommendation: Entry point may exceed model's effective context window; switch to lite profile
+    agent_directive: >
+      Monitor your own methodology adherence. If you notice you are repeatedly
+      missing cascades, forgetting to update STATE.md, producing shallow context,
+      or losing track of entry point conventions, surface this to the user:
+      "I'm noticing degraded methodology adherence — this task may benefit from
+      a more capable model (Sonnet/Opus) or a lighter integration profile."
+      Record the observation as an open question in STATE.md.
+
+  - id: HAI-06
+    name: writeObligations
+    domain: HAI
+    project_types: [universal]
+    description: Enforce close-stage write obligations via PROTOCOL.yaml close_check
+    trigger: End of any file-modifying response
+    reads: [".context/PROTOCOL.yaml (close_check section)", "registry/doc-tokens.yaml (terminology consistency)"]
+    writes: [STATE.md, SUMMARY.md, ROADMAP.md, SESSION-LOG.md, "Management/DIGEST.md", "Management/STATUS.md", ".context/BASE.md", ".context/DOCS-MAP.md", "registry/doc-tokens.yaml"]
+    dependencies: [HAI-04, QRY-03]
+    stage: close
+    version: v1.6
+    agent_directive: >
+      Before ending any response that modified files, read PROTOCOL.yaml close_check.
+      For each triggered item, update the target file now. A response that modifies
+      files but skips triggered obligations is incomplete. This is the final self-audit
+      before the response ends.
+
+  # --- Template and bootstrap ---
+  - id: TPL-01
+    name: bootstrap
+    domain: TPL
+    project_types: [universal]
+    description: Initialize a project from the template with guided content
+    trigger: First session on a new project
+    reads: [template files, "registry/feature-registry.yaml", "registry/doc-tokens.yaml"]
+    writes: [PROJECT.md, .context/BASE.md, STATE.md, "registry/doc-tokens.yaml"]
+    options:
+      template: [starter, full]
+    dependencies: [CTX-01, TPL-02]
+    stage: on_demand
+    version: v1.6
+    agent_directive: >
+      Read guided content. Help user fill PROJECT.md. Run initContext.
+      For brownfield: use segmented onboarding (5 segments driven by doc-tokens.yaml
+      categories). Populate doc-tokens.yaml with project identity, terminology,
+      and propagation targets during onboarding. Reference feature-registry.yaml
+      to determine applicable workflows and query types.
+
+  - id: TPL-02
+    name: detectRuntime
+    domain: TPL
+    project_types: [universal]
+    description: Determine which entry point file is active
+    trigger: Cold start (implicit)
+    reads: [loaded entry point file]
+    writes: []
+    dependencies: []
+    stage: initialize
+    version: v1
+    agent_directive: >
+      Templates ship all three variants. Runtime auto-loads the appropriate one.
+
+  - id: TPL-03
+    name: structureSelect
+    domain: TPL
+    project_types: [universal]
+    description: Choose template tier based on project complexity
+    trigger: TPL-01 bootstrap or user upgrade request
+    reads: [PROJECT.md, user input]
+    writes: [additional template files if upgrading]
+    options:
+      tier: [starter, full]
+    dependencies: [TPL-01]
+    stage: on_demand
+    version: v1
+    agent_directive: >
+      Starter for most projects. Full when project has multiple phases
+      or needs dual-audience separation. Offer upgrade path.
+
+  # --- Data exploration ---
+  - id: EXP-01
+    name: ingestData
+    domain: EXP
+    project_types: [data]
+    description: Scan submitted data sources, classify by type, sample content, measure scale, detect quality signals
+    trigger: User submits new data source (CSV, database, repo, document set)
+    reads: [data source, .context/BASE.md]
+    writes: [.context/BASE.md (data inventory), specialist stubs]
+    options:
+      source_type: [structured, repository, documents, mixed]
+    dependencies: [CTX-01]
+    stage: on_demand
+    version: v1.1
+    agent_directive: >
+      When data is submitted, scan for structure (columns, types, file names,
+      directory layout). Sample content. Measure scale (row counts, file counts).
+      Detect quality signals (null rates, duplicates, encoding). Present
+      findings to user. Do NOT try to understand everything — map the surface
+      first, deep understanding comes in the Map stage.
+
+  - id: EXP-02
+    name: buildReferences
+    domain: EXP
+    project_types: [data]
+    description: Transform raw data mapping into structured reference artifacts
+    trigger: After EXP-01 ingest and CTX-05 mapping, or user requests reference building
+    reads: [.context/BASE.md, relevant specialist, data sources]
+    writes: [specialist context files (entity registries, topic taxonomies, dimension indices, metric catalogs)]
+    dependencies: [EXP-01, CTX-05]
+    stage: execute
+    version: v1.1
+    agent_directive: >
+      Build navigable reference artifacts from the data map. Entity registries,
+      topic taxonomies, queryable dimension indices, derived metric catalogs.
+      References are the bridge between raw data and interactive exploration.
+      Each reference entry must be addressable, cross-linked, and source-attributed.
+
+  - id: EXP-03
+    name: exploreCommand
+    domain: EXP
+    project_types: [data]
+    description: Recognize and execute named exploration patterns consistently
+    trigger: User query matching an exploration command pattern
+    reads: [.context/BASE.md, relevant specialist per command type]
+    writes: [STATE.md (exploration path)]
+    options:
+      commands: [explore, schema, search, relate, quality, timeline, dimensions, gaps, summary]
+    dependencies: [QRY-02, CTX-03]
+    stage: execute
+    version: v1.1
+    agent_directive: >
+      Recognize named exploration patterns in user queries. Each command
+      maps to a specific specialist and action. Most exploration queries
+      are read-only — they don't produce file changes. Progressively reveal
+      available commands as the user explores.
+
+  - id: EXP-04
+    name: manageAbstraction
+    domain: EXP
+    project_types: [data]
+    description: Navigate the abstraction ladder, deciding when to access raw data vs references
+    trigger: Any data query during exploration
+    reads: [.context/BASE.md, relevant specialist]
+    writes: []
+    dependencies: [EXP-03]
+    stage: execute
+    version: v1.1
+    agent_directive: >
+      Work at Level 2-3 (summaries and references) by default. Drop to
+      Level 0-1 (raw data, schema) only for specific queries that require
+      actual data values. Context files contain understanding, not data.
+      If a recurring query needs Level 0 access, propose adding the result
+      as a derived metric or reference in the specialist.
+
+  # --- Project discovery ---
+  - id: SCAN-01
+    name: codebaseInventory
+    domain: SCAN
+    project_types: [universal]
+    description: Walk the project structure and build a complete inventory of directories, files, modules, and their purposes
+    trigger: Discovery stage entry (brownfield bootstrap, methodology first applied to existing project, major re-assessment)
+    reads: [project directory structure, package files, entry points, key source files, "registry/doc-tokens.yaml"]
+    writes: [.context/BASE.md (project map), "registry/doc-tokens.yaml (project identity, terminology)"]
+    options:
+      depth: [shallow, deep]
+    dependencies: [CTX-05]
+    stage: on_demand
+    version: v1.4
+    type_variants:
+      code: Walk directory tree, identify modules, map build system, record technology stack
+      data: Scan data directories, inventory data files, identify schema sources
+      analytical: Trace pipeline components, inventory chain stages, map orchestration config
+    agent_directive: >
+      Walk the entire project directory structure. For each significant directory
+      and file, record: path, purpose (inferred from names, contents, conventions),
+      key patterns, and dependencies. The inventory is the foundation — you cannot
+      contribute effectively to code you haven't mapped. Output goes into the
+      project map section of BASE.md.
+
+  - id: SCAN-02
+    name: dependencyMapping
+    domain: SCAN
+    project_types: [universal]
+    description: Map all internal and external dependencies — packages, modules, services, data flows
+    trigger: SCAN-01 inventory (cascade), explicit dependency analysis request
+    reads: [package manifests, import statements, configuration files, .context/BASE.md]
+    writes: [.context/BASE.md (dependencies section)]
+    dependencies: [SCAN-01]
+    stage: on_demand
+    version: v1.4
+    type_variants:
+      code: Parse package.json/Cargo.toml/requirements.txt, trace import graphs, map service dependencies
+      data: Map data source connections, trace ETL flows, identify schema dependencies
+      analytical: Map chain dependencies, trace data flows between pipeline stages
+    agent_directive: >
+      After the inventory, map how pieces connect. Parse package manifests for
+      external dependencies. Trace imports for internal module dependencies.
+      Identify service-to-service connections. Record version constraints.
+      This map tells you what breaks when something changes — essential for
+      cascade accuracy and safe modifications.
+
+  - id: SCAN-03
+    name: patternExtraction
+    domain: SCAN
+    project_types: [universal]
+    description: Identify recurring code patterns, conventions, and architectural decisions in the existing project
+    trigger: SCAN-01 inventory (cascade), explicit pattern analysis request, Evolution stage refactoring
+    reads: [source files (sampled), .context/BASE.md, existing .context/ specialists]
+    writes: [.context/ specialists (proposed), STATE.md (architectural decisions discovered)]
+    dependencies: [SCAN-01]
+    stage: on_demand
+    version: v1.4
+    type_variants:
+      code: Identify naming conventions, error handling patterns, test patterns, API design patterns
+      data: Identify data modeling patterns, query patterns, transformation conventions
+      analytical: Identify composition patterns, evaluation approaches, orchestration conventions
+    agent_directive: >
+      Sample key files across the project. Identify recurring patterns:
+      naming conventions, error handling, testing approach, architectural patterns,
+      design decisions embedded in the code. Each pattern is a convention the agent
+      must follow in future work. Patterns become specialist file candidates.
+      Record discovered architectural decisions in STATE.md — these are decisions
+      that were already made, just not documented.
+
+  - id: SCAN-04
+    name: debtAssessment
+    domain: SCAN
+    project_types: [universal]
+    description: Identify technical debt, inconsistencies, security concerns, and improvement opportunities
+    trigger: Explicit assessment request, Discovery stage completion, Evolution stage periodic review
+    reads: [.context/BASE.md, .context/ specialists, source files (targeted)]
+    writes: [STATE.md (open questions for debt items), PLAN.md (remediation priorities if requested)]
+    dependencies: [SCAN-01, SCAN-03]
+    stage: on_demand
+    version: v1.4
+    type_variants:
+      code: Outdated dependencies, missing tests, inconsistent patterns, security vulnerabilities, dead code
+      data: Stale data, missing validation, undocumented schemas, quality gaps
+      analytical: Outdated evaluation criteria, untested chains, missing documentation
+    agent_directive: >
+      Based on the inventory and patterns, identify areas of concern:
+      outdated dependencies, missing tests, inconsistent conventions, security
+      issues, dead code, documentation gaps. Each finding becomes an open
+      question in STATE.md with severity assessment. Do NOT attempt to fix
+      everything — assess and prioritize. The human decides what to address.
+
+  - id: SCAN-05
+    name: docDependencyGraph
+    domain: SCAN
+    project_types: [universal]
+    description: Build and maintain document dependency graph in doc-tokens.yaml during brownfield onboarding and close
+    trigger: Brownfield Segment 2 (Architecture scan), wwa close (growth tracking), wwa init (default seeding)
+    reads: [registry/doc-tokens.yaml, .context/DOCS-MAP.md, docs/ directory]
+    writes: [registry/doc-tokens.yaml (doc_graph section)]
+    dependencies: [SCAN-01, SCAN-02]
+    stage: on_demand
+    version: v1.6
+    type_variants:
+      code: API docs, database schemas, architecture docs dependency chains
+      data: Schema docs, data catalog, pipeline documentation dependency chains
+      analytical: Evaluation criteria, prompt templates, domain knowledge dependency chains
+    agent_directive: >
+      During brownfield onboarding Segment 2, scan the docs/ directory and build a
+      dependency graph. Create nodes for each document file, identify cross-references
+      (markdown links, .context/ references), and create typed edges (reads_from,
+      cascades_to). Write the graph to doc-tokens.yaml doc_graph section. During
+      close, detect new files and add them as nodes with category: unknown.
+
+  - id: SCAN-06
+    name: docReviewGenerate
+    domain: SCAN
+    project_types: [universal]
+    description: Generate internal document registry (docs/internal/doc-registry.yaml + .md) from dependency graph
+    trigger: Explicit wwa doc-review command, post-onboarding review
+    reads: [registry/doc-tokens.yaml (doc_graph, project_names), .context/DOCS-MAP.md]
+    writes: [docs/internal/doc-registry.yaml, docs/internal/doc-registry.md]
+    dependencies: [SCAN-05]
+    stage: on_demand
+    version: v1.6
+    agent_directive: >
+      Synthesize the document dependency graph, project terminology, and docs inventory
+      into a structured registry at docs/internal/. The YAML file provides machine-readable
+      data (dependency graph, terminology, health metrics). The markdown file provides
+      human-readable views (dependency tree, glossary, health dashboard, cross-reference
+      index). This registry can be included in case studies and management reports via
+      the --internal-registry flag on casestudy and close commands.
+
+  - id: SCAN-07
+    name: boundariesConfig
+    domain: SCAN
+    project_types: [universal]
+    description: Configurable project boundaries via PROTOCOL.yaml — path resolution, visibility, scan rules, distribution
+    trigger: Brownfield onboarding with non-standard paths, self-hosting projects, custom distribution rules
+    reads: [.context/PROTOCOL.yaml (boundaries section)]
+    writes: [.context/PROTOCOL.yaml (boundaries section)]
+    dependencies: [SCAN-01]
+    stage: on_demand
+    version: v1.6
+    agent_directive: >
+      When a project stores registries at non-standard paths (e.g. docs/internal/ instead
+      of .context/), uncomment and configure the boundaries section in PROTOCOL.yaml.
+      The boundaries section controls: registry paths (tokens, docs_map, output), visibility
+      classification (internal vs release folders), scan rules (include/exclude), and
+      distribution rules (git/npm include/exclude). All CLI tools read boundaries to resolve
+      paths. Projects without a boundaries section get default behavior (backward compatible).
+
+# ============================================================
+# LAYER 2: GUIDED WORKFLOWS
+# How features compose into reusable task patterns.
+# ============================================================
+
+workflows:
+  - id: WF-01
+    name: standard-task
+    project_types: [universal]
+    description: >
+      The default workflow for any task. Review current state, plan the work,
+      implement changes, update documentation and context, close with
+      management file updates. This is the backbone pattern.
+    steps:
+      - name: review
+        stage: scope
+        description: Read current state, understand context, identify what needs to change
+        features: [QRY-01, QRY-02, CTX-03]
+        agent_action: >
+          Load entry point + STATE.md (cold start). Classify the query.
+          Load the scoped context. Understand the current position and
+          what decisions have been made. Read relevant files.
+      - name: plan
+        stage: plan
+        description: Propose structured plan with verification criteria
+        features: [TSK-01, HAI-01, STT-02]
+        agent_action: >
+          Draft a plan with objectives, steps, read/produce specs, and
+          verification criteria. Surface any unknowns as open questions.
+          Present to human for approval. Wait before executing.
+      - name: implement
+        stage: execute
+        description: Execute plan, record decisions, cascade changes
+        features: [STT-01, QRY-03, CTX-05, HAI-03]
+        agent_action: >
+          Follow the plan step by step. After each file change, check
+          cascades and update dependent files. Record every decision in
+          STATE.md immediately. If the project structure changed, update
+          the map in BASE.md.
+      - name: document
+        stage: execute
+        description: Update context files and triggered docs
+        features: [CTX-04, CTX-05, HAI-04]
+        agent_action: >
+          If new domain areas were discovered, propose specialist context
+          files. Update BASE.md map if structure changed. Check docs
+          trigger table and update human-facing docs if structural changes.
+      - name: update
+        stage: close
+        description: Close session with audit trail and position update
+        features: [TSK-03, TSK-04, STT-03]
+        agent_action: >
+          Write SUMMARY.md entry. Update STATE.md position. Mark ROADMAP.md
+          if phase complete. The "Next" field bridges to the next session.
+
+  - id: WF-02
+    name: code-change
+    project_types: [code]
+    description: >
+      When the user asks to modify code. The agent doesn't just change files —
+      it maintains the project's understanding of itself.
+    steps:
+      - name: review
+        stage: scope
+        description: Understand what exists before changing it
+        features: [QRY-01, QRY-02, CTX-03]
+        agent_action: >
+          Load context for the relevant domain. Read the files that will
+          be affected. Read tests first. Understand dependencies.
+      - name: plan
+        stage: plan
+        description: Propose code changes with cascade impacts identified
+        features: [TSK-01, HAI-01]
+        agent_action: >
+          Plan the code change. Identify cascade triggers. List all files
+          affected (direct + cascade). Include context updates in the plan.
+      - name: implement
+        stage: execute
+        description: Make changes, cascade, update context
+        features: [STT-01, QRY-03, CTX-05]
+        agent_action: >
+          Make the code change. Immediately cascade to dependent files.
+          Update .context/BASE.md codebase map if structure changed.
+          Record the decision in STATE.md.
+      - name: context-sync
+        stage: execute
+        description: Ensure future sessions understand the change
+        features: [CTX-04, CTX-05, HAI-03]
+        agent_action: >
+          This is the key step. Update the codebase map so the next session
+          knows about the new code. If a new domain emerged, propose a
+          specialist. The agent is building understanding for its future self.
+      - name: update
+        stage: close
+        description: Record and close
+        features: [TSK-03, TSK-04, STT-03]
+        agent_action: Write audit trail. Update position. Bridge to next session.
+
+  - id: WF-03
+    name: context-refresh
+    project_types: [universal]
+    description: >
+      Resync the agent's understanding with the actual project state.
+      Used when the project has changed significantly between sessions.
+    steps:
+      - name: scan
+        stage: scope
+        description: Read current .context/ and compare against reality
+        features: [QRY-01, CTX-02]
+        agent_action: >
+          Load all .context/ files. Scan the actual project structure.
+          Identify drift: new items, removed items, renamed files,
+          updated dependencies.
+      - name: compare
+        stage: plan
+        description: Identify what's stale and what's missing
+        features: [CTX-05]
+        agent_action: >
+          Build a diff between what .context/ says and what exists.
+          Flag significant drift to the user.
+      - name: update-context
+        stage: execute
+        description: Rewrite context files to match reality
+        features: [CTX-05, CTX-04]
+        agent_action: >
+          Update BASE.md project map. Update affected specialist files.
+          If new domain areas are discovered, propose new specialists.
+      - name: cascade
+        stage: execute
+        description: Propagate context changes
+        features: [QRY-03]
+        agent_action: >
+          If scoping rules or cascade rules need updating,
+          update the entry point.
+      - name: record
+        stage: close
+        description: Log what changed and why
+        features: [STT-01, TSK-04]
+        agent_action: >
+          Record context changes in STATE.md. Write SUMMARY entry
+          documenting what drifted and what was corrected.
+
+  - id: WF-04
+    name: bootstrap
+    project_types: [universal]
+    description: >
+      First session on a new project. Get from zero to working agent
+      collaboration as fast as possible.
+    steps:
+      - name: detect
+        stage: initialize
+        description: Identify project type and runtime
+        features: [TPL-02, TPL-03]
+        agent_action: >
+          Determine which entry point was loaded. Detect whether this
+          is greenfield or brownfield. Choose template tier.
+          Infer project type from directory contents.
+      - name: initialize
+        stage: scope
+        description: Set up project context
+        features: [TPL-01, CTX-01]
+        agent_action: >
+          Help user fill in PROJECT.md. Create initial .context/BASE.md.
+          For brownfield, scan the project to populate the map.
+      - name: map
+        stage: execute
+        description: Build the project understanding
+        features: [CTX-05]
+        agent_action: >
+          Walk project structure. Record paths, purposes, patterns.
+          Map dependencies. This is the foundation for all future sessions.
+      - name: pair
+        stage: execute
+        description: Set up context pairing
+        features: [CTX-04]
+        agent_action: >
+          Identify domain areas. Suggest specialist context files.
+          Add scoping rules for each domain to the entry point.
+      - name: ready
+        stage: close
+        description: Confirm setup and orient
+        features: [STT-03, TSK-04]
+        agent_action: >
+          Set STATE.md to initial position. Write first SUMMARY entry.
+          The project is now ready for real work.
+
+  - id: WF-05
+    name: data-exploration
+    project_types: [data]
+    description: >
+      When the user submits data and wants to explore it. The agent builds
+      structured understanding and provides interactive access. Context IS
+      the primary artifact — not a maintenance side effect.
+    steps:
+      - name: ingest
+        stage: scope
+        description: First contact with the data — scan structure, classify, measure
+        features: [QRY-01, EXP-01, CTX-05]
+        agent_action: >
+          Scan data sources for structure (columns, types, files, layout).
+          Sample content. Measure scale. Detect quality signals.
+          Present initial findings to user. Build draft BASE.md data inventory.
+      - name: map
+        stage: plan
+        description: Build the data model — schemas, relationships, taxonomies
+        features: [CTX-05, EXP-01, HAI-01]
+        agent_action: >
+          Build field inventories, identify keys and join paths, map
+          derived metrics, note quality issues. For documents: build index,
+          identify entities, map cross-references. Present to user for
+          correction and approval.
+      - name: reference
+        stage: execute
+        description: Build navigable reference artifacts
+        features: [EXP-02, CTX-04, EXP-04]
+        agent_action: >
+          Transform raw mapping into structured references: entity registries,
+          topic taxonomies, dimension indices, metric catalogs. Each entry
+          must be addressable, cross-linked, and source-attributed.
+      - name: explore
+        stage: execute
+        description: Interactive querying — user asks, agent routes to data
+        features: [EXP-03, EXP-04, CTX-03]
+        agent_action: >
+          Classify user query against queryable dimensions. Load appropriate
+          specialist. Answer from references when possible, access raw data
+          only when needed. Propose new dimensions when queries reveal gaps.
+      - name: refine
+        stage: close
+        description: Evolve understanding based on exploration
+        features: [EXP-02, STT-01, TSK-04]
+        agent_action: >
+          Add new queryable dimensions discovered during exploration.
+          Update references. Record exploration insights in STATE.md.
+          Write SUMMARY entry bridging to next session.
+
+  - id: WF-06
+    name: analytical-system
+    project_types: [analytical]
+    description: >
+      When the user works on prompt composition, evaluation pipelines,
+      context analysis, or ML chain orchestration. The agent maps
+      analytical components, builds structured understanding, and
+      supports iterative refinement of analytical artifacts.
+    steps:
+      - name: discover
+        stage: scope
+        description: Identify analytical components, chains, and pipeline stages
+        features: [QRY-01, QRY-02, CTX-03]
+        agent_action: >
+          Load context for the analytical domain. Identify chains
+          (input → transformation → output). Map pipeline stages.
+          Understand what components exist and how they connect.
+      - name: map-chains
+        stage: plan
+        description: Build the chain model and propose specialist structure
+        features: [TSK-01, HAI-01, CTX-05]
+        agent_action: >
+          Document each chain with its stages, inputs, outputs, and
+          evaluation criteria. Propose specialist context files for
+          distinct knowledge domains. Present chain model for approval.
+      - name: build-context
+        stage: execute
+        description: Create structured context for analytical components
+        features: [CTX-04, CTX-05, STT-01]
+        agent_action: >
+          Build specialist files for each analytical domain (composition,
+          evaluation, execution, domain knowledge). Record architectural
+          decisions about chain structure in STATE.md.
+      - name: compose
+        stage: execute
+        description: Build or modify analytical artifacts (prompts, pipelines, evaluations)
+        features: [STT-01, QRY-03, HAI-03]
+        agent_action: >
+          Create or modify the analytical artifacts. Follow cascade rules
+          for pipeline changes (upstream change → downstream specs update).
+          Maintain dual-audience separation for documentation.
+      - name: evaluate
+        stage: verify
+        description: Check analytical artifacts against evaluation criteria
+        features: [TSK-02]
+        agent_action: >
+          Run evaluation criteria against completed work. For prompts:
+          check against scoring rubrics. For pipelines: verify stage
+          contracts. Report results with specific evidence.
+      - name: refine
+        stage: close
+        description: Record findings and bridge to next iteration
+        features: [TSK-03, TSK-04, STT-03]
+        agent_action: >
+          Write SUMMARY entry documenting what was built and evaluation
+          results. Update STATE.md with refinement direction. The "Next"
+          field should identify what to iterate on.
+
+  - id: WF-07
+    name: specification-project
+    project_types: [universal]
+    description: >
+      When the primary output is specifications, standards, or methodology
+      documents rather than code or data artifacts. The agent helps
+      structure, draft, review, and cross-reference specification content.
+    steps:
+      - name: research
+        stage: scope
+        description: Gather prior art, constraints, and requirements
+        features: [QRY-01, QRY-02, CTX-03]
+        agent_action: >
+          Load relevant context. Read existing specs, research docs,
+          and requirements. Identify what the spec needs to cover
+          and what prior decisions constrain it.
+      - name: outline
+        stage: plan
+        description: Propose spec structure with sections and cross-references
+        features: [TSK-01, HAI-01, STT-02]
+        agent_action: >
+          Draft a spec outline with sections, cross-references to
+          existing specs, and verification criteria. Surface any
+          open questions about scope or approach. Wait for approval.
+      - name: draft
+        stage: execute
+        description: Write spec content with traceability
+        features: [STT-01, QRY-03, CTX-05, HAI-03]
+        agent_action: >
+          Write each spec section. Cross-reference related specs.
+          Record design decisions in STATE.md immediately. Follow
+          cascade rules when spec changes affect other documents.
+      - name: cross-reference
+        stage: execute
+        description: Ensure consistency across related specifications
+        features: [QRY-03, CTX-05]
+        agent_action: >
+          Check that this spec is consistent with all related specs.
+          Update cross-references. Flag contradictions. Update
+          context files if the spec changes the project's understanding.
+      - name: review
+        stage: verify
+        description: Verify spec completeness and consistency
+        features: [TSK-02]
+        agent_action: >
+          Check spec against outline criteria. Verify all sections
+          are substantive. Confirm cross-references are valid.
+          Report coverage gaps.
+      - name: record
+        stage: close
+        description: Update management files and bridge to next spec
+        features: [TSK-03, TSK-04, STT-03]
+        agent_action: >
+          Write SUMMARY entry. Update STATE.md position. If this
+          spec enables other specs, note the dependency in "Next."
+
+  - id: WF-08
+    name: discovery
+    project_types: [universal]
+    description: >
+      When the methodology is applied to an existing project (brownfield) or
+      when a major re-assessment is needed. The agent systematically builds
+      understanding of the project before contributing to it. Discovery must
+      complete before the agent can work effectively.
+    steps:
+      - name: inventory
+        stage: scope
+        description: Walk the project structure and build a complete file/module inventory
+        features: [QRY-01, SCAN-01, CTX-05]
+        agent_action: >
+          Walk the entire project directory. Record every significant path,
+          its purpose, and its key patterns. Build the project map in
+          .context/BASE.md. This is the foundation — skip nothing.
+      - name: map
+        stage: plan
+        description: Map dependencies, connections, and data flows between components
+        features: [SCAN-02, HAI-01]
+        agent_action: >
+          Parse package manifests, trace imports, map service connections.
+          Present the dependency map to the human for validation. Flag
+          any surprising connections or circular dependencies.
+      - name: extract
+        stage: execute
+        description: Identify patterns, conventions, and implicit architectural decisions
+        features: [SCAN-03, STT-01, CTX-04]
+        agent_action: >
+          Sample key files. Identify naming conventions, error handling
+          patterns, test approaches, design patterns. Record discovered
+          architectural decisions in STATE.md. Propose specialist context
+          files for distinct domains.
+      - name: assess
+        stage: verify
+        description: Evaluate technical debt, risks, and improvement opportunities
+        features: [SCAN-04, STT-02]
+        agent_action: >
+          Based on inventory and patterns, identify areas of concern:
+          outdated deps, missing tests, inconsistencies, security issues.
+          Write findings as open questions in STATE.md with severity.
+          Present assessment to human — they decide priorities.
+      - name: bootstrap
+        stage: close
+        description: Finalize context files, update entry point, record discovery session
+        features: [CTX-01, TSK-03, TSK-04, STT-03]
+        agent_action: >
+          Finalize .context/BASE.md with complete project map. Write
+          specialist context files approved during extract step. Update
+          entry point scoping table with project-specific query types.
+          Write SUMMARY entry. Update STATE.md position. Set lifecycle
+          stage to Development (or Design if architecture needs work).
+
+# ============================================================
+# LAYER 3: AGENT BEHAVIORAL PROTOCOL
+# ============================================================
+
+protocol:
+  purpose: >
+    The agent's job is not just to complete tasks. It is to build and
+    maintain a project intelligence layer that makes every future session
+    more effective than the last. When you change something, you also update
+    the project's understanding of itself. When you make a decision, you
+    record it. When you encounter something new, you build context.
+
+  core_directives:
+    - id: P-01
+      name: Build understanding, not just output
+      project_types: [universal]
+      directive: >
+        Every change is also a context change. When you add a module,
+        update the project map. When you make an architecture decision,
+        record it. When you discover a new domain, propose a specialist.
+        The agent is always building the project's self-knowledge.
+
+    - id: P-02
+      name: Maintain for your future self
+      project_types: [universal]
+      directive: >
+        Every session starts cold. Write decisions, open questions,
+        and context updates as if leaving notes for a colleague who
+        will continue your work but has no memory of this session.
+
+    - id: P-03
+      name: Cascade is not optional
+      project_types: [universal]
+      directive: >
+        File changes ripple through dependencies. Check the cascade table
+        after every change. Do it in the same response. Deferred cascades
+        are skipped cascades.
+
+    - id: P-04
+      name: Scope to avoid drowning
+      project_types: [universal]
+      directive: >
+        Context windows are finite. Follow the scoping table. Load BASE.md
+        + one specialist. If you need more, split the query.
+
+    - id: P-05
+      name: Surface uncertainty, don't hide it
+      project_types: [universal]
+      directive: >
+        Silent assumptions are the primary failure mode. When unsure,
+        write an open question. When ambiguous, ask.
+
+    - id: P-06
+      name: The human controls direction
+      project_types: [universal]
+      directive: >
+        The agent proposes; the human decides. The plan checkpoint exists
+        because the human's judgment about WHAT to build is more reliable
+        than the agent's.
+
+    - id: P-07
+      name: Keep files loadable
+      project_types: [universal]
+      directive: >
+        Context that doesn't fit in the window can't help. Intelligence
+        layer files that grow beyond 300 lines consume disproportionate
+        tokens. When a file exceeds this threshold, restructure it into
+        an index (active content + navigation) and component files
+        (archived sections). The index stays small; components are loaded
+        only when their specific content is needed.
+
+    - id: P-08
+      name: Methodology is additive only
+      project_types: [universal]
+      directive: >
+        The methodology NEVER modifies project source code, tests, or
+        pre-existing documentation. It only creates and modifies its own
+        files (STATE.md, .context/, PLAN.md, SUMMARY.md, etc.). In
+        brownfield projects, existing files are NEVER deleted or
+        overwritten — methodology content is appended to existing entry
+        points and new files are created alongside existing ones.
+
+    - id: P-09
+      name: Surface capability limitations
+      project_types: [universal]
+      directive: >
+        Monitor your own methodology adherence during a session. If you
+        notice repeated cascade misses, forgotten STATE.md updates,
+        shallow context, or lost conventions, surface this to the user
+        rather than silently degrading. Record the observation as an
+        open question in STATE.md. Suggest switching to a more capable
+        model or a lighter integration profile. Two rules followed
+        consistently beat ten rules followed inconsistently.
+
+    - id: P-10
+      name: Document proportionally
+      project_types: [universal]
+      directive: >
+        Match documentation effort to task significance. Low-effort tasks
+        (status checks, lookups, clarifications) need no STATE.md or
+        SESSION-LOG updates beyond the cascade contract. Medium-effort tasks
+        get targeted recording (decisions yes, session log optional).
+        High-effort tasks get full recording including session metrics and
+        refinement tracking. The agent self-assesses materiality and documents
+        accordingly. Never record routine queries in STATE.md or SESSION-LOG.md.
+
+  workflow_selection: >
+    When a query arrives, the agent selects the appropriate guided workflow:
+    - First session / template just copied → WF-04 (bootstrap)
+    - Brownfield project, first application of methodology → WF-08 (discovery)
+    - Code modification request → WF-02 (code-change)
+    - Data submitted or data question → WF-05 (data-exploration)
+    - "Refresh context" or detected drift → WF-03 (context-refresh)
+    - General task request → WF-01 (standard-task)
+    - Analytical/prompt system task → WF-06 (analytical-system)
+    - Spec writing or methodology design → WF-07 (specification-project)
+    If no workflow matches, follow WF-01 as the default pattern.
+    Project type is inferred from the entry point's scoping table content.
+    Lifecycle stage (from PROJECT-PROFILE.md) further adjusts feature priorities —
+    see docs/architecture/project-lifecycle.md for the activation table.
+
+# ============================================================
+# LAYER 4: ROUTING RULES
+# Computable query classification and feature activation
+# ============================================================
+
+query_patterns:
+  # --- Universal patterns ---
+  - query_type: planning
+    match_rules:
+      keywords: [plan, roadmap, phase, requirements, scope, prioritize]
+      phrases: ["what should we", "next phase", "plan for"]
+    workflow: WF-01
+    project_types: [universal]
+
+  - query_type: context_refresh
+    match_rules:
+      keywords: [refresh, resync, update context, drift, stale]
+      phrases: ["refresh context", "update .context", "resync"]
+    workflow: WF-03
+    project_types: [universal]
+
+  - query_type: phase_completion
+    match_rules:
+      keywords: [complete, finish, close, done, gate]
+      phrases: ["phase complete", "mark done", "close session"]
+    workflow: WF-01
+    project_types: [universal]
+
+  - query_type: backlog
+    match_rules:
+      keywords: [backlog, idea, future, todo, later]
+      phrases: ["add to backlog", "future work"]
+    workflow: WF-01
+    project_types: [universal]
+
+  # --- Code project patterns ---
+  - query_type: code_change
+    match_rules:
+      keywords: [implement, code, build, fix, refactor, add feature, modify]
+      phrases: ["add a", "change the", "fix the", "refactor", "implement"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: bug_fix
+    match_rules:
+      keywords: [bug, error, broken, failing, debug]
+      phrases: ["fix the bug", "why is this", "not working"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: dependency_update
+    match_rules:
+      keywords: [dependency, package, upgrade, install, npm, pip]
+      phrases: ["update package", "add dependency"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: database_work
+    match_rules:
+      keywords: [database, schema, migration, model, table, query, sql]
+      phrases: ["add a table", "update schema", "run migration"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: api_work
+    match_rules:
+      keywords: [api, endpoint, route, controller, rest, graphql]
+      phrases: ["add endpoint", "api route", "rest endpoint"]
+    workflow: WF-02
+    project_types: [code]
+
+  - query_type: deployment_work
+    match_rules:
+      keywords: [deploy, infrastructure, pipeline, ci, cd, environment, staging, production, devops]
+      phrases: ["deploy to", "set up pipeline", "configure environment", "infrastructure change"]
+    workflow: WF-02
+    project_types: [code]
+
+  # --- Data exploration patterns ---
+  - query_type: data_ingest
+    match_rules:
+      keywords: [ingest, import, load, submit, upload, dataset, csv]
+      phrases: ["here is the data", "load this", "analyze this dataset"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: schema_query
+    match_rules:
+      keywords: [schema, columns, fields, types, structure, table]
+      phrases: ["what columns", "show schema", "field types"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: explore_entity
+    match_rules:
+      keywords: [explore, entity, about, details, info]
+      phrases: ["explore", "tell me about", "what do we know about"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: relationship_query
+    match_rules:
+      keywords: [relate, relationship, connect, join, link, between]
+      phrases: ["how does X relate to", "connection between"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: quality_check
+    match_rules:
+      keywords: [quality, null, missing, duplicate, integrity]
+      phrases: ["data quality", "check quality", "missing values"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: analytical_query
+    match_rules:
+      keywords: [trend, compare, analyze, distribution, aggregate, count]
+      phrases: ["show me trends", "compare", "how many"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: document_search
+    match_rules:
+      keywords: [document, search, find, topic, reference, policy]
+      phrases: ["search for", "find documents about", "what does the policy say"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: dimension_management
+    match_rules:
+      keywords: [dimension, add dimension, queryable, aspect]
+      phrases: ["add dimension", "new queryable aspect", "list dimensions"]
+    workflow: WF-05
+    project_types: [data]
+
+  - query_type: add_reference
+    match_rules:
+      keywords: [reference, add reference, build reference, catalog, registry entry]
+      phrases: ["add a reference", "build reference for", "new reference entry"]
+    workflow: WF-05
+    project_types: [data]
+
+  # --- Analytical system patterns ---
+  - query_type: chain_work
+    match_rules:
+      keywords: [chain, pipeline, prompt, composition, orchestration, stage]
+      phrases: ["build a chain", "compose prompts", "pipeline stage", "chain architecture"]
+    workflow: WF-06
+    project_types: [analytical]
+
+  - query_type: evaluation
+    match_rules:
+      keywords: [evaluate, score, rubric, criteria, benchmark, test prompt]
+      phrases: ["evaluate this", "scoring rubric", "how well does", "benchmark against"]
+    workflow: WF-06
+    project_types: [analytical]
+
+  - query_type: composition
+    match_rules:
+      keywords: [compose, template, prompt template, context window, token]
+      phrases: ["compose a prompt", "prompt template", "context strategy"]
+    workflow: WF-06
+    project_types: [analytical]
+
+  - query_type: domain_research
+    match_rules:
+      keywords: [research, domain, pattern, best practice, prior art]
+      phrases: ["research patterns", "domain knowledge", "what works for"]
+    workflow: WF-06
+    project_types: [analytical]
+
+  # --- Discovery / brownfield patterns ---
+  - query_type: project_discovery
+    match_rules:
+      keywords: [discover, inventory, map project, assess, scan codebase, understand, brownfield]
+      phrases: ["what does this project do", "scan the codebase", "map the project", "understand the architecture"]
+    workflow: WF-08
+    project_types: [universal]
+
+  - query_type: dependency_analysis
+    match_rules:
+      keywords: [dependencies, imports, connections, coupling, what uses, used by]
+      phrases: ["map dependencies", "what depends on", "trace imports", "dependency graph"]
+    workflow: WF-08
+    project_types: [universal]
+
+  - query_type: pattern_analysis
+    match_rules:
+      keywords: [patterns, conventions, architecture, how is this built, coding style]
+      phrases: ["what patterns", "coding conventions", "architectural decisions", "how does this work"]
+    workflow: WF-08
+    project_types: [universal]
+
+  - query_type: debt_assessment
+    match_rules:
+      keywords: [debt, technical debt, outdated, risks, security audit, code quality]
+      phrases: ["assess technical debt", "what needs fixing", "code quality", "security review"]
+    workflow: WF-08
+    project_types: [universal]
+
+  # --- Specification project patterns ---
+  - query_type: spec_writing
+    match_rules:
+      keywords: [spec, specification, standard, define, formalize, document]
+      phrases: ["write a spec", "define the standard", "formalize this", "specification for"]
+    workflow: WF-07
+    project_types: [universal]
+
+  - query_type: cross_reference
+    match_rules:
+      keywords: [cross-reference, consistency, align, reconcile, trace]
+      phrases: ["cross-reference with", "check consistency", "align specs"]
+    workflow: WF-07
+    project_types: [universal]
+
+routing:
+  algorithm: >
+    1. CLASSIFY: Match query against entry point scoping table first (project-specific).
+       If no match, check query_patterns (registry-level). Default: general_task → WF-01.
+    2. SELECT: Use workflow field from matched pattern. Check for bootstrap override
+       (first session → WF-04).
+    3. RESOLVE: Get workflow steps. For current stage, collect features from step + activation map.
+    4. COMPUTE: Aggregate reads/writes from scoping table row + resolved features.
+    5. EXECUTE: Agent loads read set, performs work, writes to write set.
+    6. CASCADE: For each written file, walk cascade table + registry dependencies (max 2 levels).
+
+  project_type_detection: >
+    Infer from entry point scoping table content and PROJECT-PROFILE.md:
+    - Has PROJECT-PROFILE.md → read project types and lifecycle stage directly
+    - Has "code change", "bug fix", "API work" rows → code project
+    - Has "schema query", "explore", "data ingest" rows → data project
+    - Has "chain work", "evaluation", "composition" rows → analytical project
+    - Has "spec writing", "cross-reference" rows → specification project (uses WF-07)
+    - Has "project discovery", "dependency analysis" rows → discovery active (uses WF-08)
+    - Has rows from multiple types → mixed project (multiple workflows available)
+    - Has neither → general project (WF-01 only)
+    Lifecycle stage (from PROJECT-PROFILE.md) adjusts feature activation priorities
+    but does not change project type detection.
+
+  priority_rules:
+    - Scoping table (project-specific) takes priority over registry patterns
+    - Entry point cascade table takes priority over registry dependencies
+    - One specialist per query (never load multiple)
+    - Write sets are constraints (agent should not write outside them)
+    - Max cascade depth is 2 levels
+    - Ambiguous classification → ask user (STT-02)
+
+# ============================================================
+# ACTIVATION AND DEPENDENCY MAPS
+# ============================================================
+
+activation:
+  initialize: [QRY-01, HAI-02, TPL-02]
+  scope: [QRY-02, CTX-03]
+  plan: [TSK-01, HAI-01, STT-02]
+  execute: [STT-01, QRY-03, CTX-04, CTX-05, CTX-06, HAI-03, HAI-05, EXP-02, EXP-03, EXP-04, SCAN-03]
+  verify: [TSK-02, SCAN-04]
+  close: [TSK-03, TSK-04, STT-03, HAI-04, HAI-06]
+  on_demand: [CTX-01, CTX-02, TPL-01, TPL-03, EXP-01, SCAN-01, SCAN-02, SCAN-05, SCAN-06, SCAN-07]
+
+dependencies:
+  TPL-01: [CTX-01, TPL-02]
+  CTX-01: [CTX-05]
+  QRY-01: [QRY-02]
+  QRY-02: [CTX-03]
+  TSK-01: [HAI-01]
+  HAI-02: [HAI-01]
+  TSK-03: [TSK-04, QRY-03]
+  STT-03: [TSK-03]
+  HAI-03: [HAI-04]
+  CTX-02: [CTX-05]
+  CTX-06: [QRY-03]
+  EXP-01: [CTX-05]
+  EXP-02: [EXP-01, CTX-05]
+  EXP-03: [QRY-02, CTX-03]
+  EXP-04: [EXP-03]
+  SCAN-01: [CTX-05]
+  SCAN-02: [SCAN-01]
+  SCAN-03: [SCAN-01]
+  SCAN-04: [SCAN-01, SCAN-03]
+  SCAN-05: [SCAN-01, SCAN-02]
+  SCAN-06: [SCAN-05]
+  SCAN-07: [SCAN-01]
+
+versions:
+  v1:
+    features: 22
+    workflows: 4
+    protocol_directives: 6
+    notes: Core methodology. File-driven, single-agent. Workflows compose features into task patterns.
+  v1.1:
+    features: 26
+    workflows: 5
+    protocol_directives: 6
+    query_patterns: 19
+    notes: >
+      Adds EXP domain (4 features), WF-05 (data-exploration), project-type annotations,
+      query patterns for automated routing, Layer 4 routing rules. CTX-05 generalized
+      to mapProject. Backwards-compatible with v1.
+  v1.2:
+    features: 27
+    workflows: 5
+    protocol_directives: 7
+    query_patterns: 19
+    notes: >
+      Adds CTX-06 manageScale (file size monitoring + index restructuring) and P-07
+      Keep files loadable (context window efficiency). Backwards-compatible with v1.1.
+  v1.3:
+    features: 27
+    workflows: 7
+    protocol_directives: 7
+    query_patterns: 25
+    notes: >
+      Adds WF-06 analytical-system, WF-07 specification-project. 6 new query patterns
+      for analytical and specification work. Backwards-compatible with v1.2.
+  v1.4:
+    features: 31
+    workflows: 8
+    protocol_directives: 7
+    query_patterns: 29
+    notes: >
+      Adds SCAN domain (4 features: SCAN-01 codebaseInventory, SCAN-02 dependencyMapping,
+      SCAN-03 patternExtraction, SCAN-04 debtAssessment). Adds WF-08 discovery workflow
+      for brownfield project entry. 4 new query patterns for discovery. Adds lifecycle
+      stage awareness to routing. PROJECT-PROFILE.md as new intelligence layer file.
+      Backwards-compatible with v1.3.
+  v1.5:
+    features: 32
+    workflows: 8
+    protocol_directives: 10
+    query_patterns: 29
+    notes: >
+      Adds HAI-05 modelCapabilityCheck (degradation detection + user surfacing).
+      Adds P-08 Methodology is additive only (safety invariant for brownfield).
+      Adds P-09 Surface capability limitations (self-monitoring directive).
+      Integration profiles (lite/standard/full) for controlling methodology surface area.
+      .context/METHODOLOGY.md as overflow target for lighter profiles.
+      Brownfield merge protocol (append-only, never delete). Model tier entry point setting.
+      Backwards-compatible with v1.4.
+  v1.6:
+    features: 36
+    workflows: 8
+    protocol_directives: 10
+    query_patterns: 29
+    notes: >
+      Adds HAI-06 writeObligations (close-stage enforcement via PROTOCOL.yaml close_check).
+      YAML-centric agent protocol: entry points become thin boot loaders (~50 lines),
+      all recurring rules move to .context/PROTOCOL.yaml (~120 lines YAML).
+      Adds SCAN-05 docDependencyGraph (document dependency graph in doc-tokens.yaml),
+      SCAN-06 docReviewGenerate (internal document registry generation),
+      and SCAN-07 boundariesConfig (configurable path resolution via PROTOCOL.yaml boundaries).
+      New CLI commands: deps, doc-review. New flags: --deps, --internal-registry.
+      .context/INDEX.yaml as navigation manifest with live metrics.
+      Template file counts: starter 20, full 34 (+PROTOCOL.yaml, +INDEX.yaml per tier).
+      Backwards-compatible with v1.5.
+  v2:
+    adds: [multi-agent orchestration, automated gate verification, template generator CLI]
+    notes: Extends v1.5. Backwards-compatible. New workflows for multi-agent patterns.