# Amber Knowledge Plan (compatible with external plan yaml formats)
# This file declares the high-value architecture documentation and knowledge
# cards that should exist for the repository.
#
# Amber can read this (or the .json variant); both forms carry the same
# canonical shape declared in schemas/knowledge-plan.schema.json. Readers also
# accept the external `knowledgecard` spelling for interoperability.

schemaVersion: "1.0.0"
version: 1

scope:
  include: []
  exclude:
    - "node_modules/**"
    - "apps/web/node_modules/**"
    - "coverage/**"
    - ".tmp/**"
    - ".archive/**"
    - "agent-tools/**"
    - ".amber-legacy-harness-backup-*/**"
    - ".amber/worktrees/**"
    - "test-fixtures/**"
    - "test-adoption/**"
    - "test-workflows/**"
    - "mcps/**"
    - ".tmp-*/**"

knowledgePlan:
  template: architecture
  notes:
    - text: "Amber Protocol is a repository-local governance layer for AI-assisted engineering, NOT a runtime framework or agent platform. It produces review artifacts, dry-run plans, and approval records as files inside the target repo."
    - text: "The CLI entry point is scripts/amber.js. All business logic lives in scripts/lib/. The scripts/lib/core/ directory is the core engine; files matching scripts/lib/*-commands.js are thin CLI wrappers that delegate to core functions."
    - text: "Seven governance control layers in priority order: Governance (highest) > Verification > Observability > Lifecycle > Context > Tooling > Execution (lowest/avoid). This priority weighting shapes the entire codebase."
    - text: "The delivery lifecycle is: audit -> init -> governance report -> next -> plan -> gate -> verify -> approve -> handoff bundle -> handoff validate. Each stage maps to a CLI command."
    - text: "Safety boundary: read-only/dry-run first. 'init' and 'wiki' never overwrite existing files. Amber does not auto-execute target-project commands, dispatch live agents, or run dynamic workflows."
    - text: "Skills in skills/*/SKILL.md are the single source of truth. Platform-specific files (.claude/, .agents/skills/, .gemini/commands/) are auto-generated via 'npm run gen:agents'. Never edit generated files; edit skills/ instead."
    - text: "Dependencies are intentionally minimal: ajv for JSON Schema validation, ajv-formats for format validation, nodemailer for notifications. No Express, no database, no ORM in the CLI package."
    - text: "src/ contains auxiliary utilities only (migration + security scanners), not the main CLI logic. Do not confuse src/ with scripts/lib/core/."
    - text: "apps/web/ is a standalone React 18 + Vite + tRPC + TanStack Router application with its own package.json (@amber-protocol/web). It is NOT part of the published amber-protocol npm package."
    - text: "Governed loop execution (ADR-0003) requires four gates: declarative policy check, explicit 'amber loop approve', isolated git worktree, and tamper-evident hash-chain ledger. Default 'loop run' is still dry-run."
    - text: "The project uses CommonJS ('type': 'commonjs' in package.json). Node >= 18.17 required."
    - text: "JSON Schemas in schemas/ define contracts for loop-contract, route, session-manifest, and timeline-event (plus knowledge-plan). All validated with ajv."
  documents:
    - title: "CLI Architecture & Command Dispatch"
      goal: "Document how scripts/amber.js dispatches commands through command-dispatcher.js to handler modules and the core engine in scripts/lib/core/."
      hints: "Cover the command-dispatcher pattern, how *-commands.js files wrap core logic, and the separation between CLI surface and business logic. Include Mermaid diagram for flow if helpful."
    - title: "Governance Model & Seven Layers"
      goal: "Map the seven governance control layers to concrete commands, data structures, and enforcement points."
      hints: "Governance > Verification > Observability > Lifecycle > Context > Tooling > Execution. Reference governance.js, governance-report.js, governance-readiness.js, and the standards/ JSON files."
    - title: "Session & Lifecycle Management"
      goal: "Document routes, sessions, checkpoints, worktrees, and the lifecycle state machine."
      hints: "Cover session-commands.js, session-state-machine.js, session-manifest.js, route-commands.js, route-loader.js, checkpoint-manager.js, worktree-manager.js, and lifecycle.js."
    - title: "Loop Engineering & Governed Execution"
      goal: "Document loop contracts, ledgers, dry-run mode, and the four-gate governed execution path."
      hints: "Cover loops.js, loop-execution.js, loop-ledger.js, loop-policy.js, governed-runner.js, execution-validator.js."
    - title: "Skills & Platform Generation"
      goal: "Explain the skill system: SKILL.md as source of truth, gen:agents generation, and platform integrations."
      hints: "Cover skills/*/SKILL.md, scripts/gen-agent-commands.js, and the .claude/, .agents/skills/, .gemini/commands/ output directories."
    - title: "Web Dashboard"
      goal: "Document the apps/web React dashboard architecture: tRPC API, TanStack Router routes, and session/timeline components."
      hints: "Separate package.json (@amber-protocol/web). Cover routes/, components/session/, components/timeline/, features/, lib/trpc.ts, and the Express server."
    - title: "Schema & Validation Layer"
      goal: "Document the JSON Schema contracts and runtime validation with ajv."
      hints: "Cover schemas/*.schema.json, validators.js, schema-version-checker.js, and how ajv is used across the codebase."
    - title: "Handoff & Continuity"
      goal: "Explain the handoff bundle, session handoff, and continuity surfaces that make work transferable."
      hints: "Cover handoff-bundle.js, handoff-command.js, continuity-surfaces.js, session-handoff.md template, and the handoff validate flow."
    - title: "Security & Migration Utilities"
      goal: "Document the auxiliary security scanners and state migration tools in src/."
      hints: "Cover src/security/ (audit-report, dependency-scan, permission-review, secret-scan) and src/migration/ (dry-run, rollback, schema-validator)."

# issues/357: this block was `knowledgecard.notes`, a shape the schema rejects
# (knowledgeCards must be an array of cards) and schemaVersion was absent. Nobody
# hit it because --yaml was a no-op until now, so this template was never loaded.
knowledgeCards:
  - id: "core-engine"
    text: "scripts/lib/core/ is the core engine — treat as one knowledge module. It contains audit, doctor, governance, planning, lifecycle, loops, handoff, scaffold, maintenance, and workflow-pack logic."
    tags:
      - "architecture"
      - "core"
  - id: "cli-wrappers"
    text: "scripts/lib/*-commands.js files are thin CLI command handlers. They parse arguments and delegate to scripts/lib/core/ functions. Map each to its core counterpart."
    tags:
      - "cli"
      - "architecture"
  - id: "aux-modules"
    text: "src/migration/ and src/security/ are auxiliary utility modules separate from the CLI core. Migration handles state schema upgrades; security provides read-only scanners (dependency, permission, secret)."
    tags:
      - "migration"
      - "security"
  - id: "skills-source-of-truth"
    text: "skills/ contains the platform-agnostic journey skill definitions: amber (intent router), amber-delivery, amber-diagnosis-adoption, amber-context-continuity, and amber-continuous-improvement. Platform-specific files in .claude/, .agents/skills/, .gemini/commands/ are generated, never hand-edited. Run `npm run gen:agents` after changing skills/."
    tags:
      - "skills"
      - "generation"
  - id: "web-app-separate"
    text: "apps/web/ is a standalone React+Vite+tRPC application with its own package.json. Its src/ uses TanStack Router for file-based routing and tRPC for type-safe API calls to an Express server."
    tags:
      - "web"
      - "viewer"
  - id: "templates-purpose"
    text: "templates/ contains starter file templates that 'amber init' and 'amber wiki' scaffold into target repos. Includes AGENTS.md, CLAUDE.md, wiki skeleton, feature_list.json, and governance templates."
    tags:
      - "scaffolding"
  - id: "schemas-contracts"
    text: "schemas/ defines four JSON Schema contracts: loop-contract, route, session-manifest, timeline-event. These are the authoritative validation contracts used across the CLI (plus knowledge-plan)."
    tags:
      - "validation"
      - "schema"
  - id: "command-dispatcher"
    text: "scripts/lib/command-dispatcher.js is the central command registry and router — all CLI commands flow through it."
    tags:
      - "cli"
      - "core"
