agent-method 1.5.12

package/templates/full/registry/features/catalog.yaml

@@ -0,0 +1,743 @@
+# ============================================================
+# 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).
+