schema_version: '0.7'

intent: >
  NotarAI is a continuous intent reconciliation platform. It represents a shift
  in how software is built in the LLM era: from code-as-truth to
  spec-as-living-witness. Every software project contains three bodies of
  artifact — intent (specs), code, and docs — that inevitably drift apart. NotarAI
  treats this three-body drift problem as the central engineering challenge of the
  LLM era and provides the tooling to detect, propose, and approve reconciliation
  across all three. The spec is always the tiebreaker.

behaviors:
  - name: continuous_reconciliation
    given: 'any change to code, spec, or docs in a governed repository'
    then: 'the engine detects drift across all three artifact bodies and proposes targeted updates to bring them into alignment'

  - name: bidirectional_sync
    given: 'a human or LLM edits any artifact — spec, code, or doc'
    then: 'the engine determines which other artifacts are now out of sync and proposes specific, minimal updates to each'

  - name: propose_and_approve
    given: 'the engine detects drift or generates a reconciliation proposal'
    then: 'the proposal is surfaced to the human for review and approval; nothing is auto-applied'

  - name: coverage_model
    given: 'a file exists in the repository'
    then: 'it is classified as Tier 1 (fully specced), Tier 2 (registered), Tier 3 (excluded), or Tier 4 (derived); any file not in one of these tiers is flagged as an unspecced artifact lint warning'

  - name: spec_composition
    given: 'a system contains subsystems or cross-cutting concerns'
    then: 'specs are composed via $ref for subsystem hierarchy and applies for cross-cutting invariants, allowing each spec to govern its own scope without duplication'

constraints:
  - 'The human must approve all reconciliation proposals before any artifact is modified'
  - 'The spec is always the canonical tiebreaker when code and spec disagree'
  - 'Specs are version-controlled and diffable — every change is traceable'
  - 'Coverage policy defaults to warn; unspecced files are flagged, not blocked, unless policy is set to strict'
  - 'README.md should be concise and complementary to the docs site'
  - 'Install scripts should avoid the need for sudo/admin access if possible'

invariants:
  - 'The engine must never silently auto-modify code, specs, or docs without human approval'
  - 'A file matching an exclude glob must never trigger an unspecced file warning'
  - 'Spec composition must never create circular $ref chains'

subsystems:
  - $ref: './cli.spec.yaml'
  - $ref: './docs.spec.yaml'
  - $ref: './ci.spec.yaml'

applies:
  - $ref: './style.spec.yaml'

exclude:
  - 'img/**'
  - '.claude/**'
  - 'docs/book/**'
  - 'docs/mermaid-init.js'
  - 'docs/mermaid.min.js'
  - '.notarai/.cache/**'
  - '.notarai/reconciliation_state.json'

artifacts:
  docs:
    - path: 'README.md'
      role: 'Project-level overview covering the NotarAI platform, philosophy, and CLI usage'
    - path: 'CONTRIBUTING.md'
      role: 'Contributor guide stub -- redirects to the full guide on the docs site'
    - path: 'docs/src/background/motivation.md'
      role: 'Narrative motivation for the NotarAI approach and the three-body drift problem'
    - path: 'docs/src/background/design-diagrams.md'
      role: 'Design diagrams illustrating the problem, solution, and reconciliation lifecycle'
    - path: 'docs/src/background/comparison-to-sdd.md'
      role: 'Conceptual comparison between NotarAI and Spec-Driven Development (SDD) tools, positioning NotarAI as spec-anchored with active reconciliation'
    - path: 'docs/src/background/inspirations.md'
      role: 'Background page covering the tools and traditions that shaped NotarAI -- BDD, IaC, JSON Schema, Design by Contract, and ADRs'
  configs:
    - path: 'Cargo.toml'
      role: 'Rust package manifest -- dependencies, build metadata, and binary target'
    - path: 'biome.json'
      role: 'Biome formatting config -- applies to non-Rust source files (JSON, JS/TS, CSS); excludes Markdown (handled by prettier pending biomejs/biome#3718)'
    - path: 'scripts/install.sh'
      role: 'Shell install script -- detects OS/arch, downloads appropriate binary from GitHub Releases'
    - path: 'scripts/install.ps1'
      role: 'PowerShell install script for Windows'
    - path: 'CLAUDE.md'
      role: 'Claude Code context file -- project description and NotarAI imports for AI-assisted development'
    - path: '.claude/rules/*.md'
      role: 'Modular Claude rules -- style, testing, and schema version conventions split from CLAUDE.md'
    - path: '.pre-commit-config.yaml'
      role: 'pre-commit hook configuration -- runs code formatters and linters before each commit'

decisions:
  - date: '2026-02-20'
    choice: 'Propose-and-approve as the only reconciliation mode'
    rationale: 'Auto-sync erodes trust in the spec as source of truth; humans must remain in the loop for all artifact changes'
  - date: '2026-02-20'
    choice: 'Spec is the tiebreaker when code and spec disagree'
    rationale: 'Elevates intent above implementation drift; forces explicit decisions when code diverges from spec'
  - date: '2026-02-20'
    choice: 'Three-tier coverage model (full / registered / excluded)'
    rationale: 'Avoids the binary owned/unowned problem; registered tier lets utility files be visible without full behavioral specs; excluded tier prevents binary assets and generated files from polluting the coverage report'
  - date: '2026-02-20'
    choice: 'System spec owns all concept-level docs; subsystem specs own only their code and config'
    rationale: 'Avoids dual ownership of documentation; system spec is the natural home for cross-cutting narrative artifacts'
  - date: '2026-02-21'
    choice: 'Promote notebooks, configs, and source to the spec schema (v0.4)'
    rationale: "ML, research, and infra projects use notebooks and config files as first-class artifacts; external datasets (e.g. HuggingFace) need a source field since they can't be expressed as local glob patterns"
  - date: '2026-02-22'
    choice: 'docs-site and CI each get their own subspecs'
    rationale: 'docs-site.spec.yaml governs the Astro site infrastructure and user-facing guide content; ci.spec.yaml governs GitHub Actions workflows and Dependabot. System spec owns concept-level background docs and cross-cutting configs (package.json, scripts/) that touch multiple subsystems.'
  - date: '2026-02-23'
    choice: 'Migrate CLI from Node.js/TypeScript to Rust'
    rationale: 'Single static binary eliminates Node.js runtime dependency; enables cross-platform distribution via direct download; project has not been released yet so this is a clean replacement with no migration concerns'
  - date: '2026-02-24'
    choice: 'Hash cache + MCP server for proportional context usage in reconciliation'
    rationale: 'Full git diffs and unconditional artifact reads would flood the context window as repos grow. The hash cache skips unchanged files; the MCP server pre-filters diffs to only files a given spec governs. Together they make reconciliation context proportional to what actually changed.'
  - date: '2026-02-28'
    choice: 'Migrate from prettier (npm) to biome (cargo install biome) for non-Rust formatting'
    rationale: 'Eliminates the Node.js runtime dependency entirely; biome is written in Rust and installable via cargo, consistent with the project toolchain; YAML formatting dropped as biome does not support it'
  - date: '2026-03-04'
    choice: 'Prettier re-introduced for Markdown formatting alongside biome'
    rationale: >
      Biome does not yet support Markdown formatting (biomejs/biome#3718).
      Prettier handles .md files as a temporary measure; biome covers all other
      non-Rust formats. The 2026-02-28 biome migration decision is still in
      effect for everything except Markdown.

  - date: '2026-02-26'
    choice: 'Remove sync_policy from schema (v0.5)'
    rationale: >
      sync_policy had no implementation behind it -- the reconciliation
      engine always uses propose-and-approve. Removed to reduce schema
      surface and set honest expectations. Users who need custom workflow
      behavior should encode it in their LLM workflow conventions.

  - date: '2026-03-04'
    choice: 'Add Tier 4 (Derived) to the coverage model'
    rationale: >
      Generated outputs (build artifacts, compiled bundles) need staleness
      tracking without being authored directly. Tier 4 fills this gap without
      conflating derived files with Tier 3 (excluded). Use tier: derived on
      the spec or tier: 4 on individual artifact refs.

  - date: '2026-03-04'
    choice: 'Schema 0.6: all schema enhancements in a single bump'
    rationale: >
      Consolidates four design phases into one release. Adds output, content,
      states, design, audience, variants, pipeline, and feedback blocks. Extends
      tier to include derived (Tier 4). Extends behavior with interaction and
      state_transition. All additions are optional -- existing specs validate
      without modification.

  - date: '2026-03-05'
    choice: 'Schema 0.7: multi-artifact platform expansion'
    rationale: >
      Extends the schema with optional fields for non-software domains:
      compliance frameworks, content section connections/evidence/duration,
      print/responsive design, structured feedback triggers, pipeline
      conditionals, state transition guards/actions, and extended enums for
      output types, layout types, interaction triggers, and domains. All
      additions are backward-compatible -- v0.6 specs validate without changes.
