From 62477aae6ae41961a216cb2aadfe1f33df1cae69 Mon Sep 17 00:00:00 2001 From: egallmann Date: Sun, 15 Mar 2026 11:35:10 -0400 Subject: [PATCH] Add runtime system and migration ADR coverage --- PROJECT.yaml | 1 + SYSTEM-OVERVIEW.md | 245 +- adrs/entities/registry.yaml | 433 ++++ adrs/index/architecture-index.yaml | 23 + adrs/index/capability-registry.yaml | 44 + adrs/index/component-registry.yaml | 326 +++ adrs/index/decision-registry.yaml | 296 +++ adrs/index/entity-registry.yaml | 2184 +++++++++++++++++ adrs/index/invariant-registry.yaml | 533 ++++ adrs/index/relationship-registry.yaml | 513 ++++ adrs/index/system-registry.yaml | 95 + adrs/index/unresolved-registry.yaml | 3 + ...onal-execution-for-project-level-sema.yaml | 65 +- ...L-0002-recon-self-validation-strategy.yaml | 52 +- ...DR-L-0003-cem-implementation-deferral.yaml | 71 +- ...oritative-mode-for-workspace-boundary.yaml | 7 +- ...005-self-configuring-domain-discovery.yaml | 7 +- ...onversational-query-interface-for-rss.yaml | 110 +- ...s-and-obligation-projection-semantics.yaml | 59 + adrs/manifest.yaml | 441 +++- adrs/migrations/canonical-id-remap.yaml | 28 + ...-PC-0001-mcp-server-and-tool-registry.yaml | 84 + ...0002-watchdog-and-update-coordination.yaml | 82 + ...t-freshness-and-reconciliation-gating.yaml | 77 + ...ation-projection-and-context-assembly.yaml | 79 + .../ADR-PC-0005-json-semantic-extraction.yaml | 76 + ...-PC-0006-frontend-semantic-extraction.yaml | 78 + ...07-cloudformation-semantic-extraction.yaml | 75 + ...chestration-and-assistant-integration.yaml | 113 + ...PS-0002-semantic-extraction-subsystem.yaml | 83 + ...mentation-for-developer-invoked-graph.yaml | 20 +- ...raction-for-compliance-controls-and-s.yaml | 49 +- ...gular-and-cssscss-semantic-extraction.yaml | 52 +- ...ste-runtime-mcp-server-implementation.yaml | 28 +- adrs/rendered/ADR-L-0001.md | 2 +- adrs/rendered/ADR-L-0002.md | 6 +- adrs/rendered/ADR-L-0003.md | 6 +- adrs/rendered/ADR-L-0004.md | 6 +- adrs/rendered/ADR-L-0005.md | 6 +- adrs/rendered/ADR-L-0006.md | 6 +- adrs/rendered/ADR-L-0007.md | 63 + adrs/rendered/ADR-P-0001.md | 2 +- adrs/rendered/ADR-P-0002.md | 8 +- adrs/rendered/ADR-P-0003.md | 8 +- adrs/rendered/ADR-P-0004.md | 8 +- adrs/rendered/ADR-P-0005.md | 2 +- adrs/rendered/ADR-PC-0001.md | 77 + adrs/rendered/ADR-PC-0002.md | 81 + adrs/rendered/ADR-PC-0003.md | 72 + adrs/rendered/ADR-PC-0004.md | 73 + adrs/rendered/ADR-PC-0005.md | 71 + adrs/rendered/ADR-PC-0006.md | 70 + adrs/rendered/ADR-PC-0007.md | 71 + adrs/rendered/ADR-PS-0001.md | 86 + adrs/rendered/ADR-PS-0002.md | 63 + 55 files changed, 6750 insertions(+), 469 deletions(-) create mode 100644 adrs/entities/registry.yaml create mode 100644 adrs/index/architecture-index.yaml create mode 100644 adrs/index/capability-registry.yaml create mode 100644 adrs/index/component-registry.yaml create mode 100644 adrs/index/decision-registry.yaml create mode 100644 adrs/index/entity-registry.yaml create mode 100644 adrs/index/invariant-registry.yaml create mode 100644 adrs/index/relationship-registry.yaml create mode 100644 adrs/index/system-registry.yaml create mode 100644 adrs/index/unresolved-registry.yaml create mode 100644 adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml create mode 100644 adrs/migrations/canonical-id-remap.yaml create mode 100644 adrs/physical-component/ADR-PC-0001-mcp-server-and-tool-registry.yaml create mode 100644 adrs/physical-component/ADR-PC-0002-watchdog-and-update-coordination.yaml create mode 100644 adrs/physical-component/ADR-PC-0003-preflight-freshness-and-reconciliation-gating.yaml create mode 100644 adrs/physical-component/ADR-PC-0004-obligation-projection-and-context-assembly.yaml create mode 100644 adrs/physical-component/ADR-PC-0005-json-semantic-extraction.yaml create mode 100644 adrs/physical-component/ADR-PC-0006-frontend-semantic-extraction.yaml create mode 100644 adrs/physical-component/ADR-PC-0007-cloudformation-semantic-extraction.yaml create mode 100644 adrs/physical-system/ADR-PS-0001-runtime-orchestration-and-assistant-integration.yaml create mode 100644 adrs/physical-system/ADR-PS-0002-semantic-extraction-subsystem.yaml create mode 100644 adrs/rendered/ADR-L-0007.md create mode 100644 adrs/rendered/ADR-PC-0001.md create mode 100644 adrs/rendered/ADR-PC-0002.md create mode 100644 adrs/rendered/ADR-PC-0003.md create mode 100644 adrs/rendered/ADR-PC-0004.md create mode 100644 adrs/rendered/ADR-PC-0005.md create mode 100644 adrs/rendered/ADR-PC-0006.md create mode 100644 adrs/rendered/ADR-PC-0007.md create mode 100644 adrs/rendered/ADR-PS-0001.md create mode 100644 adrs/rendered/ADR-PS-0002.md diff --git a/PROJECT.yaml b/PROJECT.yaml index f621023..fb57d62 100644 --- a/PROJECT.yaml +++ b/PROJECT.yaml @@ -57,3 +57,4 @@ compliance: architecture_documentation: adr_directory: "adrs/" manifest_path: "adrs/manifest.yaml" + architecture_namespace: "ste-runtime" diff --git a/SYSTEM-OVERVIEW.md b/SYSTEM-OVERVIEW.md index 55c9083..18a27f4 100644 --- a/SYSTEM-OVERVIEW.md +++ b/SYSTEM-OVERVIEW.md @@ -3,30 +3,29 @@ integrity_schema_version: 1 generated: deterministic_projection_v1 artifact_kind: system_overview generator_id: adr-system-overview -generator_version: 2 +generator_version: 1 hash_algorithm: sha256 -source_hash: 589cfd7a74282b51417bb952aa8abe878d0500ec92be8ef68da640629c24a150 -rendered_hash: 852da4668b54412bb114e9ee4505b6ed08606be8c526ceb730ab366d276b6182 +source_hash: d041d0cb304542a0054d79b70ef31d18baf3b271fa6ce5f4f0a80dfb3adfefb3 +rendered_hash: 8219d815cf039e905c9b850284ad80d4d338d0afafed315100aadec406c114d3 --> ---- + # SYSTEM-OVERVIEW @@ -43,36 +42,31 @@ Read this file before writing code, generating artifacts, or hand-crafting repos ## System Purpose -`ste-runtime` is a tool with architecture described through ADR Kit artifacts. - -STE Runtime experimental component implementing RECON, RSS, MCP integration, and self-documenting semantic extraction workflows. - -It currently declares 11 ADRs, 13 invariants, and 2 tracked gaps. +`adr-architecture-kit` is the documentation-state toolkit for STE architecture work. It provides: - JSON Schema contracts for ADR artifacts - Pydantic models for typed parsing -- ADR records under `adrs/` -- generated manifest and rendered documentation -- repository-specific implementation and validation workflows +- parsers and business-rule validators +- manifest and registry generators +- YAML authoring support for Physical-System ADRs +- CLI workflows for scope-aware governance operations -Primary package manager: `npm`. +It does not define STE doctrine. That authority remains in `ste-spec`. ## Authority Hierarchy Use this order when resolving ambiguity: -1. [`PROJECT.yaml`](PROJECT.yaml) - Project-local metadata: ownership, automation posture, repository intent, and ADR locations. -2. [`adrs/`](adrs/) +1. `ste-spec` + Normative doctrine. This repo must not override it. +2. [`PROJECT.yaml`](PROJECT.yaml) + Project-local quality gates, metadata, and operating policy. +3. [`adrs/`](adrs/) Architectural authority for this repository. -3. [`adrs/manifest.yaml`](adrs/manifest.yaml) - Generated ADR index used for fast discovery and summary-level reasoning. -4. [`package.json`](package.json) - Runtime, scripts, package metadata, and Node-based workflow authority. -5. [`src/`](src/), [`scripts/`](scripts/), [`python-scripts/`](python-scripts/) - Primary implementation surface. +4. [`src/adr_kit/`](src/adr_kit/) + Current implementation of the above. If code and ADRs disagree, treat the ADRs and project policy as authoritative unless the task is explicitly to correct the ADRs. @@ -82,12 +76,12 @@ When an AI enters this repo cold, use this order: 1. Read [`PROJECT.yaml`](PROJECT.yaml). 2. Read this file. -3. Inspect [`adrs/`](adrs/) and [`adrs/manifest.yaml`](adrs/manifest.yaml). -4. Inspect [`adrs/rendered/`](adrs/rendered/) for generated human-readable ADR views. -5. Inspect [`package.json`](package.json) for scripts, runtime boundaries, and entrypoints. -6. Inspect the primary implementation surface: [`src/`](src/), [`scripts/`](scripts/), [`python-scripts/`](python-scripts/). -7. Inspect [`.github/workflows/test.yml`](.github/workflows/test.yml) for enforced CI checks. -8. Only then decide whether new code or documentation is needed. +3. Inspect [`pyproject.toml`](pyproject.toml). +4. Inspect the CLI entrypoints in [`main.py`](src/adr_kit/cli/main.py). +5. Inspect generators in [`src/adr_kit/generators/`](src/adr_kit/generators/). +6. Inspect validators in [`src/adr_kit/validators/`](src/adr_kit/validators/). +7. Inspect placement and scope rules in [`PLACEMENT-CONVENTION.md`](docs/PLACEMENT-CONVENTION.md). +8. Only then decide whether new code is needed. Do not start by hand-writing artifacts if a generator or validator already exists. @@ -95,33 +89,43 @@ Do not start by hand-writing artifacts if a generator or validator already exist Core implementation areas: -- ADR authority: [`adrs/`](adrs/) -- Generated ADR index: [`adrs/manifest.yaml`](adrs/manifest.yaml) -- Rendered ADR markdown: [`adrs/rendered/`](adrs/rendered/) -- Implementation surface: [`src/`](src/), [`scripts/`](scripts/), [`python-scripts/`](python-scripts/) -- ADR inventory: 11 ADRs, 13 invariants, 2 total gaps. +- Parser: [`yaml_parser.py`](src/adr_kit/parser/yaml_parser.py) +- Business validation: [`adr_validator.py`](src/adr_kit/validators/adr_validator.py) +- Scope resolution: [`resolver.py`](src/adr_kit/scope/resolver.py) +- Manifest generation: [`manifest_generator.py`](src/adr_kit/generators/manifest_generator.py) +- Legacy entity registry compatibility: [`entity_registry_generator.py`](src/adr_kit/generators/entity_registry_generator.py) +- Architecture index generation: [`architecture_index_generator.py`](src/adr_kit/generators/architecture_index_generator.py) +- Physical-System ADR generation: [`physical_system_generator.py`](src/adr_kit/generators/physical_system_generator.py) +- Runtime hygiene: [`runtime_hygiene.py`](src/adr_kit/validators/runtime_hygiene.py) Primary CLI capabilities: -- `adr generate-rendered-docs --scope C:\Users\Erik\Documents\Projects\ste-runtime` -- `adr generate-system-overview --scope C:\Users\Erik\Documents\Projects\ste-runtime` -- `adr validate-generated-docs --scope C:\Users\Erik\Documents\Projects\ste-runtime` -- `adr validate-system-overview --scope C:\Users\Erik\Documents\Projects\ste-runtime` -- `npm run build` -- `npm run lint` -- `npm run test` -- `npm run recon:self` +- `adr compile --mode {normal,strict,lenient}` +- `adr generate-manifest` +- `adr generate-architecture-index` +- `adr normalize-canonical-ids` +- `adr generate-rendered-docs` +- `adr validate` +- `adr validate-generated-docs` +- `adr scope` +- `adr generate-physical-system` +- `adr audit-runtime` +- `adr generate-system-overview` +- `adr validate-system-overview` ## Artifact Model Repository artifact classes: - ADRs: [`adrs/logical/`](adrs/logical/) and [`adrs/physical/`](adrs/physical/) +- Invariants: [`adrs/invariants/`](adrs/invariants/) +- Architecture discovery bundle: [`adrs/index/`](adrs/index/) - Derived manifest: [`adrs/manifest.yaml`](adrs/manifest.yaml) +- Legacy compatibility registry: [`adrs/entities/registry.yaml`](adrs/entities/registry.yaml) - Rendered ADR markdown: [`adrs/rendered/`](adrs/rendered/) -- AI-first overview: [`SYSTEM-OVERVIEW.md`](SYSTEM-OVERVIEW.md) +- JSON schemas: [`schema/v1.0/`](schema/v1.0/) and [`schema/v1.1/`](schema/v1.1/) - Project metadata: [`PROJECT.yaml`](PROJECT.yaml) -- Node package metadata: [`package.json`](package.json) +- AI-first overview: [`SYSTEM-OVERVIEW.md`](SYSTEM-OVERVIEW.md) Subtype authority comes from document content, not folders: @@ -134,45 +138,65 @@ Do not infer physical subtype from directory names when frontmatter already tell Use this type model when reasoning about repository architecture artifacts: -- `ADR-L-XXXX`: Conceptual logical design: capabilities, boundaries, contracts, constraints, and invariants. +- `ADR-L-XXXX`: Conceptual logical design: capabilities, boundaries, contracts, constraints, invariants, and non-functional requirements. - `ADR-V-XXXX`: Vision-oriented logical ADRs that describe future-state capabilities and target evolution. -- `ADR-P-XXXX`: Broad physical implementation specifications. -- `ADR-PS-XXXX`: High-level system design with major component boxes, relationships, and topology. -- `ADR-PC-XXXX`: Implementation-ready physical component specifications. +- `ADR-P-XXXX`: Legacy broad physical implementation specifications. +- `ADR-PS-XXXX`: Physical-System ADRs: high-level system design with major component boxes, relationships, broad technology claims, and a coherent design for the abstraction layer they support. +- `ADR-PC-XXXX`: Physical-Component ADRs: executable architecture intended to be implementation-ready without further human clarification. ## Canonical Workflows -### Generate rendered ADR markdown +### Validate the repository -Run `adr generate-rendered-docs --scope C:\Users\Erik\Documents\Projects\ste-runtime`. Do not hand-edit files under `adrs/rendered/`. +Run `adr governance-checks` for the standard local governance bundle, or add `--recursive` to validate all detected scopes while keeping tests root-scoped. Use `adr validate` or `adr validate --recursive` when you only need ADR schema and business-rule validation. -### Regenerate this overview +### Compile through the unified driver + +Run `adr compile --mode normal|strict|lenient` for the unified compiler path. Add `--recursive` to compile each detected scope independently. `lenient` only tolerates the current post-emit drift and contract-validation error family. + +### Commit at meaningful boundaries -Run `adr generate-system-overview --scope C:\Users\Erik\Documents\Projects\ste-runtime`. Do not hand-edit `SYSTEM-OVERVIEW.md`. +After a coherent implementation slice is verified, commit it before continuing. Do not accumulate unrelated unverified changes. + +### Maintain workflow-facing README content + +Update `README.md` when contributor-facing workflows or orientation guidance change. `README.md` is manual, not generated, and is not covered by `adr validate-generated-docs`. + +### Generate or refresh the architecture index + +Run `adr generate-architecture-index`. Treat `adrs/index/` as the primary machine discovery surface. + +### Generate or refresh the manifest + +Run `adr generate-manifest` or `adr generate-manifest --recursive`. Do not hand-edit `manifest.yaml`. + +### Generate rendered ADR markdown + +Run `adr generate-rendered-docs`. Do not hand-edit files under `adrs/rendered/`. ### Validate generated documentation -Run `adr validate-generated-docs --scope C:\Users\Erik\Documents\Projects\ste-runtime` and `adr validate-system-overview --scope C:\Users\Erik\Documents\Projects\ste-runtime`. +Run `adr validate-generated-docs` after regenerating manifest or rendered ADR markdown artifacts. This does not validate `README.md` or `SYSTEM-OVERVIEW.md`. -### Build the project +### Validate compiled contract profiles -Run `npm run build`. +Run `adr validate-contract --contract-profile greenfield` for strict contract enforcement, or use the brownfield profile with explicit thresholds during migration. -### Lint the project +### Generate a Physical-System ADR -Run `npm run lint`. +Inspect the generator first, then use `adr generate-physical-system` when the input can be structured. -### Run automated tests +### Validate project metadata -Run `npm test`. +Run `adr validate-project-metadata` to verify `PROJECT.yaml` against schema and model rules. -### Refresh semantic self-documentation +### Audit runtime hygiene -Run `npm run recon:self` and review generated state noise before committing. +Run `adr audit-runtime --fail-on-outdated` or `python scripts/check_runtime_hygiene.py --fail-on-outdated`. -### Respect project quality gates +### Regenerate this overview -Current declared gates: type_checking, test_suite_passing, linting, dependency_security_audit. +Run `adr generate-system-overview` and then `adr validate-system-overview`. Do not hand-edit `SYSTEM-OVERVIEW.md`. ## Tooling Priority Rules @@ -180,34 +204,29 @@ These are operational rules for AI contributors: 1. If a generator exists for the target artifact, use or extend it before hand-crafting output. 2. If a validator exists for the target artifact, run it before declaring work complete. -3. Treat ADR source and project metadata as authoritative over stale narrative docs. -4. Generated artifacts should be regenerated, not edited in place. +3. If a CLI command exposes the workflow, prefer it over ad hoc scripts. +4. If scope resolution exists, use it instead of assuming the current working directory is the only project root. +5. If frontmatter identifies artifact type, trust frontmatter over folder naming. +6. AI-first artifacts such as this overview must be generated from code or structured templates, not maintained manually. ## Path and Scope Rules These rules are mandatory: -1. Resolve repository work from the explicit project scope root, not an arbitrary parent workspace folder. -2. Treat sibling repositories as separate scopes unless a workflow explicitly says otherwise. -3. Place architectural authority under `adrs/` and keep generated views under `adrs/rendered/`. -4. Do not infer authority from folder names alone when structured metadata already exists. +1. Derive artifact paths from explicit scope roots. +2. Keep generated and temporary test artifacts inside scope-owned ignored paths such as `tests/.tmp/`. +3. Treat submodules and sibling repositories as separate scopes unless recursive scope resolution is explicitly requested. +4. Never classify artifacts by path shape when authoritative document metadata already exists. -Use ADR metadata and project metadata as placement authority before relying on directory folklore. +See [`PLACEMENT-CONVENTION.md`](docs/PLACEMENT-CONVENTION.md) for the full placement rule. ## High-Value Invariants Start here when you need the non-negotiables: -- [`INV-0001`](adrs/manifest.yaml) - Single repository only: RECON discovers files within the current repository. Cross-repository reconciliation is out of scope. -- [`INV-0002`](adrs/manifest.yaml) - Incremental reconciliation: Only files that have changed since the last run are re-extracted (when timestamp detection is available). -- [`INV-0003`](adrs/manifest.yaml) - Configurable source directories: Specified via `ste.config.json` or auto-detected. -- [`INV-0004`](adrs/manifest.yaml) - Shallow extraction: Extract structural elements (functions, classes, imports, exports) without deep semantic analysis. -- [`INV-0005`](adrs/manifest.yaml) - No deep semantic analysis: Do not attempt to understand function behavior, side effects, or complex type flows. -- [`INV-0006`](adrs/manifest.yaml) - Multi-language support: TypeScript, Python, CloudFormation, JSON (see E-ADR-005), Angular, CSS/SCSS (see E-ADR-006). -- [`INV-0007`](adrs/manifest.yaml) - Portable execution: RECON must work when dropped into any project. -- [`INV-0008`](adrs/manifest.yaml) - Provisional mapping: Normalization to AI-DOC schema is best-effort, not canonical. -- [`INV-0009`](adrs/manifest.yaml) - Schema evolution expected: The AI-DOC schema is still evolving; normalization will change. -- [`INV-0010`](adrs/manifest.yaml) - ID stability: Element IDs should be stable across runs for the same source element. +- [`INV-0001-schema-validation-required.yaml`](adrs/invariants/INV-0001-schema-validation-required.yaml) +- [`INV-0002-runtime-hygiene-and-dependency-security.yaml`](adrs/invariants/INV-0002-runtime-hygiene-and-dependency-security.yaml) +- [`INV-0003-meaningful-boundary-commits-required.yaml`](adrs/invariants/INV-0003-meaningful-boundary-commits-required.yaml) Practical meaning: @@ -221,23 +240,29 @@ Practical meaning: Use these heuristics before implementing: -- "Need the current architecture decision?": - Start in `adrs/` and use `adrs/rendered/` only as generated views. -- "Need a repo summary quickly?": - Read `adrs/manifest.yaml` before sampling individual ADR files. -- "Need the implementation surface?": - Inspect `src/`, `scripts/`, `python-scripts/` before searching the entire repo. -- "Need runtime entrypoints?": - Inspect the `bin` map in `package.json` before tracing CLI files manually. +- "Need to create or update an ADR artifact": + Check generators, then parser, then validator. +- "Need to validate repository architecture artifacts": + Check CLI and validator before writing checks. +- "Need to understand where physical ADRs belong": + Read placement convention and trust `adr_type`. +- "Need to add a new system-design workflow": + Prefer adding it to `src/adr_kit/generators/` and exposing it through the CLI. +- "Need to assess maintenance quality": + Run runtime hygiene audit before making claims about modernity or security. ## Common Failure Modes Avoid these: -- editing generated artifacts directly instead of regenerating them -- treating archived or local-only docs as current authority -- skipping manifest or ADR review and relying on stale README prose -- assuming the parent workspace folder is the project scope +- hand-authoring YAML when a model-driven generator exists +- using folder names as type authority +- computing relative paths without an explicit scope root +- writing tests against OS temp locations when repo-owned temp roots are the project rule +- leaving manifest output stale after artifact changes +- hand-editing rendered ADR markdown instead of regenerating it +- allowing deprecated APIs or dependency vulnerabilities to accumulate silently +- maintaining AI-first documentation manually when a generator should be authoritative ## Completion Criteria @@ -245,16 +270,18 @@ A change is not complete unless relevant checks were run. Minimum close-out expectation: -- regenerate derived ADR artifacts if ADR inputs changed -- validate `SYSTEM-OVERVIEW.md` if orientation-relevant workflows or authority changed -- run `npm run lint` when the change touches that concern -- run `npm run build` when the change touches that concern -- run `npm run test` when the change touches that concern -- run `npm run recon:self` when the change touches that concern -- satisfy declared quality gates: type_checking, test_suite_passing, linting, dependency_security_audit +- run targeted tests for the changed area +- run `adr governance-checks` for the standard local governance bundle when repository behavior changed, or add `--recursive` for workspace-level scope validation +- commit each meaningful verified implementation boundary before starting the next slice +- update `README.md` when workflow-facing behavior or orientation guidance changed +- run `adr validate` when artifact semantics changed but the full governance bundle is unnecessary +- regenerate derived artifacts if their sources changed +- run `adr validate-generated-docs` for committed generated documentation artifacts +- run runtime hygiene audit when changing dependency or runtime-facing code +- regenerate and validate `SYSTEM-OVERVIEW.md` when orientation-relevant workflows change ## One-Line Orientation If you only remember one thing: -ste-runtime is ADR-first, generated-doc-aware, and scope-bound. Start from structured authority, then move into implementation. \ No newline at end of file +This repository is generator-first, validator-first, scope-aware, and frontmatter-authoritative. \ No newline at end of file diff --git a/adrs/entities/registry.yaml b/adrs/entities/registry.yaml new file mode 100644 index 0000000..817ec91 --- /dev/null +++ b/adrs/entities/registry.yaml @@ -0,0 +1,433 @@ +# integrity_schema_version: 1 +# generated: deterministic_projection_v1 +# artifact_kind: legacy_entity_registry +# generator_id: adr-compiler +# generator_version: 1 +# hash_algorithm: sha256 +# source_hash: 0380cca483a764c23b6ef00e0471bf9f8c9e02a23567075372bca8784d0fb670 +# rendered_hash: 835aa38984ba9d78ac6d8ed07c0529c41448956de4ee1e6b914ca3e34e4016d2 + +schema_version: '1.1' +type: entity_registry +entities: +- entity_id: CAP-0007 + entity_type: capability + name: Surface graph freshness and obligation projection semantics + introduced_by: ADR-L-0007 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: COMP-0001 + entity_type: component + name: MCP Server and Tool Registry + introduced_by: ADR-PC-0001 + lifecycle_stage: active + source_path: adrs/physical-component/ADR-PC-0001-mcp-server-and-tool-registry.yaml + source_artifact_type: physical_component_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: COMP-0002 + entity_type: component + name: Watchdog and Update Coordination + introduced_by: ADR-PC-0002 + lifecycle_stage: active + source_path: adrs/physical-component/ADR-PC-0002-watchdog-and-update-coordination.yaml + source_artifact_type: physical_component_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: COMP-0003 + entity_type: component + name: Preflight Freshness and Reconciliation Gate + introduced_by: ADR-PC-0003 + lifecycle_stage: active + source_path: adrs/physical-component/ADR-PC-0003-preflight-freshness-and-reconciliation-gating.yaml + source_artifact_type: physical_component_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: COMP-0004 + entity_type: component + name: Obligation Projection and Context Assembly + introduced_by: ADR-PC-0004 + lifecycle_stage: active + source_path: adrs/physical-component/ADR-PC-0004-obligation-projection-and-context-assembly.yaml + source_artifact_type: physical_component_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: COMP-0005 + entity_type: component + name: JSON Semantic Extractor + introduced_by: ADR-PC-0005 + lifecycle_stage: active + source_path: adrs/physical-component/ADR-PC-0005-json-semantic-extraction.yaml + source_artifact_type: physical_component_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: COMP-0006 + entity_type: component + name: Frontend Semantic Extractor + introduced_by: ADR-PC-0006 + lifecycle_stage: active + source_path: adrs/physical-component/ADR-PC-0006-frontend-semantic-extraction.yaml + source_artifact_type: physical_component_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: COMP-0007 + entity_type: component + name: CloudFormation Semantic Extractor + introduced_by: ADR-PC-0007 + lifecycle_stage: active + source_path: adrs/physical-component/ADR-PC-0007-cloudformation-semantic-extraction.yaml + source_artifact_type: physical_component_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: DEC-0001 + entity_type: decision + name: RECON executes provisionally, generating semantic pressure without assuming + correctness. + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: DEC-0002 + entity_type: decision + name: RECON self-validation is non-blocking, report-only, and exploratory. + introduced_by: ADR-L-0002 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: DEC-0003 + entity_type: decision + name: CEM implementation is intentionally deferred. + introduced_by: ADR-L-0003 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: DEC-0004 + entity_type: decision + name: 'ste-runtime is a single process that combines:' + introduced_by: ADR-L-0004 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: DEC-0005 + entity_type: decision + name: '' + introduced_by: ADR-L-0005 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: DEC-0006 + entity_type: decision + name: 'Implement a Conversational Query Interface (CQI) as a layer above RSS that:' + introduced_by: ADR-L-0006 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: DEC-0007 + entity_type: decision + name: Freshness and obligation projection are logical runtime semantics + introduced_by: ADR-L-0007 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0001 + entity_type: invariant + name: INV-0001 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0002 + entity_type: invariant + name: INV-0002 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0003 + entity_type: invariant + name: INV-0003 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0004 + entity_type: invariant + name: INV-0004 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0005 + entity_type: invariant + name: INV-0005 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0006 + entity_type: invariant + name: INV-0006 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0007 + entity_type: invariant + name: INV-0007 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0008 + entity_type: invariant + name: INV-0008 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0009 + entity_type: invariant + name: INV-0009 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0010 + entity_type: invariant + name: INV-0010 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0011 + entity_type: invariant + name: INV-0011 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0012 + entity_type: invariant + name: INV-0012 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] +- entity_id: INV-0013 + entity_type: invariant + name: INV-0013 + introduced_by: ADR-L-0001 + lifecycle_stage: active + source_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_artifact_type: logical_adr + domains: [] + related_adrs: [] + realized_by: [] + relationships: + depends_on: [] + implements: [] + consumes: [] + realizes: [] diff --git a/adrs/index/architecture-index.yaml b/adrs/index/architecture-index.yaml new file mode 100644 index 0000000..9a8fedc --- /dev/null +++ b/adrs/index/architecture-index.yaml @@ -0,0 +1,23 @@ +schema_version: '1.1' +type: architecture_index +architecture_namespace: ste-runtime +generated_at: '2026-03-15T15:25:48Z' +generator: adr-architecture-index +entity_registry_path: adrs/index/entity-registry.yaml +relationship_registry_path: adrs/index/relationship-registry.yaml +unresolved_registry_path: adrs/index/unresolved-registry.yaml +decision_registry_path: adrs/index/decision-registry.yaml +capability_registry_path: adrs/index/capability-registry.yaml +invariant_registry_path: adrs/index/invariant-registry.yaml +component_registry_path: adrs/index/component-registry.yaml +system_registry_path: adrs/index/system-registry.yaml +validation_summary: + hard_failures: 0 + warnings: 0 + unresolved_entries: 0 +source_coverage: + logical_adrs: 7 + physical_adrs: 5 + physical_system_adrs: 2 + physical_component_adrs: 7 + standalone_invariants: 0 diff --git a/adrs/index/capability-registry.yaml b/adrs/index/capability-registry.yaml new file mode 100644 index 0000000..0c1a20c --- /dev/null +++ b/adrs/index/capability-registry.yaml @@ -0,0 +1,44 @@ +schema_version: '1.1' +type: normalized_entity_registry +entities: +- id: CAP-0007 + entity_type: capability + name: Surface graph freshness and obligation projection semantics + summary: Provide canonical freshness, invalidation, and obligation semantics for + runtime consumers. + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0007#CAP-0007 + artifact_path: adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0007 + domains: + - rss + - obligations + - freshness + implemented_by_components: [] + enabled_by_decisions: [] + relationships: + declared_in: + - ADR-L-0007 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0007#CAP-0007 + extraction_phase: extract_capability + classification: explicit + generator: adr-architecture-index diff --git a/adrs/index/component-registry.yaml b/adrs/index/component-registry.yaml new file mode 100644 index 0000000..4794e19 --- /dev/null +++ b/adrs/index/component-registry.yaml @@ -0,0 +1,326 @@ +schema_version: '1.1' +type: normalized_entity_registry +entities: +- id: COMP-0001 + entity_type: component + name: MCP Server and Tool Registry + summary: '- Serve MCP stdio runtime for assistant integration - Register structural, + operational, context, optimized, and obligation tools - Route tool requests onto + runtime graph and context services' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0001#COMP-0001 + artifact_path: adrs/physical-component/ADR-PC-0001-mcp-server-and-tool-registry.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0001 + legacy_component_id: COMP-0001 + technologies: + - typescript + - node.js + - mcp + - zod + module_path: src/mcp/mcp-server.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0001 + relationships: + declared_in: + - ADR-PC-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0001 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0001#COMP-0001 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0002 + entity_type: component + name: Watchdog and Update Coordination + summary: '- Watch source and state changes - Detect coherent edit transactions - + Coordinate update batches and reconciliation triggers - Protect runtime behavior + from unsafe write loops' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0002#COMP-0002 + artifact_path: adrs/physical-component/ADR-PC-0002-watchdog-and-update-coordination.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0002 + legacy_component_id: COMP-0002 + technologies: + - typescript + - node.js + - chokidar + module_path: src/watch/watchdog.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0001 + relationships: + declared_in: + - ADR-PC-0002 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0001 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0002#COMP-0002 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0003 + entity_type: component + name: Preflight Freshness and Reconciliation Gate + summary: '- Resolve intent scope - Evaluate graph freshness - Determine whether + reconciliation is required - Surface freshness status for downstream tools' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0003#COMP-0003 + artifact_path: adrs/physical-component/ADR-PC-0003-preflight-freshness-and-reconciliation-gating.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0003 + legacy_component_id: COMP-0003 + technologies: + - typescript + - node.js + - zod + module_path: src/mcp/preflight.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0001 + relationships: + declared_in: + - ADR-PC-0003 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0001 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0003#COMP-0003 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0004 + entity_type: component + name: Obligation Projection and Context Assembly + summary: '- Project obligations from change intent and graph state - Surface invalidated + validations and advisories - Load source-backed implementation context - Format + runtime context for assistant consumption' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0004#COMP-0004 + artifact_path: adrs/physical-component/ADR-PC-0004-obligation-projection-and-context-assembly.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0004 + legacy_component_id: COMP-0004 + technologies: + - typescript + - node.js + - zod + module_path: src/mcp/obligation-projector.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0001 + relationships: + declared_in: + - ADR-PC-0004 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0001 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0004#COMP-0004 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0005 + entity_type: component + name: JSON Semantic Extractor + summary: '- Detect semantically relevant JSON files - Extract controls, schemas, + and configuration semantics - Provide RECON-ready assertions for normalization' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0005#COMP-0005 + artifact_path: adrs/physical-component/ADR-PC-0005-json-semantic-extraction.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0005 + legacy_component_id: COMP-0005 + technologies: + - typescript + - json + - node.js + module_path: src/extractors/json/json-extractor.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0002 + relationships: + declared_in: + - ADR-PC-0005 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0002 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0005#COMP-0005 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0006 + entity_type: component + name: Frontend Semantic Extractor + summary: '- Extract Angular component, service, route, and template semantics - + Extract CSS/SCSS tokens, styles, and related frontend semantics - Provide frontend + assertions for RECON normalization' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0006#COMP-0006 + artifact_path: adrs/physical-component/ADR-PC-0006-frontend-semantic-extraction.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0006 + legacy_component_id: COMP-0006 + technologies: + - typescript + - angular + - css + - scss + module_path: src/extractors/angular/angular-extractor.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0002 + relationships: + declared_in: + - ADR-PC-0006 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0002 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0006#COMP-0006 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0007 + entity_type: component + name: CloudFormation Semantic Extractor + summary: '- Extract template, parameter, resource, and output semantics - Derive + infrastructure relationships and API/data model evidence - Preserve template-level + implementation intent metadata' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0007#COMP-0007 + artifact_path: adrs/physical-component/ADR-PC-0007-cloudformation-semantic-extraction.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0007 + legacy_component_id: COMP-0007 + technologies: + - typescript + - cloudformation + - yaml + - json + module_path: src/recon/phases/extraction-cloudformation.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0002 + relationships: + declared_in: + - ADR-PC-0007 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0002 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0007#COMP-0007 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index diff --git a/adrs/index/decision-registry.yaml b/adrs/index/decision-registry.yaml new file mode 100644 index 0000000..8dd5acf --- /dev/null +++ b/adrs/index/decision-registry.yaml @@ -0,0 +1,296 @@ +schema_version: '1.1' +type: normalized_entity_registry +entities: +- id: DEC-0001 + entity_type: decision + name: RECON executes provisionally, generating semantic pressure without assuming + correctness. + summary: '### 1. Semantic Pressure Over Semantic Truth RECON exists to **observe + how semantic truth breaks under change**, not to declare what truth is. During + exploratory development, the extraction algorithms, normalization sche' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#DEC-0001 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#DEC-0001 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0002 + entity_type: decision + name: RECON self-validation is non-blocking, report-only, and exploratory. + summary: '### 1. Non-Blocking Preserves Learning If validation blocked execution + on every finding, RECON would become unusable during exploratory development. + Many validation findings are informational or represent known limitatio' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0002#DEC-0002 + artifact_path: adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0002 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0002 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0002#DEC-0002 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0003 + entity_type: decision + name: CEM implementation is intentionally deferred. + summary: '### 1. CEM Orchestrates Components That Must Exist First CEM''s stages + call into foundational components: - **Orientation** calls RSS for context assembly + - **Analysis** reads AI-DOC semantic state - **Deliberation** invo' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0003#DEC-0003 + artifact_path: adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0003 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0003 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0003#DEC-0003 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0004 + entity_type: decision + name: 'ste-runtime is a single process that combines:' + summary: '### The Watchdog IS the Conflict Resolution Process When a file moves: + 1. Watchdog detects the move (authoritative: it observed the file system event) + 2. Migration detection scores confidence (1.0 = certain same element)' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0004#DEC-0004 + artifact_path: adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0004 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0004 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0004#DEC-0004 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0005 + entity_type: decision + name: '' + summary: '' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0005#DEC-0005 + artifact_path: adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0005 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0005 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0005#DEC-0005 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0006 + entity_type: decision + name: 'Implement a Conversational Query Interface (CQI) as a layer above RSS that:' + summary: '### 1. Reduces Cognitive Load for Both Humans and AI Without CQI: ``` + Human: "What would be affected by changing the auth service?" → Human must know: + use blast-radius, specify key format, parse output → AI must know: co' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0006#DEC-0006 + artifact_path: adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0006 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0006 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0006#DEC-0006 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0007 + entity_type: decision + name: Freshness and obligation projection are logical runtime semantics + summary: The current runtime models freshness and obligation data in public schemas + and assistant-facing responses, so these semantics require canonical documentation + above the component layer. + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0007#DEC-0007 + artifact_path: adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0007 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0007 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0007#DEC-0007 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index diff --git a/adrs/index/entity-registry.yaml b/adrs/index/entity-registry.yaml new file mode 100644 index 0000000..5032fe6 --- /dev/null +++ b/adrs/index/entity-registry.yaml @@ -0,0 +1,2184 @@ +schema_version: '1.1' +type: normalized_entity_registry +entities: +- id: ADR-L-0001 + entity_type: adr + name: RECON Provisional Execution for Project-Level Semantic State + summary: 'The STE Architecture Specification defines RECON (Reconciliation Engine) + as the mechanism for extracting semantic state from source code and populating + AI-DOC. The question arose: How should RECON operate during the expl' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + status: accepted + domains: + - recon + - architecture + - governance + tags: + - recon + - provisional-execution + - semantic-state + - ste-compliance + relationships: + declared_in: [] + references: + - ADR-L-0002 + - ADR-L-0003 + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-L-0002 + entity_type: adr + name: RECON Self-Validation Strategy + summary: 'RECON generates AI-DOC state from source code extraction. The question + arose: How should RECON validate its own output to ensure consistency and quality? + Key tensions: 1. **Blocking vs. Non-Blocking:** Should validation ' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0002 + artifact_path: adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml + source_refs: [] + metadata: + status: accepted + domains: + - recon + - validation + - governance + tags: + - recon + - validation + - self-validation + - ste-compliance + relationships: + declared_in: [] + references: + - ADR-L-0001 + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0002 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-L-0003 + entity_type: adr + name: CEM Implementation Deferral + summary: 'The STE Architecture Specification (ste-spec) defines a 9-stage Cognitive + Execution Model (CEM): ``` Perception → Orientation → Analysis → Deliberation + → Planning → Execution → Observation → Reflection → Adaptation ``` C' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0003 + artifact_path: adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml + source_refs: [] + metadata: + status: accepted + domains: + - architecture + - governance + - cem + tags: + - cem + - deferral + - meta-decision + - build-order + relationships: + declared_in: [] + references: + - ADR-L-0001 + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0003 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-L-0004 + entity_type: adr + name: Watchdog Authoritative Mode for Workspace Boundary + summary: 'Per STE Architecture (Section 3.1), STE operates across two distinct governance + boundaries: 1. **Workspace Development Boundary** - Provisional state, soft + + hard enforcement, post-reasoning validation 2. **Runtime Execu' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0004 + artifact_path: adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml + source_refs: [] + metadata: + status: accepted + domains: + - watchdog + - governance + - workspace-boundary + tags: + - watchdog + - file-watching + - workspace-boundary + - ste-compliance + relationships: + declared_in: [] + references: + - ADR-L-0001 + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0004 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-L-0005 + entity_type: adr + name: Self-Configuring Domain Discovery + summary: '' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0005 + artifact_path: adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml + source_refs: [] + metadata: + status: proposed + domains: + - recon + - domain-discovery + - architecture + tags: + - domain-discovery + - self-configuring + - ai-doc + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0005 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-L-0006 + entity_type: adr + name: Conversational Query Interface for RSS + summary: 'E-ADR-004 established the RSS CLI and TypeScript API as the foundation + for graph traversal and context assembly. However, a gap exists between: 1. **Raw + RSS operations** (search, dependencies, blast-radius) - require kno' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0006 + artifact_path: adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml + source_refs: [] + metadata: + status: proposed + domains: + - rss + - interface + - architecture + tags: + - rss + - conversational + - query-interface + - natural-language + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0006 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-L-0007 + entity_type: adr + name: Graph Freshness and Obligation Projection Semantics + summary: ste-runtime now exposes graph freshness checks, invalidated validation + signals, change intent handling, and obligation projection behavior through RSS + and MCP tooling. These semantics are broader than implementation deta + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0007 + artifact_path: adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml + source_refs: [] + metadata: + status: proposed + domains: + - rss + - obligations + - freshness + tags: + - freshness + - obligations + - preflight + - validation + relationships: + declared_in: [] + references: + - ADR-L-0004 + - ADR-L-0006 + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0007 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-P-0001 + entity_type: adr + name: RSS CLI Implementation for Developer-Invoked Graph Traversal + summary: 'The STE Architecture Specification Section 4.6 defines RSS (Runtime State-Slicing) + as the component responsible for graph traversal and context assembly from AI-DOC + state. RSS provides six core operations: | Operation | ' + canonical_source: + source_type: physical_adr + source_ref: ADR-P-0001 + artifact_path: adrs/physical/ADR-P-0001-rss-cli-implementation-for-developer-invoked-graph.yaml + source_refs: [] + metadata: + status: accepted + domains: + - rss + - cli + - implementation + tags: + - rss + - cli + - graph-traversal + - developer-tools + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_adr + source_ref: ADR-P-0001 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-P-0002 + entity_type: adr + name: JSON Data Extraction for Compliance Controls and Schemas + summary: 'Many enterprise codebases contain JSON files with semantic value beyond + simple configuration: | Category | Examples | Semantic Value | |----------|----------|----------------| + | Controls/Rules Catalog | Security controls' + canonical_source: + source_type: physical_adr + source_ref: ADR-P-0002 + artifact_path: adrs/physical/ADR-P-0002-json-data-extraction-for-compliance-controls-and-s.yaml + source_refs: [] + metadata: + status: superseded + domains: + - extraction + - data + - implementation + tags: + - json + - extractor + - compliance + - schemas + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_adr + source_ref: ADR-P-0002 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-P-0003 + entity_type: adr + name: Angular and CSS/SCSS Semantic Extraction + summary: 'The TypeScript extractor currently processes Angular files as standard + TypeScript, capturing: - Functions and their signatures - Classes and their methods + - Import/export relationships - Module structure However, Angular' + canonical_source: + source_type: physical_adr + source_ref: ADR-P-0003 + artifact_path: adrs/physical/ADR-P-0003-angular-and-cssscss-semantic-extraction.yaml + source_refs: [] + metadata: + status: superseded + domains: + - extraction + - frontend + - implementation + tags: + - angular + - css + - scss + - extractor + - frontend + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_adr + source_ref: ADR-P-0003 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-P-0004 + entity_type: adr + name: ste-runtime MCP Server Implementation + summary: 'Per STE Architecture Section 3.1, the Workspace Development Boundary requires: + - **Provisional state** maintenance (pre-merge, feature branches) - **Soft + hard + enforcement** (LLM instruction-following + validation tools' + canonical_source: + source_type: physical_adr + source_ref: ADR-P-0004 + artifact_path: adrs/physical/ADR-P-0004-ste-runtime-mcp-server-implementation.yaml + source_refs: [] + metadata: + status: superseded + domains: + - mcp + - integration + - implementation + tags: + - mcp + - server + - cursor-integration + - file-watching + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_adr + source_ref: ADR-P-0004 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-P-0005 + entity_type: adr + name: Extractor Validation Requirements + summary: '' + canonical_source: + source_type: physical_adr + source_ref: ADR-P-0005 + artifact_path: adrs/physical/ADR-P-0005-extractor-validation-requirements.yaml + source_refs: [] + metadata: + status: accepted + domains: + - validation + - extraction + - implementation + tags: + - validation + - extractors + - quality-assurance + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_adr + source_ref: ADR-P-0005 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-PC-0001 + entity_type: adr + name: MCP Server and Tool Registry + summary: This component exposes assistant-facing runtime tools over MCP and binds + structural, operational, context, optimized, and obligation-oriented tool surfaces + into one discoverable server boundary. + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0001 + artifact_path: adrs/physical-component/ADR-PC-0001-mcp-server-and-tool-registry.yaml + source_refs: [] + metadata: + status: proposed + domains: + - mcp + - integration + - runtime + tags: [] + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0001 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-PC-0002 + entity_type: adr + name: Watchdog and Update Coordination + summary: This component monitors changes, detects transactions, coordinates update + batches, and safeguards write-triggered reconciliation behavior for the runtime + boundary. + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0002 + artifact_path: adrs/physical-component/ADR-PC-0002-watchdog-and-update-coordination.yaml + source_refs: [] + metadata: + status: proposed + domains: + - watch + - runtime + - reconciliation + tags: [] + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0002 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-PC-0003 + entity_type: adr + name: Preflight Freshness and Reconciliation Gating + summary: This component evaluates file freshness, intent scope, and reconciliation + requirements before runtime actions rely on semantic graph state. + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0003 + artifact_path: adrs/physical-component/ADR-PC-0003-preflight-freshness-and-reconciliation-gating.yaml + source_refs: [] + metadata: + status: proposed + domains: + - preflight + - freshness + - reconciliation + tags: [] + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0003 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-PC-0004 + entity_type: adr + name: Obligation Projection and Context Assembly + summary: This component projects invalidated validations and change-driven obligations, + assembles implementation context, and loads source-backed evidence for assistant-facing + reasoning. + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0004 + artifact_path: adrs/physical-component/ADR-PC-0004-obligation-projection-and-context-assembly.yaml + source_refs: [] + metadata: + status: proposed + domains: + - obligations + - context + - rss + tags: [] + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0004 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-PC-0005 + entity_type: adr + name: JSON Semantic Extraction + summary: JSON semantic extraction captures controls, schemas, and configuration + semantics from JSON sources and feeds them into RECON normalization. + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0005 + artifact_path: adrs/physical-component/ADR-PC-0005-json-semantic-extraction.yaml + source_refs: [] + metadata: + status: proposed + domains: + - extraction + - json + - recon + tags: [] + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0005 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-PC-0006 + entity_type: adr + name: Frontend Semantic Extraction + summary: Frontend semantic extraction captures Angular and CSS/SCSS-specific semantics + beyond generic TypeScript structure and feeds them into RECON normalization. + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0006 + artifact_path: adrs/physical-component/ADR-PC-0006-frontend-semantic-extraction.yaml + source_refs: [] + metadata: + status: proposed + domains: + - extraction + - frontend + - recon + tags: [] + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0006 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-PC-0007 + entity_type: adr + name: CloudFormation Semantic Extraction + summary: CloudFormation semantic extraction captures templates, resources, outputs, + parameters, infrastructure relationships, and template-level implementation intent + from CloudFormation sources. + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0007 + artifact_path: adrs/physical-component/ADR-PC-0007-cloudformation-semantic-extraction.yaml + source_refs: [] + metadata: + status: proposed + domains: + - extraction + - cloudformation + - recon + tags: [] + relationships: + declared_in: [] + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0007 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-PS-0001 + entity_type: adr + name: Runtime Orchestration and Assistant Integration + summary: ste-runtime now contains a runtime orchestration boundary that keeps semantic + state fresh, exposes assistant-facing MCP tools, performs reconciliation gating + and freshness checks, and assembles implementation context and + canonical_source: + source_type: physical_system_adr + source_ref: ADR-PS-0001 + artifact_path: adrs/physical-system/ADR-PS-0001-runtime-orchestration-and-assistant-integration.yaml + source_refs: [] + metadata: + status: proposed + domains: + - runtime + - mcp + - rss + - watch + tags: + - runtime + - mcp + - watchdog + - obligations + relationships: + declared_in: [] + references: [] + related_to: + - ADR-PC-0001 + - ADR-PC-0002 + - ADR-PC-0003 + - ADR-PC-0004 + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_system_adr + source_ref: ADR-PS-0001 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: ADR-PS-0002 + entity_type: adr + name: Semantic Extraction Subsystem + summary: ste-runtime extraction is now a subsystem containing multiple first-class + extractors and normalization flows rather than a pair of isolated physical slices. + This ADR groups the implemented extractor estate under a concre + canonical_source: + source_type: physical_system_adr + source_ref: ADR-PS-0002 + artifact_path: adrs/physical-system/ADR-PS-0002-semantic-extraction-subsystem.yaml + source_refs: [] + metadata: + status: proposed + domains: + - extraction + - recon + - normalization + tags: + - extraction + - recon + - semantic-state + relationships: + declared_in: [] + references: [] + related_to: + - ADR-PC-0005 + - ADR-PC-0006 + - ADR-PC-0007 + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_system_adr + source_ref: ADR-PS-0002 + extraction_phase: extract_adr + classification: explicit + generator: adr-architecture-index +- id: CAP-0007 + entity_type: capability + name: Surface graph freshness and obligation projection semantics + summary: Provide canonical freshness, invalidation, and obligation semantics for + runtime consumers. + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0007#CAP-0007 + artifact_path: adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0007 + domains: + - rss + - obligations + - freshness + implemented_by_components: [] + enabled_by_decisions: [] + relationships: + declared_in: + - ADR-L-0007 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0007#CAP-0007 + extraction_phase: extract_capability + classification: explicit + generator: adr-architecture-index +- id: COMP-0001 + entity_type: component + name: MCP Server and Tool Registry + summary: '- Serve MCP stdio runtime for assistant integration - Register structural, + operational, context, optimized, and obligation tools - Route tool requests onto + runtime graph and context services' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0001#COMP-0001 + artifact_path: adrs/physical-component/ADR-PC-0001-mcp-server-and-tool-registry.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0001 + legacy_component_id: COMP-0001 + technologies: + - typescript + - node.js + - mcp + - zod + module_path: src/mcp/mcp-server.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0001 + relationships: + declared_in: + - ADR-PC-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0001 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0001#COMP-0001 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0002 + entity_type: component + name: Watchdog and Update Coordination + summary: '- Watch source and state changes - Detect coherent edit transactions - + Coordinate update batches and reconciliation triggers - Protect runtime behavior + from unsafe write loops' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0002#COMP-0002 + artifact_path: adrs/physical-component/ADR-PC-0002-watchdog-and-update-coordination.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0002 + legacy_component_id: COMP-0002 + technologies: + - typescript + - node.js + - chokidar + module_path: src/watch/watchdog.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0001 + relationships: + declared_in: + - ADR-PC-0002 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0001 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0002#COMP-0002 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0003 + entity_type: component + name: Preflight Freshness and Reconciliation Gate + summary: '- Resolve intent scope - Evaluate graph freshness - Determine whether + reconciliation is required - Surface freshness status for downstream tools' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0003#COMP-0003 + artifact_path: adrs/physical-component/ADR-PC-0003-preflight-freshness-and-reconciliation-gating.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0003 + legacy_component_id: COMP-0003 + technologies: + - typescript + - node.js + - zod + module_path: src/mcp/preflight.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0001 + relationships: + declared_in: + - ADR-PC-0003 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0001 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0003#COMP-0003 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0004 + entity_type: component + name: Obligation Projection and Context Assembly + summary: '- Project obligations from change intent and graph state - Surface invalidated + validations and advisories - Load source-backed implementation context - Format + runtime context for assistant consumption' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0004#COMP-0004 + artifact_path: adrs/physical-component/ADR-PC-0004-obligation-projection-and-context-assembly.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0004 + legacy_component_id: COMP-0004 + technologies: + - typescript + - node.js + - zod + module_path: src/mcp/obligation-projector.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0001 + relationships: + declared_in: + - ADR-PC-0004 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0001 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0004#COMP-0004 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0005 + entity_type: component + name: JSON Semantic Extractor + summary: '- Detect semantically relevant JSON files - Extract controls, schemas, + and configuration semantics - Provide RECON-ready assertions for normalization' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0005#COMP-0005 + artifact_path: adrs/physical-component/ADR-PC-0005-json-semantic-extraction.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0005 + legacy_component_id: COMP-0005 + technologies: + - typescript + - json + - node.js + module_path: src/extractors/json/json-extractor.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0002 + relationships: + declared_in: + - ADR-PC-0005 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0002 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0005#COMP-0005 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0006 + entity_type: component + name: Frontend Semantic Extractor + summary: '- Extract Angular component, service, route, and template semantics - + Extract CSS/SCSS tokens, styles, and related frontend semantics - Provide frontend + assertions for RECON normalization' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0006#COMP-0006 + artifact_path: adrs/physical-component/ADR-PC-0006-frontend-semantic-extraction.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0006 + legacy_component_id: COMP-0006 + technologies: + - typescript + - angular + - css + - scss + module_path: src/extractors/angular/angular-extractor.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0002 + relationships: + declared_in: + - ADR-PC-0006 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0002 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0006#COMP-0006 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: COMP-0007 + entity_type: component + name: CloudFormation Semantic Extractor + summary: '- Extract template, parameter, resource, and output semantics - Derive + infrastructure relationships and API/data model evidence - Preserve template-level + implementation intent metadata' + canonical_source: + source_type: physical_component_adr + source_ref: ADR-PC-0007#COMP-0007 + artifact_path: adrs/physical-component/ADR-PC-0007-cloudformation-semantic-extraction.yaml + source_refs: [] + metadata: + adr_id: ADR-PC-0007 + legacy_component_id: COMP-0007 + technologies: + - typescript + - cloudformation + - yaml + - json + module_path: src/recon/phases/extraction-cloudformation.ts + implements_capabilities: [] + implements_system: + - ADR-PS-0002 + relationships: + declared_in: + - ADR-PC-0007 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: + - SYS-0002 + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_component_adr + source_ref: ADR-PC-0007#COMP-0007 + extraction_phase: extract_component + classification: explicit + generator: adr-architecture-index +- id: DEC-0001 + entity_type: decision + name: RECON executes provisionally, generating semantic pressure without assuming + correctness. + summary: '### 1. Semantic Pressure Over Semantic Truth RECON exists to **observe + how semantic truth breaks under change**, not to declare what truth is. During + exploratory development, the extraction algorithms, normalization sche' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#DEC-0001 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#DEC-0001 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0002 + entity_type: decision + name: RECON self-validation is non-blocking, report-only, and exploratory. + summary: '### 1. Non-Blocking Preserves Learning If validation blocked execution + on every finding, RECON would become unusable during exploratory development. + Many validation findings are informational or represent known limitatio' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0002#DEC-0002 + artifact_path: adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0002 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0002 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0002#DEC-0002 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0003 + entity_type: decision + name: CEM implementation is intentionally deferred. + summary: '### 1. CEM Orchestrates Components That Must Exist First CEM''s stages + call into foundational components: - **Orientation** calls RSS for context assembly + - **Analysis** reads AI-DOC semantic state - **Deliberation** invo' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0003#DEC-0003 + artifact_path: adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0003 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0003 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0003#DEC-0003 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0004 + entity_type: decision + name: 'ste-runtime is a single process that combines:' + summary: '### The Watchdog IS the Conflict Resolution Process When a file moves: + 1. Watchdog detects the move (authoritative: it observed the file system event) + 2. Migration detection scores confidence (1.0 = certain same element)' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0004#DEC-0004 + artifact_path: adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0004 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0004 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0004#DEC-0004 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0005 + entity_type: decision + name: '' + summary: '' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0005#DEC-0005 + artifact_path: adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0005 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0005 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0005#DEC-0005 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0006 + entity_type: decision + name: 'Implement a Conversational Query Interface (CQI) as a layer above RSS that:' + summary: '### 1. Reduces Cognitive Load for Both Humans and AI Without CQI: ``` + Human: "What would be affected by changing the auth service?" → Human must know: + use blast-radius, specify key format, parse output → AI must know: co' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0006#DEC-0006 + artifact_path: adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0006 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0006 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0006#DEC-0006 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: DEC-0007 + entity_type: decision + name: Freshness and obligation projection are logical runtime semantics + summary: The current runtime models freshness and obligation data in public schemas + and assistant-facing responses, so these semantics require canonical documentation + above the component layer. + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0007#DEC-0007 + artifact_path: adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0007 + related_invariants: [] + enforces_invariants: [] + enables_capabilities: [] + governs_components: [] + supersedes: [] + refines: [] + relationships: + declared_in: + - ADR-L-0007 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0007#DEC-0007 + extraction_phase: extract_decision + classification: explicit + generator: adr-architecture-index +- id: INV-0001 + entity_type: invariant + name: INV-0001 + summary: 'Single repository only: RECON discovers files within the current repository. + Cross-repository reconciliation is out of scope.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0001 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Single repository only: RECON discovers files within the current repository. + Cross-repository reconciliation is out of scope.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0001 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0002 + entity_type: invariant + name: INV-0002 + summary: 'Incremental reconciliation: Only files that have changed since the last + run are re-extracted (when timestamp detection is available).' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0002 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Incremental reconciliation: Only files that have changed since the + last run are re-extracted (when timestamp detection is available).' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0002 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0003 + entity_type: invariant + name: INV-0003 + summary: 'Configurable source directories: Specified via `ste.config.json` or auto-detected.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0003 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Configurable source directories: Specified via `ste.config.json` or + auto-detected.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0003 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0004 + entity_type: invariant + name: INV-0004 + summary: 'Shallow extraction: Extract structural elements (functions, classes, imports, + exports) without deep semantic analysis.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0004 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Shallow extraction: Extract structural elements (functions, classes, + imports, exports) without deep semantic analysis.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0004 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0005 + entity_type: invariant + name: INV-0005 + summary: 'No deep semantic analysis: Do not attempt to understand function behavior, + side effects, or complex type flows.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0005 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'No deep semantic analysis: Do not attempt to understand function behavior, + side effects, or complex type flows.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0005 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0006 + entity_type: invariant + name: INV-0006 + summary: 'Multi-language support: TypeScript, Python, CloudFormation, JSON (see + E-ADR-005), Angular, CSS/SCSS (see E-ADR-006).' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0006 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Multi-language support: TypeScript, Python, CloudFormation, JSON (see + E-ADR-005), Angular, CSS/SCSS (see E-ADR-006).' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0006 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0007 + entity_type: invariant + name: INV-0007 + summary: 'Portable execution: RECON must work when dropped into any project.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0007 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Portable execution: RECON must work when dropped into any project.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0007 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0008 + entity_type: invariant + name: INV-0008 + summary: 'Provisional mapping: Normalization to AI-DOC schema is best-effort, not + canonical.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0008 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Provisional mapping: Normalization to AI-DOC schema is best-effort, + not canonical.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0008 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0009 + entity_type: invariant + name: INV-0009 + summary: 'Schema evolution expected: The AI-DOC schema is still evolving; normalization + will change.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0009 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Schema evolution expected: The AI-DOC schema is still evolving; normalization + will change.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0009 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0010 + entity_type: invariant + name: INV-0010 + summary: 'ID stability: Element IDs should be stable across runs for the same source + element.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0010 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'ID stability: Element IDs should be stable across runs for the same + source element.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0010 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0011 + entity_type: invariant + name: INV-0011 + summary: 'State is authoritative, not historical: Each run produces the current + truth, not a delta.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0011 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'State is authoritative, not historical: Each run produces the current + truth, not a delta.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0011 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0012 + entity_type: invariant + name: INV-0012 + summary: 'Create/Update/Delete semantics: New slices are created, changed slices + are updated, orphaned slices are deleted.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0012 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Create/Update/Delete semantics: New slices are created, changed slices + are updated, orphaned slices are deleted.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0012 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0013 + entity_type: invariant + name: INV-0013 + summary: 'Orphan detection: Slices from processed source files that no longer exist + in code are removed.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0013 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Orphan detection: Slices from processed source files that no longer + exist in code are removed.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0013 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: SYS-0001 + entity_type: system + name: Runtime Orchestration and Assistant Integration + summary: ste-runtime now contains a runtime orchestration boundary that keeps semantic + state fresh, exposes assistant-facing MCP tools, performs reconciliation gating + and freshness checks, and assembles implementation context and + canonical_source: + source_type: physical_system_adr + source_ref: ADR-PS-0001 + artifact_path: adrs/physical-system/ADR-PS-0001-runtime-orchestration-and-assistant-integration.yaml + source_refs: [] + metadata: + adr_id: ADR-PS-0001 + implements_logical: + - ADR-L-0004 + - ADR-L-0006 + - ADR-L-0007 + technologies: + - typescript + - node.js + - mcp + - chokidar + - zod + relationships: + declared_in: + - ADR-PS-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_system_adr + source_ref: ADR-PS-0001 + extraction_phase: extract_system + classification: explicit + generator: adr-architecture-index +- id: SYS-0002 + entity_type: system + name: Semantic Extraction Subsystem + summary: ste-runtime extraction is now a subsystem containing multiple first-class + extractors and normalization flows rather than a pair of isolated physical slices. + This ADR groups the implemented extractor estate under a concre + canonical_source: + source_type: physical_system_adr + source_ref: ADR-PS-0002 + artifact_path: adrs/physical-system/ADR-PS-0002-semantic-extraction-subsystem.yaml + source_refs: [] + metadata: + adr_id: ADR-PS-0002 + implements_logical: + - ADR-L-0001 + - ADR-L-0005 + technologies: + - typescript + - node.js + - json + - angular + - css + - cloudformation + relationships: + declared_in: + - ADR-PS-0002 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_system_adr + source_ref: ADR-PS-0002 + extraction_phase: extract_system + classification: explicit + generator: adr-architecture-index diff --git a/adrs/index/invariant-registry.yaml b/adrs/index/invariant-registry.yaml new file mode 100644 index 0000000..757ef86 --- /dev/null +++ b/adrs/index/invariant-registry.yaml @@ -0,0 +1,533 @@ +schema_version: '1.1' +type: normalized_entity_registry +entities: +- id: INV-0001 + entity_type: invariant + name: INV-0001 + summary: 'Single repository only: RECON discovers files within the current repository. + Cross-repository reconciliation is out of scope.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0001 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Single repository only: RECON discovers files within the current repository. + Cross-repository reconciliation is out of scope.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0001 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0002 + entity_type: invariant + name: INV-0002 + summary: 'Incremental reconciliation: Only files that have changed since the last + run are re-extracted (when timestamp detection is available).' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0002 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Incremental reconciliation: Only files that have changed since the + last run are re-extracted (when timestamp detection is available).' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0002 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0003 + entity_type: invariant + name: INV-0003 + summary: 'Configurable source directories: Specified via `ste.config.json` or auto-detected.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0003 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Configurable source directories: Specified via `ste.config.json` or + auto-detected.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0003 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0004 + entity_type: invariant + name: INV-0004 + summary: 'Shallow extraction: Extract structural elements (functions, classes, imports, + exports) without deep semantic analysis.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0004 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Shallow extraction: Extract structural elements (functions, classes, + imports, exports) without deep semantic analysis.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0004 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0005 + entity_type: invariant + name: INV-0005 + summary: 'No deep semantic analysis: Do not attempt to understand function behavior, + side effects, or complex type flows.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0005 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'No deep semantic analysis: Do not attempt to understand function behavior, + side effects, or complex type flows.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0005 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0006 + entity_type: invariant + name: INV-0006 + summary: 'Multi-language support: TypeScript, Python, CloudFormation, JSON (see + E-ADR-005), Angular, CSS/SCSS (see E-ADR-006).' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0006 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Multi-language support: TypeScript, Python, CloudFormation, JSON (see + E-ADR-005), Angular, CSS/SCSS (see E-ADR-006).' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0006 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0007 + entity_type: invariant + name: INV-0007 + summary: 'Portable execution: RECON must work when dropped into any project.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0007 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Portable execution: RECON must work when dropped into any project.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0007 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0008 + entity_type: invariant + name: INV-0008 + summary: 'Provisional mapping: Normalization to AI-DOC schema is best-effort, not + canonical.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0008 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Provisional mapping: Normalization to AI-DOC schema is best-effort, + not canonical.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0008 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0009 + entity_type: invariant + name: INV-0009 + summary: 'Schema evolution expected: The AI-DOC schema is still evolving; normalization + will change.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0009 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Schema evolution expected: The AI-DOC schema is still evolving; normalization + will change.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0009 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0010 + entity_type: invariant + name: INV-0010 + summary: 'ID stability: Element IDs should be stable across runs for the same source + element.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0010 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'ID stability: Element IDs should be stable across runs for the same + source element.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0010 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0011 + entity_type: invariant + name: INV-0011 + summary: 'State is authoritative, not historical: Each run produces the current + truth, not a delta.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0011 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'State is authoritative, not historical: Each run produces the current + truth, not a delta.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0011 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0012 + entity_type: invariant + name: INV-0012 + summary: 'Create/Update/Delete semantics: New slices are created, changed slices + are updated, orphaned slices are deleted.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0012 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Create/Update/Delete semantics: New slices are created, changed slices + are updated, orphaned slices are deleted.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0012 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index +- id: INV-0013 + entity_type: invariant + name: INV-0013 + summary: 'Orphan detection: Slices from processed source files that no longer exist + in code are removed.' + canonical_source: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0013 + artifact_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + source_refs: [] + metadata: + adr_id: ADR-L-0001 + scope: global + statement: 'Orphan detection: Slices from processed source files that no longer + exist in code are removed.' + enforcement_level: must + declaration_mode: local + upheld_by_decisions: [] + relationships: + declared_in: + - ADR-L-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: logical_adr + source_ref: ADR-L-0001#INV-0013 + extraction_phase: assign_canonical_invariant + classification: explicit + generator: adr-architecture-index diff --git a/adrs/index/relationship-registry.yaml b/adrs/index/relationship-registry.yaml new file mode 100644 index 0000000..58db883 --- /dev/null +++ b/adrs/index/relationship-registry.yaml @@ -0,0 +1,513 @@ +schema_version: '1.1' +type: relationship_registry +relationships: +- relationship_id: declared_in:CAP-0007:ADR-L-0007 + relationship_type: declared_in + from_entity_id: CAP-0007 + to_entity_id: ADR-L-0007 + provenance_classification: explicit + evidence: + - ADR-L-0007#CAP-0007 + canonical_source_ref: ADR-L-0007#CAP-0007 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:COMP-0001:ADR-PC-0001 + relationship_type: declared_in + from_entity_id: COMP-0001 + to_entity_id: ADR-PC-0001 + provenance_classification: explicit + evidence: + - ADR-PC-0001#COMP-0001 + canonical_source_ref: ADR-PC-0001#COMP-0001 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:COMP-0002:ADR-PC-0002 + relationship_type: declared_in + from_entity_id: COMP-0002 + to_entity_id: ADR-PC-0002 + provenance_classification: explicit + evidence: + - ADR-PC-0002#COMP-0002 + canonical_source_ref: ADR-PC-0002#COMP-0002 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:COMP-0003:ADR-PC-0003 + relationship_type: declared_in + from_entity_id: COMP-0003 + to_entity_id: ADR-PC-0003 + provenance_classification: explicit + evidence: + - ADR-PC-0003#COMP-0003 + canonical_source_ref: ADR-PC-0003#COMP-0003 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:COMP-0004:ADR-PC-0004 + relationship_type: declared_in + from_entity_id: COMP-0004 + to_entity_id: ADR-PC-0004 + provenance_classification: explicit + evidence: + - ADR-PC-0004#COMP-0004 + canonical_source_ref: ADR-PC-0004#COMP-0004 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:COMP-0005:ADR-PC-0005 + relationship_type: declared_in + from_entity_id: COMP-0005 + to_entity_id: ADR-PC-0005 + provenance_classification: explicit + evidence: + - ADR-PC-0005#COMP-0005 + canonical_source_ref: ADR-PC-0005#COMP-0005 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:COMP-0006:ADR-PC-0006 + relationship_type: declared_in + from_entity_id: COMP-0006 + to_entity_id: ADR-PC-0006 + provenance_classification: explicit + evidence: + - ADR-PC-0006#COMP-0006 + canonical_source_ref: ADR-PC-0006#COMP-0006 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:COMP-0007:ADR-PC-0007 + relationship_type: declared_in + from_entity_id: COMP-0007 + to_entity_id: ADR-PC-0007 + provenance_classification: explicit + evidence: + - ADR-PC-0007#COMP-0007 + canonical_source_ref: ADR-PC-0007#COMP-0007 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:DEC-0001:ADR-L-0001 + relationship_type: declared_in + from_entity_id: DEC-0001 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#DEC-0001 + canonical_source_ref: ADR-L-0001#DEC-0001 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:DEC-0002:ADR-L-0002 + relationship_type: declared_in + from_entity_id: DEC-0002 + to_entity_id: ADR-L-0002 + provenance_classification: explicit + evidence: + - ADR-L-0002#DEC-0002 + canonical_source_ref: ADR-L-0002#DEC-0002 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:DEC-0003:ADR-L-0003 + relationship_type: declared_in + from_entity_id: DEC-0003 + to_entity_id: ADR-L-0003 + provenance_classification: explicit + evidence: + - ADR-L-0003#DEC-0003 + canonical_source_ref: ADR-L-0003#DEC-0003 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:DEC-0004:ADR-L-0004 + relationship_type: declared_in + from_entity_id: DEC-0004 + to_entity_id: ADR-L-0004 + provenance_classification: explicit + evidence: + - ADR-L-0004#DEC-0004 + canonical_source_ref: ADR-L-0004#DEC-0004 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:DEC-0005:ADR-L-0005 + relationship_type: declared_in + from_entity_id: DEC-0005 + to_entity_id: ADR-L-0005 + provenance_classification: explicit + evidence: + - ADR-L-0005#DEC-0005 + canonical_source_ref: ADR-L-0005#DEC-0005 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:DEC-0006:ADR-L-0006 + relationship_type: declared_in + from_entity_id: DEC-0006 + to_entity_id: ADR-L-0006 + provenance_classification: explicit + evidence: + - ADR-L-0006#DEC-0006 + canonical_source_ref: ADR-L-0006#DEC-0006 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:DEC-0007:ADR-L-0007 + relationship_type: declared_in + from_entity_id: DEC-0007 + to_entity_id: ADR-L-0007 + provenance_classification: explicit + evidence: + - ADR-L-0007#DEC-0007 + canonical_source_ref: ADR-L-0007#DEC-0007 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0001:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0001 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0001 + canonical_source_ref: ADR-L-0001#INV-0001 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0002:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0002 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0002 + canonical_source_ref: ADR-L-0001#INV-0002 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0003:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0003 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0003 + canonical_source_ref: ADR-L-0001#INV-0003 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0004:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0004 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0004 + canonical_source_ref: ADR-L-0001#INV-0004 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0005:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0005 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0005 + canonical_source_ref: ADR-L-0001#INV-0005 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0006:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0006 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0006 + canonical_source_ref: ADR-L-0001#INV-0006 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0007:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0007 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0007 + canonical_source_ref: ADR-L-0001#INV-0007 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0008:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0008 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0008 + canonical_source_ref: ADR-L-0001#INV-0008 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0009:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0009 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0009 + canonical_source_ref: ADR-L-0001#INV-0009 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0010:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0010 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0010 + canonical_source_ref: ADR-L-0001#INV-0010 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0011:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0011 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0011 + canonical_source_ref: ADR-L-0001#INV-0011 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0012:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0012 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0012 + canonical_source_ref: ADR-L-0001#INV-0012 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:INV-0013:ADR-L-0001 + relationship_type: declared_in + from_entity_id: INV-0013 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0001#INV-0013 + canonical_source_ref: ADR-L-0001#INV-0013 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:SYS-0001:ADR-PS-0001 + relationship_type: declared_in + from_entity_id: SYS-0001 + to_entity_id: ADR-PS-0001 + provenance_classification: explicit + evidence: + - ADR-PS-0001 + canonical_source_ref: ADR-PS-0001 + confidence: 1.0 + metadata: {} +- relationship_id: declared_in:SYS-0002:ADR-PS-0002 + relationship_type: declared_in + from_entity_id: SYS-0002 + to_entity_id: ADR-PS-0002 + provenance_classification: explicit + evidence: + - ADR-PS-0002 + canonical_source_ref: ADR-PS-0002 + confidence: 1.0 + metadata: {} +- relationship_id: embodied_in:COMP-0001:SYS-0001 + relationship_type: embodied_in + from_entity_id: COMP-0001 + to_entity_id: SYS-0001 + provenance_classification: explicit + evidence: + - ADR-PC-0001 + canonical_source_ref: ADR-PC-0001#COMP-0001 + confidence: 1.0 + metadata: {} +- relationship_id: embodied_in:COMP-0002:SYS-0001 + relationship_type: embodied_in + from_entity_id: COMP-0002 + to_entity_id: SYS-0001 + provenance_classification: explicit + evidence: + - ADR-PC-0002 + canonical_source_ref: ADR-PC-0002#COMP-0002 + confidence: 1.0 + metadata: {} +- relationship_id: embodied_in:COMP-0003:SYS-0001 + relationship_type: embodied_in + from_entity_id: COMP-0003 + to_entity_id: SYS-0001 + provenance_classification: explicit + evidence: + - ADR-PC-0003 + canonical_source_ref: ADR-PC-0003#COMP-0003 + confidence: 1.0 + metadata: {} +- relationship_id: embodied_in:COMP-0004:SYS-0001 + relationship_type: embodied_in + from_entity_id: COMP-0004 + to_entity_id: SYS-0001 + provenance_classification: explicit + evidence: + - ADR-PC-0004 + canonical_source_ref: ADR-PC-0004#COMP-0004 + confidence: 1.0 + metadata: {} +- relationship_id: embodied_in:COMP-0005:SYS-0002 + relationship_type: embodied_in + from_entity_id: COMP-0005 + to_entity_id: SYS-0002 + provenance_classification: explicit + evidence: + - ADR-PC-0005 + canonical_source_ref: ADR-PC-0005#COMP-0005 + confidence: 1.0 + metadata: {} +- relationship_id: embodied_in:COMP-0006:SYS-0002 + relationship_type: embodied_in + from_entity_id: COMP-0006 + to_entity_id: SYS-0002 + provenance_classification: explicit + evidence: + - ADR-PC-0006 + canonical_source_ref: ADR-PC-0006#COMP-0006 + confidence: 1.0 + metadata: {} +- relationship_id: embodied_in:COMP-0007:SYS-0002 + relationship_type: embodied_in + from_entity_id: COMP-0007 + to_entity_id: SYS-0002 + provenance_classification: explicit + evidence: + - ADR-PC-0007 + canonical_source_ref: ADR-PC-0007#COMP-0007 + confidence: 1.0 + metadata: {} +- relationship_id: references:ADR-L-0001:ADR-L-0002 + relationship_type: references + from_entity_id: ADR-L-0001 + to_entity_id: ADR-L-0002 + provenance_classification: explicit + evidence: + - ADR-L-0001 + canonical_source_ref: ADR-L-0001 + confidence: 1.0 + metadata: {} +- relationship_id: references:ADR-L-0001:ADR-L-0003 + relationship_type: references + from_entity_id: ADR-L-0001 + to_entity_id: ADR-L-0003 + provenance_classification: explicit + evidence: + - ADR-L-0001 + canonical_source_ref: ADR-L-0001 + confidence: 1.0 + metadata: {} +- relationship_id: references:ADR-L-0002:ADR-L-0001 + relationship_type: references + from_entity_id: ADR-L-0002 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0002 + canonical_source_ref: ADR-L-0002 + confidence: 1.0 + metadata: {} +- relationship_id: references:ADR-L-0003:ADR-L-0001 + relationship_type: references + from_entity_id: ADR-L-0003 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0003 + canonical_source_ref: ADR-L-0003 + confidence: 1.0 + metadata: {} +- relationship_id: references:ADR-L-0004:ADR-L-0001 + relationship_type: references + from_entity_id: ADR-L-0004 + to_entity_id: ADR-L-0001 + provenance_classification: explicit + evidence: + - ADR-L-0004 + canonical_source_ref: ADR-L-0004 + confidence: 1.0 + metadata: {} +- relationship_id: references:ADR-L-0007:ADR-L-0004 + relationship_type: references + from_entity_id: ADR-L-0007 + to_entity_id: ADR-L-0004 + provenance_classification: explicit + evidence: + - ADR-L-0007 + canonical_source_ref: ADR-L-0007 + confidence: 1.0 + metadata: {} +- relationship_id: references:ADR-L-0007:ADR-L-0006 + relationship_type: references + from_entity_id: ADR-L-0007 + to_entity_id: ADR-L-0006 + provenance_classification: explicit + evidence: + - ADR-L-0007 + canonical_source_ref: ADR-L-0007 + confidence: 1.0 + metadata: {} +- relationship_id: related_to:ADR-PS-0001:ADR-PC-0001 + relationship_type: related_to + from_entity_id: ADR-PS-0001 + to_entity_id: ADR-PC-0001 + provenance_classification: derived + evidence: + - ADR-PS-0001 + canonical_source_ref: ADR-PS-0001 + confidence: 0.8 + metadata: {} +- relationship_id: related_to:ADR-PS-0001:ADR-PC-0002 + relationship_type: related_to + from_entity_id: ADR-PS-0001 + to_entity_id: ADR-PC-0002 + provenance_classification: derived + evidence: + - ADR-PS-0001 + canonical_source_ref: ADR-PS-0001 + confidence: 0.8 + metadata: {} +- relationship_id: related_to:ADR-PS-0001:ADR-PC-0003 + relationship_type: related_to + from_entity_id: ADR-PS-0001 + to_entity_id: ADR-PC-0003 + provenance_classification: derived + evidence: + - ADR-PS-0001 + canonical_source_ref: ADR-PS-0001 + confidence: 0.8 + metadata: {} +- relationship_id: related_to:ADR-PS-0001:ADR-PC-0004 + relationship_type: related_to + from_entity_id: ADR-PS-0001 + to_entity_id: ADR-PC-0004 + provenance_classification: derived + evidence: + - ADR-PS-0001 + canonical_source_ref: ADR-PS-0001 + confidence: 0.8 + metadata: {} +- relationship_id: related_to:ADR-PS-0002:ADR-PC-0005 + relationship_type: related_to + from_entity_id: ADR-PS-0002 + to_entity_id: ADR-PC-0005 + provenance_classification: derived + evidence: + - ADR-PS-0002 + canonical_source_ref: ADR-PS-0002 + confidence: 0.8 + metadata: {} +- relationship_id: related_to:ADR-PS-0002:ADR-PC-0006 + relationship_type: related_to + from_entity_id: ADR-PS-0002 + to_entity_id: ADR-PC-0006 + provenance_classification: derived + evidence: + - ADR-PS-0002 + canonical_source_ref: ADR-PS-0002 + confidence: 0.8 + metadata: {} +- relationship_id: related_to:ADR-PS-0002:ADR-PC-0007 + relationship_type: related_to + from_entity_id: ADR-PS-0002 + to_entity_id: ADR-PC-0007 + provenance_classification: derived + evidence: + - ADR-PS-0002 + canonical_source_ref: ADR-PS-0002 + confidence: 0.8 + metadata: {} diff --git a/adrs/index/system-registry.yaml b/adrs/index/system-registry.yaml new file mode 100644 index 0000000..8d9a07a --- /dev/null +++ b/adrs/index/system-registry.yaml @@ -0,0 +1,95 @@ +schema_version: '1.1' +type: normalized_entity_registry +entities: +- id: SYS-0001 + entity_type: system + name: Runtime Orchestration and Assistant Integration + summary: ste-runtime now contains a runtime orchestration boundary that keeps semantic + state fresh, exposes assistant-facing MCP tools, performs reconciliation gating + and freshness checks, and assembles implementation context and + canonical_source: + source_type: physical_system_adr + source_ref: ADR-PS-0001 + artifact_path: adrs/physical-system/ADR-PS-0001-runtime-orchestration-and-assistant-integration.yaml + source_refs: [] + metadata: + adr_id: ADR-PS-0001 + implements_logical: + - ADR-L-0004 + - ADR-L-0006 + - ADR-L-0007 + technologies: + - typescript + - node.js + - mcp + - chokidar + - zod + relationships: + declared_in: + - ADR-PS-0001 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_system_adr + source_ref: ADR-PS-0001 + extraction_phase: extract_system + classification: explicit + generator: adr-architecture-index +- id: SYS-0002 + entity_type: system + name: Semantic Extraction Subsystem + summary: ste-runtime extraction is now a subsystem containing multiple first-class + extractors and normalization flows rather than a pair of isolated physical slices. + This ADR groups the implemented extractor estate under a concre + canonical_source: + source_type: physical_system_adr + source_ref: ADR-PS-0002 + artifact_path: adrs/physical-system/ADR-PS-0002-semantic-extraction-subsystem.yaml + source_refs: [] + metadata: + adr_id: ADR-PS-0002 + implements_logical: + - ADR-L-0001 + - ADR-L-0005 + technologies: + - typescript + - node.js + - json + - angular + - css + - cloudformation + relationships: + declared_in: + - ADR-PS-0002 + references: [] + related_to: [] + enforces: [] + enabled_by: [] + enables: [] + governs: [] + implemented_by: [] + embodied_in: [] + supersedes: [] + superseded_by: [] + refines: [] + completeness: + status: complete + missing_fields: [] + provenance: + source_type: physical_system_adr + source_ref: ADR-PS-0002 + extraction_phase: extract_system + classification: explicit + generator: adr-architecture-index diff --git a/adrs/index/unresolved-registry.yaml b/adrs/index/unresolved-registry.yaml new file mode 100644 index 0000000..126e7fc --- /dev/null +++ b/adrs/index/unresolved-registry.yaml @@ -0,0 +1,3 @@ +schema_version: '1.1' +type: unresolved_registry +unresolved: [] diff --git a/adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml b/adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml index 7b3b183..a7f9e9a 100644 --- a/adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml +++ b/adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml @@ -19,28 +19,17 @@ related_adrs: - ADR-L-0002 - ADR-L-0003 supersedes: [] -context: 'The STE Architecture Specification defines RECON (Reconciliation Engine) - as the mechanism for extracting semantic state from source code and populating AI-DOC. - The question arose: How should RECON operate during the exploratory development - phase when foundational components are still being built? - +context: |- + The STE Architecture Specification defines RECON (Reconciliation Engine) as the mechanism for extracting semantic state from source code and populating AI-DOC. The question arose: How should RECON operate during the exploratory development phase when foundational components are still being built? Key tensions: + 1. **Canonical vs. Provisional State:** Should RECON produce canonical state that is authoritative for downstream systems? + 2. **Automatic Resolution vs. Conflict Surfacing:** Should RECON automatically resolve conflicts or surface them for human judgment? + 3. **Blocking vs. Non-Blocking:** Should RECON block development workflows when conflicts are detected? + 4. **Single Repository vs. Multi-Repository:** What is the scope of RECON's reconciliation? - 1. **Canonical vs. Provisional State:** Should RECON produce canonical state that - is authoritative for downstream systems? - - 2. **Automatic Resolution vs. Conflict Surfacing:** Should RECON automatically resolve - conflicts or surface them for human judgment? - - 3. **Blocking vs. Non-Blocking:** Should RECON block development workflows when - conflicts are detected? - - 4. **Single Repository vs. Multi-Repository:** What is the scope of RECON''s reconciliation? - - - ---' + --- capabilities: [] architectural_boundaries: [] interaction_contracts: [] @@ -180,60 +169,36 @@ decisions: - id: DEC-0001 summary: RECON executes provisionally, generating semantic pressure without assuming correctness. - rationale: '### 1. Semantic Pressure Over Semantic Truth - - - RECON exists to **observe how semantic truth breaks under change**, not to declare - what truth is. During exploratory development, the extraction algorithms, normalization - schemas, and conflict detection heuristics are all evolving. Declaring any output - as "canonical" would be premature. + rationale: |- + ### 1. Semantic Pressure Over Semantic Truth + RECON exists to **observe how semantic truth breaks under change**, not to declare what truth is. During exploratory development, the extraction algorithms, normalization schemas, and conflict detection heuristics are all evolving. Declaring any output as "canonical" would be premature. By generating pressure without claiming correctness, RECON: - - Forces execution of incomplete implementations - - Surfaces edge cases and extraction gaps - - Generates learning evidence for future refinement - - Avoids false confidence in evolving algorithms - ### 2. Conflicts Require Human Judgment - - Automatic conflict resolution assumes the system understands developer intent. - During this phase, RECON cannot reliably determine: - + Automatic conflict resolution assumes the system understands developer intent. During this phase, RECON cannot reliably determine: - Was a function renamed or deleted? - - Is a signature change intentional or accidental? - - Which version of a conflicting definition is correct? - - All conflicts are written to disk as YAML files in `.ste/state/conflicts/active/` - for human review. RECON surfaces evidence; humans render judgment. - + All conflicts are written to disk as YAML files in `.ste/state/conflicts/active/` for human review. RECON surfaces evidence; humans render judgment. ### 3. Development Must Not Be Blocked - RECON is a learning tool, not an enforcement mechanism. Blocking commits would: - - - Create friction disproportionate to RECON''s maturity - + - Create friction disproportionate to RECON's maturity - Force developers to work around false positives - - Reduce willingness to run RECON frequently + By remaining non-blocking, RECON encourages frequent execution and generates more learning data. - By remaining non-blocking, RECON encourages frequent execution and generates more - learning data. - - - ---' + --- alternatives_considered: [] consequences: positive: diff --git a/adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml b/adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml index 1f53eb9..ffa7722 100644 --- a/adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml +++ b/adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml @@ -18,23 +18,17 @@ tags: related_adrs: - ADR-L-0001 supersedes: [] -context: 'RECON generates AI-DOC state from source code extraction. The question arose: - How should RECON validate its own output to ensure consistency and quality? - +context: |- + RECON generates AI-DOC state from source code extraction. The question arose: How should RECON validate its own output to ensure consistency and quality? Key tensions: - 1. **Blocking vs. Non-Blocking:** Should validation failures halt RECON execution? - 2. **Verdict vs. Evidence:** Should validation declare correctness or surface observations? - 3. **Scope:** What aspects of AI-DOC state should be validated? - 4. **Integration:** When does validation run in the RECON pipeline? - - ---' + --- capabilities: [] architectural_boundaries: [] interaction_contracts: [] @@ -42,63 +36,40 @@ constraints: [] invariants: [] non_functional_requirements: [] decisions: -- id: DEC-0001 +- id: DEC-0002 summary: RECON self-validation is non-blocking, report-only, and exploratory. - rationale: '### 1. Non-Blocking Preserves Learning - - - If validation blocked execution on every finding, RECON would become unusable - during exploratory development. Many validation findings are informational or - represent known limitations in extraction algorithms. + rationale: |- + ### 1. Non-Blocking Preserves Learning + If validation blocked execution on every finding, RECON would become unusable during exploratory development. Many validation findings are informational or represent known limitations in extraction algorithms. By remaining non-blocking, validation: - - Captures all findings without losing work - - Allows developers to review findings at their discretion - - Generates historical data for pattern analysis - - Avoids false positive friction - ### 2. Evidence Over Verdicts - - During exploratory development, the validators themselves are evolving. A "verdict" - implies confidence that is premature. Instead, validators generate: - + During exploratory development, the validators themselves are evolving. A "verdict" implies confidence that is premature. Instead, validators generate: - Observations about state structure - - Anomalies that may indicate issues - - Coverage gaps in extraction - - Repeatability concerns - Developers interpret findings; validators do not judge. - ### 3. Categorization Enables Prioritization - All findings are categorized: - | Category | Meaning | Action | - |----------|---------|--------| - | ERROR | Structural issue that may indicate a bug | Investigate promptly | - | WARNING | Anomaly that may indicate a problem | Review when convenient | - | INFO | Observation for awareness | Log for future reference | - - ---' + --- alternatives_considered: [] consequences: positive: @@ -116,3 +87,8 @@ decisions: - Use findings to guide extractor improvements related_invariants: [] gaps: [] +migration_origin: + remapped_entities: + - entity_type: decision + from: DEC-0001 + to: DEC-0002 diff --git a/adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml b/adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml index be32056..df6e852 100644 --- a/adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml +++ b/adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml @@ -18,28 +18,19 @@ tags: related_adrs: - ADR-L-0001 supersedes: [] -context: 'The STE Architecture Specification (ste-spec) defines a 9-stage Cognitive - Execution Model (CEM): - +context: |- + The STE Architecture Specification (ste-spec) defines a 9-stage Cognitive Execution Model (CEM): ``` - Perception → Orientation → Analysis → Deliberation → - Planning → Execution → Observation → Reflection → Adaptation - ``` + CEM is intended to orchestrate governed AI cognition, calling RSS for context assembly, enforcing DAP for human-in-the-loop decisions, and maintaining audit trails. - CEM is intended to orchestrate governed AI cognition, calling RSS for context assembly, - enforcing DAP for human-in-the-loop decisions, and maintaining audit trails. - + The question arose: Should CEM be implemented early in ste-runtime development, or deferred until foundational components are stable? - The question arose: Should CEM be implemented early in ste-runtime development, - or deferred until foundational components are stable? - - - ---' + --- capabilities: [] architectural_boundaries: [] interaction_contracts: [] @@ -47,85 +38,52 @@ constraints: [] invariants: [] non_functional_requirements: [] decisions: -- id: DEC-0001 +- id: DEC-0003 summary: CEM implementation is intentionally deferred. - rationale: '### 1. CEM Orchestrates Components That Must Exist First - - - CEM''s stages call into foundational components: + rationale: |- + ### 1. CEM Orchestrates Components That Must Exist First + CEM's stages call into foundational components: - **Orientation** calls RSS for context assembly - - **Analysis** reads AI-DOC semantic state - - **Deliberation** invokes DAP for human judgment - - **Observation** checks divergence state - Building CEM before these components are stable would result in: - - Premature abstractions - - Rework as component APIs evolve - - Incomplete orchestration coverage - ### 2. Human-in-Loop Provides Implicit CEM Today - - During development, Cursor/Claude interaction with the developer satisfies CEM - governance: - + During development, Cursor/Claude interaction with the developer satisfies CEM governance: | CEM Stage | Current Implementation | - |-----------|----------------------| - | Perception | Developer provides task | - | Orientation | Agent queries RSS / searches codebase | - | Analysis | Agent reads code, understands context | - | Deliberation | Agent asks clarifying questions (implicit DAP) | - | Planning | Agent proposes solution | - | Execution | Agent edits files, runs commands | - | Observation | Developer/agent observe results | - | Reflection | Developer accepts/rejects; agent adjusts | - | Adaptation | Future responses incorporate learning | - - This implicit CEM is acceptable per ste-spec Section 4.7 because governance is - maintained through human oversight. - + This implicit CEM is acceptable per ste-spec Section 4.7 because governance is maintained through human oversight. ### 3. CEM is the Hardest Component - CEM requires: - - State machine formalization - - Integration with all other components - - Audit trail persistence - - Configurable governance policies - - Error recovery and rollback semantics - Tackling this complexity after foundations are solid reduces risk. - - ---' + --- alternatives_considered: [] consequences: positive: @@ -142,3 +100,8 @@ decisions: - Use execution pressure to surface integration gaps related_invariants: [] gaps: [] +migration_origin: + remapped_entities: + - entity_type: decision + from: DEC-0001 + to: DEC-0003 diff --git a/adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml b/adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml index d16a0da..552349d 100644 --- a/adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml +++ b/adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml @@ -54,7 +54,7 @@ constraints: [] invariants: [] non_functional_requirements: [] decisions: -- id: DEC-0001 +- id: DEC-0004 summary: 'ste-runtime is a single process that combines:' rationale: "### The Watchdog IS the Conflict Resolution Process\n\nWhen a file moves:\n\ 1. Watchdog detects the move (authoritative: it observed the file system event)\n\ @@ -74,3 +74,8 @@ decisions: alternatives_considered: [] related_invariants: [] gaps: [] +migration_origin: + remapped_entities: + - entity_type: decision + from: DEC-0001 + to: DEC-0004 diff --git a/adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml b/adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml index baf05e0..d049039 100644 --- a/adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml +++ b/adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml @@ -24,7 +24,7 @@ constraints: [] invariants: [] non_functional_requirements: [] decisions: -- id: DEC-0001 +- id: DEC-0005 summary: '' rationale: '' alternatives_considered: [] @@ -67,3 +67,8 @@ decisions: - Clear discovery debugging output related_invariants: [] gaps: [] +migration_origin: + remapped_entities: + - entity_type: decision + from: DEC-0001 + to: DEC-0005 diff --git a/adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml b/adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml index 17a7395..86a3788 100644 --- a/adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml +++ b/adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml @@ -17,53 +17,33 @@ tags: - natural-language related_adrs: [] supersedes: [] -context: 'E-ADR-004 established the RSS CLI and TypeScript API as the foundation for - graph traversal and context assembly. However, a gap exists between: - - - 1. **Raw RSS operations** (search, dependencies, blast-radius) - require knowing - the API - - 2. **Natural language queries** ("Tell me about X") - how humans and AI agents actually - communicate +context: |- + E-ADR-004 established the RSS CLI and TypeScript API as the foundation for graph traversal and context assembly. However, a gap exists between: + 1. **Raw RSS operations** (search, dependencies, blast-radius) - require knowing the API + 2. **Natural language queries** ("Tell me about X") - how humans and AI agents actually communicate The challenge: **How do we make RSS consumption as seamless as natural conversation?** - Observations from usage patterns: - | Pattern | Example Query | Current RSS Approach | - |---------|---------------|---------------------| - | Describe | "Tell me about X" | `search X` → `blast-radius` → manual assembly | - | Explain | "How does X work?" | Same as above | - | Impact | "What would change affect?" | `blast-radius X --depth=3` | - | List | "Show all Lambda handlers" | `by-tag handler:lambda` | - | Locate | "Where is X?" | `search X` | - Each pattern requires the caller to: - 1. Know which RSS operation to use - 2. Compose operations correctly - 3. Parse unstructured output - 4. Generate follow-up queries - This friction degrades both human UX and AI agent efficiency. - - ---' + --- capabilities: [] architectural_boundaries: [] interaction_contracts: [] @@ -71,28 +51,63 @@ constraints: [] invariants: [] non_functional_requirements: [] decisions: -- id: DEC-0001 +- id: DEC-0006 summary: 'Implement a Conversational Query Interface (CQI) as a layer above RSS that:' - rationale: "### 1. Reduces Cognitive Load for Both Humans and AI\n\nWithout CQI:\n\ - ```\nHuman: \"What would be affected by changing the auth service?\"\n→ Human\ - \ must know: use blast-radius, specify key format, parse output\n→ AI must know:\ - \ compose RSS calls, format results, generate follow-ups\n```\n\nWith CQI:\n```\n\ - Human: \"What would be affected by changing the auth service?\"\n→ CQI: intent=impact,\ - \ blastRadius(depth=3), structured response with files\n```\n\n### 2. Intent Classification\ - \ Enables Optimization\n\nDifferent intents have different optimal strategies:\n\ - \n| Intent | Optimization |\n|--------|-------------|\n| `list` | Use tag query\ - \ if applicable (O(n) scan vs O(1) tag lookup) |\n| `impact` | Increase depth,\ - \ cap nodes |\n| `relationship` | Traverse both, compute intersection |\n| `describe`\ - \ | Get context + suggested follow-ups |\n\n### 3. Caching Amortizes Graph Load\ - \ Cost\n\nBenchmark results:\n\n| Metric | Value |\n|--------|-------|\n| Graph\ - \ load (cold) | ~300-400ms |\n| Uncached query | ~2-4ms |\n| Cached query | **~0.2-0.3ms**\ - \ |\n\nFor interactive sessions, caching provides ~10x speedup on repeated patterns.\n\ - \n### 4. Suggested Queries Enable Exploration\n\nCQI generates contextual follow-ups:\n\ - \n```\nQuery: \"Tell me about the auth service\"\nSuggested:\n → What does AuthService\ - \ depend on?\n → What depends on AuthService?\n → Impact of changing AuthService\n\ - ```\n\nThis guides both humans and AI agents toward productive exploration.\n\n\ - ---" + rationale: |- + ### 1. Reduces Cognitive Load for Both Humans and AI + + Without CQI: + ``` + Human: "What would be affected by changing the auth service?" + → Human must know: use blast-radius, specify key format, parse output + → AI must know: compose RSS calls, format results, generate follow-ups + ``` + + With CQI: + ``` + Human: "What would be affected by changing the auth service?" + → CQI: intent=impact, blastRadius(depth=3), structured response with files + ``` + + ### 2. Intent Classification Enables Optimization + + Different intents have different optimal strategies: + + | Intent | Optimization | + |--------|-------------| + | `list` | Use tag query if applicable (O(n) scan vs O(1) tag lookup) | + | `impact` | Increase depth, cap nodes | + | `relationship` | Traverse both, compute intersection | + | `describe` | Get context + suggested follow-ups | + + ### 3. Caching Amortizes Graph Load Cost + + Benchmark results: + + | Metric | Value | + |--------|-------| + | Graph load (cold) | ~300-400ms | + | Uncached query | ~2-4ms | + | Cached query | **~0.2-0.3ms** | + + For interactive sessions, caching provides ~10x speedup on repeated patterns. + + ### 4. Suggested Queries Enable Exploration + + CQI generates contextual follow-ups: + + ``` + Query: "Tell me about the auth service" + Suggested: + → What does AuthService depend on? + → What depends on AuthService? + → Impact of changing AuthService + ``` + + This guides both humans and AI agents toward productive exploration. + + --- alternatives_considered: [] consequences: positive: @@ -110,3 +125,8 @@ decisions: - Integrate with Watchdog for automatic cache invalidation related_invariants: [] gaps: [] +migration_origin: + remapped_entities: + - entity_type: decision + from: DEC-0001 + to: DEC-0006 diff --git a/adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml b/adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml new file mode 100644 index 0000000..659bc71 --- /dev/null +++ b/adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml @@ -0,0 +1,59 @@ +schema_version: '1.0' +adr_type: logical +id: ADR-L-0007 +title: Graph Freshness and Obligation Projection Semantics +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- rss +- obligations +- freshness +tags: +- freshness +- obligations +- preflight +- validation +related_adrs: +- ADR-L-0004 +- ADR-L-0006 +supersedes: [] +superseded_by: null +context: | + ste-runtime now exposes graph freshness checks, invalidated validation + signals, change intent handling, and obligation projection behavior through + RSS and MCP tooling. These semantics are broader than implementation detail + and require an explicit logical authority. +decision: | + ste-runtime SHALL treat graph freshness and obligation projection as + first-class logical semantics. Freshness status, invalidated validations, + declared obligations, and derived obligations SHALL be modeled explicitly and + surfaced consistently across preflight checks, obligation projection, and + assistant-facing tool responses. +consequences: + positive: + - Freshness and obligation behavior gains canonical semantics instead of living + only in code. + - MCP and RSS consumers can rely on a consistent semantic contract. + negative: + - Additional physical ADR decomposition is required to align runtime tooling with + this authority. +decisions: +- id: DEC-0007 + summary: Freshness and obligation projection are logical runtime semantics + rationale: | + The current runtime models freshness and obligation data in public schemas + and assistant-facing responses, so these semantics require canonical + documentation above the component layer. +invariants: [] +capabilities: +- id: CAP-0007 + name: Surface graph freshness and obligation projection semantics + description: Provide canonical freshness, invalidation, and obligation semantics + for runtime consumers. +constraints: [] +boundaries: [] +nfrs: [] +contracts: [] +gaps: [] diff --git a/adrs/manifest.yaml b/adrs/manifest.yaml index cb339ea..491555d 100644 --- a/adrs/manifest.yaml +++ b/adrs/manifest.yaml @@ -4,22 +4,22 @@ # generator_id: adr-manifest # generator_version: 1 # hash_algorithm: sha256 -# source_hash: 35089a8f409a9a8caa5a8218027b4a64fd5e7ba930f47c8b62ceb8c96a363a91 -# rendered_hash: 893aeea4594bb2fe538f14239fb3b69400dfffcd41ed8b8cfc7324b8c1c21d0d +# source_hash: 12a5cea6f41ee37445fe692064b753eb8d91d8ce8efbb4931648ed78ad488f82 +# rendered_hash: fd4b31262d4d5401311add5fb1049d7fbc8212447e359dbebcf33ab882db7592 # manifest.yaml - GENERATED FROM ADRs, DO NOT EDIT # This file is automatically generated by 'adr generate-manifest' # To update: modify ADRs, then regenerate manifest schema_version: '1.0' type: manifest -generated_date: '2026-03-12T05:40:10Z' +generated_date: '2026-03-15T15:26:08Z' generated_from: adrs/**/*.yaml adrs: - id: ADR-L-0001 type: logical title: RECON Provisional Execution for Project-Level Semantic State status: accepted - file_path: adrs\logical\ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml + file_path: adrs/logical/ADR-L-0001-recon-provisional-execution-for-project-level-sema.yaml domains: - recon - architecture @@ -40,7 +40,7 @@ adrs: type: logical title: RECON Self-Validation Strategy status: accepted - file_path: adrs\logical\ADR-L-0002-recon-self-validation-strategy.yaml + file_path: adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml domains: - recon - validation @@ -61,7 +61,7 @@ adrs: type: logical title: CEM Implementation Deferral status: accepted - file_path: adrs\logical\ADR-L-0003-cem-implementation-deferral.yaml + file_path: adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml domains: - architecture - governance @@ -82,7 +82,7 @@ adrs: type: logical title: Watchdog Authoritative Mode for Workspace Boundary status: accepted - file_path: adrs\logical\ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml + file_path: adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml domains: - watchdog - governance @@ -103,7 +103,7 @@ adrs: type: logical title: Self-Configuring Domain Discovery status: proposed - file_path: adrs\logical\ADR-L-0005-self-configuring-domain-discovery.yaml + file_path: adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml domains: - recon - domain-discovery @@ -123,7 +123,7 @@ adrs: type: logical title: Conversational Query Interface for RSS status: proposed - file_path: adrs\logical\ADR-L-0006-conversational-query-interface-for-rss.yaml + file_path: adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml domains: - rss - interface @@ -140,11 +140,32 @@ adrs: gap_count: 0 blocking_gaps: 0 component_count: 0 +- id: ADR-L-0007 + type: logical + title: Graph Freshness and Obligation Projection Semantics + status: proposed + file_path: adrs/logical/ADR-L-0007-graph-freshness-and-obligation-projection-semantics.yaml + domains: + - rss + - obligations + - freshness + tags: + - freshness + - obligations + - preflight + - validation + implements_logical: [] + technologies: [] + decision_count: 1 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 0 - id: ADR-P-0001 type: physical title: RSS CLI Implementation for Developer-Invoked Graph Traversal status: accepted - file_path: adrs\physical\ADR-P-0001-rss-cli-implementation-for-developer-invoked-graph.yaml + file_path: adrs/physical/ADR-P-0001-rss-cli-implementation-for-developer-invoked-graph.yaml domains: - rss - cli @@ -175,8 +196,8 @@ adrs: - id: ADR-P-0002 type: physical title: JSON Data Extraction for Compliance Controls and Schemas - status: proposed - file_path: adrs\physical\ADR-P-0002-json-data-extraction-for-compliance-controls-and-s.yaml + status: superseded + file_path: adrs/physical/ADR-P-0002-json-data-extraction-for-compliance-controls-and-s.yaml domains: - extraction - data @@ -208,8 +229,8 @@ adrs: - id: ADR-P-0003 type: physical title: Angular and CSS/SCSS Semantic Extraction - status: proposed - file_path: adrs\physical\ADR-P-0003-angular-and-cssscss-semantic-extraction.yaml + status: superseded + file_path: adrs/physical/ADR-P-0003-angular-and-cssscss-semantic-extraction.yaml domains: - extraction - frontend @@ -244,8 +265,8 @@ adrs: - id: ADR-P-0004 type: physical title: ste-runtime MCP Server Implementation - status: accepted - file_path: adrs\physical\ADR-P-0004-ste-runtime-mcp-server-implementation.yaml + status: superseded + file_path: adrs/physical/ADR-P-0004-ste-runtime-mcp-server-implementation.yaml domains: - mcp - integration @@ -279,7 +300,7 @@ adrs: type: physical title: Extractor Validation Requirements status: accepted - file_path: adrs\physical\ADR-P-0005-extractor-validation-requirements.yaml + file_path: adrs/physical/ADR-P-0005-extractor-validation-requirements.yaml domains: - validation - extraction @@ -306,11 +327,227 @@ adrs: gap_count: 0 blocking_gaps: 0 component_count: 1 +- id: ADR-PS-0001 + type: physical-system + title: Runtime Orchestration and Assistant Integration + status: proposed + file_path: adrs/physical-system/ADR-PS-0001-runtime-orchestration-and-assistant-integration.yaml + domains: + - runtime + - mcp + - rss + - watch + tags: + - runtime + - mcp + - watchdog + - obligations + implements_logical: + - ADR-L-0004 + - ADR-L-0006 + - ADR-L-0007 + technologies: + - typescript + - node.js + - mcp + - chokidar + - zod + decision_count: 0 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 0 +- id: ADR-PS-0002 + type: physical-system + title: Semantic Extraction Subsystem + status: proposed + file_path: adrs/physical-system/ADR-PS-0002-semantic-extraction-subsystem.yaml + domains: + - extraction + - recon + - normalization + tags: + - extraction + - recon + - semantic-state + implements_logical: + - ADR-L-0001 + - ADR-L-0005 + technologies: + - typescript + - node.js + - json + - angular + - css + - cloudformation + decision_count: 0 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 0 +- id: ADR-PC-0001 + type: physical-component + title: MCP Server and Tool Registry + status: proposed + file_path: adrs/physical-component/ADR-PC-0001-mcp-server-and-tool-registry.yaml + domains: + - mcp + - integration + - runtime + tags: [] + implements_logical: + - ADR-L-0004 + - ADR-L-0006 + - ADR-L-0007 + technologies: + - typescript + - node.js + - mcp + - zod + decision_count: 0 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 1 +- id: ADR-PC-0002 + type: physical-component + title: Watchdog and Update Coordination + status: proposed + file_path: adrs/physical-component/ADR-PC-0002-watchdog-and-update-coordination.yaml + domains: + - watch + - runtime + - reconciliation + tags: [] + implements_logical: + - ADR-L-0004 + technologies: + - typescript + - node.js + - chokidar + decision_count: 0 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 1 +- id: ADR-PC-0003 + type: physical-component + title: Preflight Freshness and Reconciliation Gating + status: proposed + file_path: adrs/physical-component/ADR-PC-0003-preflight-freshness-and-reconciliation-gating.yaml + domains: + - preflight + - freshness + - reconciliation + tags: [] + implements_logical: + - ADR-L-0004 + - ADR-L-0007 + technologies: + - typescript + - node.js + - zod + decision_count: 0 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 1 +- id: ADR-PC-0004 + type: physical-component + title: Obligation Projection and Context Assembly + status: proposed + file_path: adrs/physical-component/ADR-PC-0004-obligation-projection-and-context-assembly.yaml + domains: + - obligations + - context + - rss + tags: [] + implements_logical: + - ADR-L-0006 + - ADR-L-0007 + technologies: + - typescript + - node.js + - zod + decision_count: 0 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 1 +- id: ADR-PC-0005 + type: physical-component + title: JSON Semantic Extraction + status: proposed + file_path: adrs/physical-component/ADR-PC-0005-json-semantic-extraction.yaml + domains: + - extraction + - json + - recon + tags: [] + implements_logical: + - ADR-L-0001 + technologies: + - typescript + - json + - node.js + decision_count: 0 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 1 +- id: ADR-PC-0006 + type: physical-component + title: Frontend Semantic Extraction + status: proposed + file_path: adrs/physical-component/ADR-PC-0006-frontend-semantic-extraction.yaml + domains: + - extraction + - frontend + - recon + tags: [] + implements_logical: + - ADR-L-0001 + technologies: + - typescript + - angular + - css + - scss + decision_count: 0 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 1 +- id: ADR-PC-0007 + type: physical-component + title: CloudFormation Semantic Extraction + status: proposed + file_path: adrs/physical-component/ADR-PC-0007-cloudformation-semantic-extraction.yaml + domains: + - extraction + - cloudformation + - recon + tags: [] + implements_logical: + - ADR-L-0001 + technologies: + - typescript + - cloudformation + - yaml + - json + decision_count: 0 + invariant_count: 0 + gap_count: 0 + blocking_gaps: 0 + component_count: 1 by_domain: recon: - ADR-L-0001 - ADR-L-0002 - ADR-L-0005 + - ADR-PS-0002 + - ADR-PC-0005 + - ADR-PC-0006 + - ADR-PC-0007 architecture: - ADR-L-0001 - ADR-L-0003 @@ -334,9 +571,18 @@ by_domain: - ADR-L-0005 rss: - ADR-L-0006 + - ADR-L-0007 - ADR-P-0001 + - ADR-PS-0001 + - ADR-PC-0004 interface: - ADR-L-0006 + obligations: + - ADR-L-0007 + - ADR-PC-0004 + freshness: + - ADR-L-0007 + - ADR-PC-0003 cli: - ADR-P-0001 implementation: @@ -349,14 +595,42 @@ by_domain: - ADR-P-0002 - ADR-P-0003 - ADR-P-0005 + - ADR-PS-0002 + - ADR-PC-0005 + - ADR-PC-0006 + - ADR-PC-0007 data: - ADR-P-0002 frontend: - ADR-P-0003 + - ADR-PC-0006 mcp: - ADR-P-0004 + - ADR-PS-0001 + - ADR-PC-0001 integration: - ADR-P-0004 + - ADR-PC-0001 + runtime: + - ADR-PS-0001 + - ADR-PC-0001 + - ADR-PC-0002 + watch: + - ADR-PS-0001 + - ADR-PC-0002 + normalization: + - ADR-PS-0002 + reconciliation: + - ADR-PC-0002 + - ADR-PC-0003 + preflight: + - ADR-PC-0003 + context: + - ADR-PC-0004 + json: + - ADR-PC-0005 + cloudformation: + - ADR-PC-0007 by_status: accepted: - ADR-L-0001 @@ -364,13 +638,24 @@ by_status: - ADR-L-0003 - ADR-L-0004 - ADR-P-0001 - - ADR-P-0004 - ADR-P-0005 proposed: - ADR-L-0005 - ADR-L-0006 + - ADR-L-0007 + - ADR-PS-0001 + - ADR-PS-0002 + - ADR-PC-0001 + - ADR-PC-0002 + - ADR-PC-0003 + - ADR-PC-0004 + - ADR-PC-0005 + - ADR-PC-0006 + - ADR-PC-0007 + superseded: - ADR-P-0002 - ADR-P-0003 + - ADR-P-0004 by_technology: cli: - ADR-P-0001 @@ -398,12 +683,21 @@ by_technology: - ADR-P-0003 - ADR-P-0004 - ADR-P-0005 + - ADR-PS-0001 + - ADR-PC-0001 node.js: - ADR-P-0001 - ADR-P-0002 - ADR-P-0003 - ADR-P-0004 - ADR-P-0005 + - ADR-PS-0001 + - ADR-PS-0002 + - ADR-PC-0001 + - ADR-PC-0002 + - ADR-PC-0003 + - ADR-PC-0004 + - ADR-PC-0005 schema-validation: - ADR-P-0001 - ADR-P-0002 @@ -422,30 +716,59 @@ by_technology: - ADR-P-0003 - ADR-P-0004 - ADR-P-0005 + - ADR-PS-0001 + - ADR-PS-0002 + - ADR-PC-0001 + - ADR-PC-0002 + - ADR-PC-0003 + - ADR-PC-0004 + - ADR-PC-0005 + - ADR-PC-0006 + - ADR-PC-0007 yaml: - ADR-P-0001 - ADR-P-0002 - ADR-P-0003 - ADR-P-0004 - ADR-P-0005 + - ADR-PC-0007 data-extraction: - ADR-P-0002 json: - ADR-P-0002 + - ADR-PS-0002 + - ADR-PC-0005 + - ADR-PC-0007 angular: - ADR-P-0003 + - ADR-PS-0002 + - ADR-PC-0006 ast-parsing: - ADR-P-0003 css: - ADR-P-0003 + - ADR-PS-0002 + - ADR-PC-0006 scss: - ADR-P-0003 + - ADR-PC-0006 incremental-recon: - ADR-P-0004 stdio: - ADR-P-0004 validation: - ADR-P-0005 + chokidar: + - ADR-PS-0001 + - ADR-PC-0002 + zod: + - ADR-PS-0001 + - ADR-PC-0001 + - ADR-PC-0003 + - ADR-PC-0004 + cloudformation: + - ADR-PS-0002 + - ADR-PC-0007 logical_to_physical_map: ADR-L-0002: - ADR-P-0001 @@ -453,11 +776,38 @@ logical_to_physical_map: ADR-L-0001: - ADR-P-0002 - ADR-P-0003 + - ADR-PS-0002 + - ADR-PC-0005 + - ADR-PC-0006 + - ADR-PC-0007 ADR-L-0004: - ADR-P-0004 + - ADR-PS-0001 + - ADR-PC-0001 + - ADR-PC-0002 + - ADR-PC-0003 ADR-L-0006: - ADR-P-0004 -system_to_components_map: {} + - ADR-PS-0001 + - ADR-PC-0001 + - ADR-PC-0004 + ADR-L-0007: + - ADR-PS-0001 + - ADR-PC-0001 + - ADR-PC-0003 + - ADR-PC-0004 + ADR-L-0005: + - ADR-PS-0002 +system_to_components_map: + ADR-PS-0001: + - ADR-PC-0001 + - ADR-PC-0002 + - ADR-PC-0003 + - ADR-PC-0004 + ADR-PS-0002: + - ADR-PC-0005 + - ADR-PC-0006 + - ADR-PC-0007 invariants: - id: INV-0001 statement: 'Single repository only: RECON discovers files within the current repository. @@ -543,6 +893,41 @@ entities: correctness. introduced_by: ADR-L-0001 lifecycle_stage: accepted +- entity_id: DEC-0002 + entity_type: decision + name: RECON self-validation is non-blocking, report-only, and exploratory. + introduced_by: ADR-L-0002 + lifecycle_stage: accepted +- entity_id: DEC-0003 + entity_type: decision + name: CEM implementation is intentionally deferred. + introduced_by: ADR-L-0003 + lifecycle_stage: accepted +- entity_id: DEC-0004 + entity_type: decision + name: 'ste-runtime is a single process that combines:' + introduced_by: ADR-L-0004 + lifecycle_stage: accepted +- entity_id: DEC-0005 + entity_type: decision + name: '' + introduced_by: ADR-L-0005 + lifecycle_stage: proposed +- entity_id: DEC-0006 + entity_type: decision + name: 'Implement a Conversational Query Interface (CQI) as a layer above RSS that:' + introduced_by: ADR-L-0006 + lifecycle_stage: proposed +- entity_id: CAP-0007 + entity_type: capability + name: Surface graph freshness and obligation projection semantics + introduced_by: ADR-L-0007 + lifecycle_stage: proposed +- entity_id: DEC-0007 + entity_type: decision + name: Freshness and obligation projection are logical runtime semantics + introduced_by: ADR-L-0007 + lifecycle_stage: proposed - entity_id: COMP-0001 entity_type: component name: RSS CLI @@ -552,7 +937,7 @@ entities: entity_type: component name: CSS/SCSS Extractor introduced_by: ADR-P-0003 - lifecycle_stage: proposed + lifecycle_stage: superseded requirements_snapshots: [] decision_ledgers: [] gaps_summary: @@ -563,17 +948,17 @@ gaps_summary: total: 2 blocking: 0 statistics: - total_adrs: 11 - logical_adrs: 6 - physical_adrs: 5 - physical_system_adrs: 0 - physical_component_adrs: 0 + total_adrs: 21 + logical_adrs: 7 + physical_adrs: 14 + physical_system_adrs: 2 + physical_component_adrs: 7 decision_adrs: 0 - total_decisions: 6 + total_decisions: 7 total_invariants: 13 - total_components: 7 + total_components: 14 total_gaps: 2 blocking_gaps: 0 - total_entities: 3 + total_entities: 10 total_requirements_snapshots: 0 total_decision_ledgers: 0 diff --git a/adrs/migrations/canonical-id-remap.yaml b/adrs/migrations/canonical-id-remap.yaml new file mode 100644 index 0000000..b0283f2 --- /dev/null +++ b/adrs/migrations/canonical-id-remap.yaml @@ -0,0 +1,28 @@ +schema_version: '1.0' +type: canonical_id_remap +entries: +- entity_type: decision + adr_id: ADR-L-0002 + file_path: adrs/logical/ADR-L-0002-recon-self-validation-strategy.yaml + from: DEC-0001 + to: DEC-0002 +- entity_type: decision + adr_id: ADR-L-0003 + file_path: adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml + from: DEC-0001 + to: DEC-0003 +- entity_type: decision + adr_id: ADR-L-0004 + file_path: adrs/logical/ADR-L-0004-watchdog-authoritative-mode-for-workspace-boundary.yaml + from: DEC-0001 + to: DEC-0004 +- entity_type: decision + adr_id: ADR-L-0005 + file_path: adrs/logical/ADR-L-0005-self-configuring-domain-discovery.yaml + from: DEC-0001 + to: DEC-0005 +- entity_type: decision + adr_id: ADR-L-0006 + file_path: adrs/logical/ADR-L-0006-conversational-query-interface-for-rss.yaml + from: DEC-0001 + to: DEC-0006 diff --git a/adrs/physical-component/ADR-PC-0001-mcp-server-and-tool-registry.yaml b/adrs/physical-component/ADR-PC-0001-mcp-server-and-tool-registry.yaml new file mode 100644 index 0000000..02a6d31 --- /dev/null +++ b/adrs/physical-component/ADR-PC-0001-mcp-server-and-tool-registry.yaml @@ -0,0 +1,84 @@ +schema_version: '1.0' +adr_type: physical-component +id: ADR-PC-0001 +title: MCP Server and Tool Registry +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- mcp +- integration +- runtime +implements_system: +- ADR-PS-0001 +implements_logical: +- ADR-L-0004 +- ADR-L-0006 +- ADR-L-0007 +technologies: +- typescript +- node.js +- mcp +- zod +context: | + This component exposes assistant-facing runtime tools over MCP and binds + structural, operational, context, optimized, and obligation-oriented tool + surfaces into one discoverable server boundary. +technology_stack: +- category: language + name: TypeScript + version: 5.3+ + rationale: Existing implementation language. +- category: library + name: '@modelcontextprotocol/sdk' + version: 1.x + rationale: MCP protocol implementation. +component_specifications: +- id: COMP-0001 + name: MCP Server and Tool Registry + type: service + responsibilities: | + - Serve MCP stdio runtime for assistant integration + - Register structural, operational, context, optimized, and obligation tools + - Route tool requests onto runtime graph and context services + generation_context: + purpose: Expose runtime semantic capabilities to assistants through MCP. + key_responsibilities: + - Register tools deterministically + - Provide assistant-facing tool responses + constraints: + - Tool behavior must remain freshness-aware + - Assistant-facing responses must use canonical runtime semantics + success_criteria: + - MCP server advertises the implemented tool surfaces + - Tool responses remain aligned with runtime freshness and obligation logic + interfaces: + - id: IFACE-0001 + type: CLI + specification: | + Entry surfaces: + - src/mcp/mcp-server.ts + - MCP stdio tool registration for structural, operational, context, optimized, and obligation tools + implementation_identifiers: + module_path: src/mcp/mcp-server.ts + entry_point: src/mcp/mcp-server.ts + test_path: src/mcp/mcp-server.test.ts + implementation_requirements: + error_handling: + strategy: Return explicit tool failures for invalid input, missing graph state, + or runtime errors. + observability: + logging: + level: info + structured: false + metrics: + - name: mcp_tool_invocations_total + type: counter + testing_requirements: + unit_test_coverage: '>= 80%' + integration_tests: | + - MCP server startup + - Tool registration and execution +implementation_decisions: [] +gaps: [] diff --git a/adrs/physical-component/ADR-PC-0002-watchdog-and-update-coordination.yaml b/adrs/physical-component/ADR-PC-0002-watchdog-and-update-coordination.yaml new file mode 100644 index 0000000..6ab356c --- /dev/null +++ b/adrs/physical-component/ADR-PC-0002-watchdog-and-update-coordination.yaml @@ -0,0 +1,82 @@ +schema_version: '1.0' +adr_type: physical-component +id: ADR-PC-0002 +title: Watchdog and Update Coordination +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- watch +- runtime +- reconciliation +implements_system: +- ADR-PS-0001 +implements_logical: +- ADR-L-0004 +technologies: +- typescript +- node.js +- chokidar +context: | + This component monitors changes, detects transactions, coordinates update + batches, and safeguards write-triggered reconciliation behavior for the + runtime boundary. +technology_stack: +- category: language + name: TypeScript + version: 5.3+ + rationale: Existing implementation language. +- category: library + name: chokidar + version: 3.x + rationale: File watching implementation. +component_specifications: +- id: COMP-0002 + name: Watchdog and Update Coordination + type: worker + responsibilities: | + - Watch source and state changes + - Detect coherent edit transactions + - Coordinate update batches and reconciliation triggers + - Protect runtime behavior from unsafe write loops + generation_context: + purpose: Keep runtime graph state current without unsafe write churn. + key_responsibilities: + - File watching + - Transaction detection + - Update coordination + constraints: + - Runtime updates must avoid self-triggered reconciliation loops + success_criteria: + - File changes are batched and coordinated safely + interfaces: + - id: IFACE-0002 + type: library_api + specification: | + Public surfaces: + - Watchdog + - UpdateCoordinator + - TransactionDetector + - WriteTracker + implementation_identifiers: + module_path: src/watch/watchdog.ts + test_path: src/watch/file-watcher.test.ts + implementation_requirements: + error_handling: + strategy: Degrade safely and suppress unsafe re-entrant update behavior. + observability: + logging: + level: info + structured: false + metrics: + - name: watchdog_events_total + type: counter + testing_requirements: + unit_test_coverage: '>= 80%' + integration_tests: | + - File watcher change handling + - Transaction detection + - Safeguard behavior +implementation_decisions: [] +gaps: [] diff --git a/adrs/physical-component/ADR-PC-0003-preflight-freshness-and-reconciliation-gating.yaml b/adrs/physical-component/ADR-PC-0003-preflight-freshness-and-reconciliation-gating.yaml new file mode 100644 index 0000000..5b91ca4 --- /dev/null +++ b/adrs/physical-component/ADR-PC-0003-preflight-freshness-and-reconciliation-gating.yaml @@ -0,0 +1,77 @@ +schema_version: '1.0' +adr_type: physical-component +id: ADR-PC-0003 +title: Preflight Freshness and Reconciliation Gating +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- preflight +- freshness +- reconciliation +implements_system: +- ADR-PS-0001 +implements_logical: +- ADR-L-0004 +- ADR-L-0007 +technologies: +- typescript +- node.js +- zod +context: | + This component evaluates file freshness, intent scope, and reconciliation + requirements before runtime actions rely on semantic graph state. +technology_stack: +- category: language + name: TypeScript + version: 5.3+ + rationale: Existing implementation language. +component_specifications: +- id: COMP-0003 + name: Preflight Freshness and Reconciliation Gate + type: service + responsibilities: | + - Resolve intent scope + - Evaluate graph freshness + - Determine whether reconciliation is required + - Surface freshness status for downstream tools + generation_context: + purpose: Prevent stale runtime state from driving assistant or operator behavior. + key_responsibilities: + - Freshness checks + - Reconciliation gating + constraints: + - Freshness semantics must align with ADR-L-0007 + success_criteria: + - Preflight results consistently reflect runtime freshness state + interfaces: + - id: IFACE-0003 + type: library_api + specification: | + Public surfaces: + - preflightReconciliation + - checkFreshness + - resolveIntentScope + implementation_identifiers: + module_path: src/mcp/preflight.ts + test_path: src/mcp/preflight.test.ts + implementation_requirements: + error_handling: + strategy: Return explicit unknown or stale freshness states rather than silently + assuming freshness. + observability: + logging: + level: info + structured: false + metrics: + - name: preflight_checks_total + type: counter + testing_requirements: + unit_test_coverage: '>= 80%' + integration_tests: | + - Scope resolution + - Freshness status checks + - Reconciliation gate outcomes +implementation_decisions: [] +gaps: [] diff --git a/adrs/physical-component/ADR-PC-0004-obligation-projection-and-context-assembly.yaml b/adrs/physical-component/ADR-PC-0004-obligation-projection-and-context-assembly.yaml new file mode 100644 index 0000000..dd17087 --- /dev/null +++ b/adrs/physical-component/ADR-PC-0004-obligation-projection-and-context-assembly.yaml @@ -0,0 +1,79 @@ +schema_version: '1.0' +adr_type: physical-component +id: ADR-PC-0004 +title: Obligation Projection and Context Assembly +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- obligations +- context +- rss +implements_system: +- ADR-PS-0001 +implements_logical: +- ADR-L-0006 +- ADR-L-0007 +technologies: +- typescript +- node.js +- zod +context: | + This component projects invalidated validations and change-driven obligations, + assembles implementation context, and loads source-backed evidence for + assistant-facing reasoning. +technology_stack: +- category: language + name: TypeScript + version: 5.3+ + rationale: Existing implementation language. +component_specifications: +- id: COMP-0004 + name: Obligation Projection and Context Assembly + type: service + responsibilities: | + - Project obligations from change intent and graph state + - Surface invalidated validations and advisories + - Load source-backed implementation context + - Format runtime context for assistant consumption + generation_context: + purpose: Build freshness-aware implementation context and obligation guidance. + key_responsibilities: + - Obligation projection + - Context assembly + constraints: + - Responses must stay aligned with runtime freshness semantics + success_criteria: + - Obligation and context tools produce source-backed, deterministic responses + interfaces: + - id: IFACE-0004 + type: library_api + specification: | + Public surfaces: + - projectObligations + - assembleContextTool + - getImplementationContext + - loadSourceGroupedByFile + implementation_identifiers: + module_path: src/mcp/obligation-projector.ts + test_path: src/mcp/tools-obligation.test.ts + implementation_requirements: + error_handling: + strategy: Return explicit advisories and empty safe defaults when source or + graph evidence is missing. + observability: + logging: + level: info + structured: false + metrics: + - name: obligation_projections_total + type: counter + testing_requirements: + unit_test_coverage: '>= 80%' + integration_tests: | + - Obligation projection flows + - Context assembly flows + - Source loading and formatting +implementation_decisions: [] +gaps: [] diff --git a/adrs/physical-component/ADR-PC-0005-json-semantic-extraction.yaml b/adrs/physical-component/ADR-PC-0005-json-semantic-extraction.yaml new file mode 100644 index 0000000..1e49661 --- /dev/null +++ b/adrs/physical-component/ADR-PC-0005-json-semantic-extraction.yaml @@ -0,0 +1,76 @@ +schema_version: '1.0' +adr_type: physical-component +id: ADR-PC-0005 +title: JSON Semantic Extraction +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- extraction +- json +- recon +implements_system: +- ADR-PS-0002 +implements_logical: +- ADR-L-0001 +related_adrs: +- ADR-P-0002 +supersedes: +- ADR-P-0002 +technologies: +- typescript +- json +- node.js +context: | + JSON semantic extraction captures controls, schemas, and configuration + semantics from JSON sources and feeds them into RECON normalization. +technology_stack: +- category: language + name: TypeScript + version: 5.3+ + rationale: Existing implementation language. +component_specifications: +- id: COMP-0005 + name: JSON Semantic Extractor + type: library + responsibilities: | + - Detect semantically relevant JSON files + - Extract controls, schemas, and configuration semantics + - Provide RECON-ready assertions for normalization + generation_context: + purpose: Extract semantic data from JSON artifacts for RECON. + key_responsibilities: + - JSON semantic discovery + - JSON assertion extraction + constraints: + - Extraction remains deterministic and path-driven + success_criteria: + - JSON semantic artifacts are represented in RECON output + interfaces: + - id: IFACE-0005 + type: library_api + specification: | + Public surfaces: + - src/extractors/json/index.ts + - src/extractors/json/json-extractor.ts + implementation_identifiers: + module_path: src/extractors/json/json-extractor.ts + test_path: src/extractors/json/json-extractor.test.ts + implementation_requirements: + error_handling: + strategy: Ignore unsupported JSON while surfacing deterministic extraction failures. + observability: + logging: + level: info + structured: false + metrics: + - name: json_extractions_total + type: counter + testing_requirements: + unit_test_coverage: '>= 80%' + integration_tests: | + - JSON semantic extraction + - JSON validation extraction coverage +implementation_decisions: [] +gaps: [] diff --git a/adrs/physical-component/ADR-PC-0006-frontend-semantic-extraction.yaml b/adrs/physical-component/ADR-PC-0006-frontend-semantic-extraction.yaml new file mode 100644 index 0000000..86e358a --- /dev/null +++ b/adrs/physical-component/ADR-PC-0006-frontend-semantic-extraction.yaml @@ -0,0 +1,78 @@ +schema_version: '1.0' +adr_type: physical-component +id: ADR-PC-0006 +title: Frontend Semantic Extraction +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- extraction +- frontend +- recon +implements_system: +- ADR-PS-0002 +implements_logical: +- ADR-L-0001 +related_adrs: +- ADR-P-0003 +supersedes: +- ADR-P-0003 +technologies: +- typescript +- angular +- css +- scss +context: | + Frontend semantic extraction captures Angular and CSS/SCSS-specific semantics + beyond generic TypeScript structure and feeds them into RECON normalization. +technology_stack: +- category: language + name: TypeScript + version: 5.3+ + rationale: Existing implementation language. +component_specifications: +- id: COMP-0006 + name: Frontend Semantic Extractor + type: library + responsibilities: | + - Extract Angular component, service, route, and template semantics + - Extract CSS/SCSS tokens, styles, and related frontend semantics + - Provide frontend assertions for RECON normalization + generation_context: + purpose: Extract frontend-specific semantic information for RECON. + key_responsibilities: + - Angular semantic extraction + - CSS/SCSS semantic extraction + constraints: + - Extraction must remain deterministic and source-driven + success_criteria: + - Frontend-specific semantics appear in RECON output + interfaces: + - id: IFACE-0006 + type: library_api + specification: | + Public surfaces: + - src/extractors/angular/angular-extractor.ts + - src/extractors/css/css-extractor.ts + implementation_identifiers: + module_path: src/extractors/angular/angular-extractor.ts + test_path: src/extractors/angular/angular-extractor.test.ts + implementation_requirements: + error_handling: + strategy: Ignore unsupported frontend patterns while surfacing deterministic + extraction failures. + observability: + logging: + level: info + structured: false + metrics: + - name: frontend_extractions_total + type: counter + testing_requirements: + unit_test_coverage: '>= 80%' + integration_tests: | + - Angular semantic extraction + - CSS/SCSS semantic extraction +implementation_decisions: [] +gaps: [] diff --git a/adrs/physical-component/ADR-PC-0007-cloudformation-semantic-extraction.yaml b/adrs/physical-component/ADR-PC-0007-cloudformation-semantic-extraction.yaml new file mode 100644 index 0000000..8fd4a55 --- /dev/null +++ b/adrs/physical-component/ADR-PC-0007-cloudformation-semantic-extraction.yaml @@ -0,0 +1,75 @@ +schema_version: '1.0' +adr_type: physical-component +id: ADR-PC-0007 +title: CloudFormation Semantic Extraction +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- extraction +- cloudformation +- recon +implements_system: +- ADR-PS-0002 +implements_logical: +- ADR-L-0001 +technologies: +- typescript +- cloudformation +- yaml +- json +context: | + CloudFormation semantic extraction captures templates, resources, outputs, + parameters, infrastructure relationships, and template-level implementation + intent from CloudFormation sources. +technology_stack: +- category: language + name: TypeScript + version: 5.3+ + rationale: Existing implementation language. +component_specifications: +- id: COMP-0007 + name: CloudFormation Semantic Extractor + type: library + responsibilities: | + - Extract template, parameter, resource, and output semantics + - Derive infrastructure relationships and API/data model evidence + - Preserve template-level implementation intent metadata + generation_context: + purpose: Extract CloudFormation semantics for RECON. + key_responsibilities: + - CloudFormation template extraction + - Infrastructure relationship extraction + constraints: + - Extraction must remain deterministic and metadata-preserving + success_criteria: + - CloudFormation resources and relationships appear in RECON output + interfaces: + - id: IFACE-0007 + type: library_api + specification: | + Public surfaces: + - src/recon/phases/extraction-cloudformation.ts + - src/extractors/cfn/* + implementation_identifiers: + module_path: src/recon/phases/extraction-cloudformation.ts + test_path: src/recon/phases/extraction-cloudformation.test.ts + implementation_requirements: + error_handling: + strategy: Continue extracting valid template sections while surfacing deterministic + parsing failures. + observability: + logging: + level: info + structured: false + metrics: + - name: cfn_extractions_total + type: counter + testing_requirements: + unit_test_coverage: '>= 80%' + integration_tests: | + - CloudFormation extraction + - CloudFormation validation extraction coverage +implementation_decisions: [] +gaps: [] diff --git a/adrs/physical-system/ADR-PS-0001-runtime-orchestration-and-assistant-integration.yaml b/adrs/physical-system/ADR-PS-0001-runtime-orchestration-and-assistant-integration.yaml new file mode 100644 index 0000000..bb17a82 --- /dev/null +++ b/adrs/physical-system/ADR-PS-0001-runtime-orchestration-and-assistant-integration.yaml @@ -0,0 +1,113 @@ +schema_version: '1.0' +adr_type: physical-system +id: ADR-PS-0001 +title: Runtime Orchestration and Assistant Integration +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- runtime +- mcp +- rss +- watch +tags: +- runtime +- mcp +- watchdog +- obligations +implements_logical: +- ADR-L-0004 +- ADR-L-0006 +- ADR-L-0007 +references_components: +- ADR-PC-0001 +- ADR-PC-0002 +- ADR-PC-0003 +- ADR-PC-0004 +related_adrs: +- ADR-P-0004 +supersedes: +- ADR-P-0004 +technologies: +- typescript +- node.js +- mcp +- chokidar +- zod +context: | + ste-runtime now contains a runtime orchestration boundary that keeps semantic + state fresh, exposes assistant-facing MCP tools, performs reconciliation + gating and freshness checks, and assembles implementation context and + obligation projections for agents and operators. +technology_stack: +- category: language + name: TypeScript + version: 5.3+ + rationale: Existing runtime implementation language. +- category: framework + name: Node.js + version: 18.x+ + rationale: Existing runtime execution environment. +- category: library + name: '@modelcontextprotocol/sdk' + version: 1.x + rationale: MCP protocol implementation. +- category: library + name: chokidar + version: 3.x + rationale: Cross-platform file watching. +system_boundaries: +- id: SYSBOUND-0001 + name: Runtime Orchestration Boundary + description: | + Encapsulates assistant-facing runtime operations over fresh semantic graph + state, including MCP tools, update coordination, preflight freshness, and + obligation/context assembly. + external_dependencies: + - RECON semantic state under `.ste/state` + - Canonical project sources + exposed_interfaces: + - MCP stdio server + - RSS query operations + - watchdog-triggered reconciliation +component_topology: + components: + - name: MCP Server and Tool Registry + type: service + purpose: Expose assistant-facing tools over the semantic graph. + implements_adr: ADR-PC-0001 + - name: Watchdog and Update Coordination + type: worker + purpose: Detect changes and coordinate safe runtime updates. + implements_adr: ADR-PC-0002 + - name: Preflight Freshness and Reconciliation Gate + type: service + purpose: Evaluate freshness and decide when reconciliation is required. + implements_adr: ADR-PC-0003 + - name: Obligation Projection and Context Assembly + type: service + purpose: Project obligations and build source-backed implementation context. + implements_adr: ADR-PC-0004 + relationships: + - from: Watchdog and Update Coordination + to: Preflight Freshness and Reconciliation Gate + type: depends_on + description: Runtime updates require freshness and reconciliation decisions. + - from: Preflight Freshness and Reconciliation Gate + to: Obligation Projection and Context Assembly + type: depends_on + description: Obligation and context responses rely on current freshness state. + - from: MCP Server and Tool Registry + to: Preflight Freshness and Reconciliation Gate + type: depends_on + description: MCP operations invoke freshness-aware behavior. + - from: MCP Server and Tool Registry + to: Obligation Projection and Context Assembly + type: depends_on + description: Assistant-facing tools expose context and obligation projections. +operational_requirements: + monitoring: Track freshness status, invalidated validations, and runtime health + metrics. + logging: Structured runtime logs for reconciliation and tool invocation flows. +gaps: [] diff --git a/adrs/physical-system/ADR-PS-0002-semantic-extraction-subsystem.yaml b/adrs/physical-system/ADR-PS-0002-semantic-extraction-subsystem.yaml new file mode 100644 index 0000000..b29a811 --- /dev/null +++ b/adrs/physical-system/ADR-PS-0002-semantic-extraction-subsystem.yaml @@ -0,0 +1,83 @@ +schema_version: '1.0' +adr_type: physical-system +id: ADR-PS-0002 +title: Semantic Extraction Subsystem +status: proposed +created_date: '2026-03-15' +authors: +- ste-runtime +domains: +- extraction +- recon +- normalization +tags: +- extraction +- recon +- semantic-state +implements_logical: +- ADR-L-0001 +- ADR-L-0005 +references_components: +- ADR-PC-0005 +- ADR-PC-0006 +- ADR-PC-0007 +related_adrs: +- ADR-P-0002 +- ADR-P-0003 +technologies: +- typescript +- node.js +- json +- angular +- css +- cloudformation +context: | + ste-runtime extraction is now a subsystem containing multiple first-class + extractors and normalization flows rather than a pair of isolated physical + slices. This ADR groups the implemented extractor estate under a concrete + system boundary. +technology_stack: +- category: language + name: TypeScript + version: 5.3+ + rationale: Existing implementation language. +- category: framework + name: Node.js + version: 18.x+ + rationale: Existing execution environment. +system_boundaries: +- id: SYSBOUND-0002 + name: Semantic Extraction Boundary + description: | + Encapsulates domain-specific extraction of semantic assertions and related + normalization inputs for RECON. + external_dependencies: + - Source files discovered by RECON + - CloudFormation resource specifications + exposed_interfaces: + - extractor modules invoked by RECON phases +component_topology: + components: + - name: JSON Semantic Extractor + type: service + purpose: Extract semantic entities from JSON control, schema, and config files. + implements_adr: ADR-PC-0005 + - name: Frontend Semantic Extractor + type: service + purpose: Extract Angular and CSS/SCSS semantics. + implements_adr: ADR-PC-0006 + - name: CloudFormation Semantic Extractor + type: service + purpose: Extract CloudFormation resources, relations, and implementation intent. + implements_adr: ADR-PC-0007 + relationships: + - from: JSON Semantic Extractor + to: Frontend Semantic Extractor + type: depends_on + description: Shared normalization and discovery patterns remain aligned across + extractor types. + - from: Frontend Semantic Extractor + to: CloudFormation Semantic Extractor + type: depends_on + description: All extractor outputs feed the same RECON normalization pipeline. +gaps: [] diff --git a/adrs/physical/ADR-P-0001-rss-cli-implementation-for-developer-invoked-graph.yaml b/adrs/physical/ADR-P-0001-rss-cli-implementation-for-developer-invoked-graph.yaml index af76473..9667c1d 100644 --- a/adrs/physical/ADR-P-0001-rss-cli-implementation-for-developer-invoked-graph.yaml +++ b/adrs/physical/ADR-P-0001-rss-cli-implementation-for-developer-invoked-graph.yaml @@ -33,33 +33,21 @@ technologies: - testing - typescript - yaml -context: 'The STE Architecture Specification Section 4.6 defines RSS (Runtime State-Slicing) - as the component responsible for graph traversal and context assembly from AI-DOC - state. RSS provides six core operations: - +context: |- + The STE Architecture Specification Section 4.6 defines RSS (Runtime State-Slicing) as the component responsible for graph traversal and context assembly from AI-DOC state. RSS provides six core operations: | Operation | Description | - |-----------|-------------| - | `lookup(domain, id)` | Direct item retrieval | - | `dependencies(item, depth)` | Forward traversal (what does this depend on?) | - | `dependents(item, depth)` | Backward traversal (what depends on this?) | - | `blast_radius(item, depth)` | Bidirectional traversal (full impact surface) | - | `by_tag(tag)` | Cross-domain query | - | `assemble_context(task)` | Main context assembly function | + The question arose: How should RSS be exposed for developer use during the exploratory phase? - The question arose: How should RSS be exposed for developer use during the exploratory - phase? - - - ---' + --- technology_stack: - category: language name: TypeScript diff --git a/adrs/physical/ADR-P-0002-json-data-extraction-for-compliance-controls-and-s.yaml b/adrs/physical/ADR-P-0002-json-data-extraction-for-compliance-controls-and-s.yaml index 0df0123..43dcbcc 100644 --- a/adrs/physical/ADR-P-0002-json-data-extraction-for-compliance-controls-and-s.yaml +++ b/adrs/physical/ADR-P-0002-json-data-extraction-for-compliance-controls-and-s.yaml @@ -2,7 +2,7 @@ schema_version: '1.0' adr_type: physical id: ADR-P-0002 title: JSON Data Extraction for Compliance Controls and Schemas -status: proposed +status: superseded created_date: '2026-01-07' modified_date: '2026-01-07' authors: @@ -19,7 +19,9 @@ tags: related_adrs: - ADR-P-0003 - ADR-P-0005 +- ADR-PC-0005 supersedes: [] +superseded_by: ADR-PC-0005 implements_logical: - ADR-L-0001 technologies: @@ -34,56 +36,31 @@ technologies: - testing - typescript - yaml -context: 'Many enterprise codebases contain JSON files with semantic value beyond - simple configuration: - +context: |- + Many enterprise codebases contain JSON files with semantic value beyond simple configuration: | Category | Examples | Semantic Value | - |----------|----------|----------------| - - | Controls/Rules Catalog | Security controls, compliance rules, policy definitions - | High - governance metadata | - - | Data Schemas | Entity definitions, API contracts, validation schemas | High - - data contracts | - - | Deployment Parameters | CFN parameters, environment configs, feature flags | High - - deployment configuration | - - | Reference Data | Seed data, lookup tables, static catalogs | Medium - reference - data | - + | Controls/Rules Catalog | Security controls, compliance rules, policy definitions | High - governance metadata | + | Data Schemas | Entity definitions, API contracts, validation schemas | High - data contracts | + | Deployment Parameters | CFN parameters, environment configs, feature flags | High - deployment configuration | + | Reference Data | Seed data, lookup tables, static catalogs | Medium - reference data | | Test Fixtures | Mock data, test inputs | Low - test data | - - | Package Manifests | `package.json`, `tsconfig.json` | Low - tooling configuration - | - + | Package Manifests | `package.json`, `tsconfig.json` | Low - tooling configuration | Currently, RECON extracts: - - Python code (functions, classes, imports, SDK usage, API endpoints) - - TypeScript code (functions, classes, imports) - - CloudFormation templates (resources, outputs, parameters, GSIs) - **JSON files are not extracted**, leaving semantic gaps: - - - Infrastructure resources may reference control/rule IDs, but definitions are not - in the graph - - - Data schemas define entity structure, but schemas are not linked to code that - uses them - + - Infrastructure resources may reference control/rule IDs, but definitions are not in the graph + - Data schemas define entity structure, but schemas are not linked to code that uses them - Deployment parameters configure resources, but parameter values are not visible - The question arose: Should RECON extract JSON data models and configuration files? - - ---' + --- technology_stack: - category: language name: TypeScript diff --git a/adrs/physical/ADR-P-0003-angular-and-cssscss-semantic-extraction.yaml b/adrs/physical/ADR-P-0003-angular-and-cssscss-semantic-extraction.yaml index 9c9243b..d3ac509 100644 --- a/adrs/physical/ADR-P-0003-angular-and-cssscss-semantic-extraction.yaml +++ b/adrs/physical/ADR-P-0003-angular-and-cssscss-semantic-extraction.yaml @@ -2,7 +2,7 @@ schema_version: '1.0' adr_type: physical id: ADR-P-0003 title: Angular and CSS/SCSS Semantic Extraction -status: proposed +status: superseded created_date: '2026-01-07' modified_date: '2026-01-07' authors: @@ -20,7 +20,9 @@ tags: related_adrs: - ADR-P-0002 - ADR-P-0005 +- ADR-PC-0006 supersedes: [] +superseded_by: ADR-PC-0006 implements_logical: - ADR-L-0001 technologies: @@ -37,68 +39,38 @@ technologies: - testing - typescript - yaml -context: 'The TypeScript extractor currently processes Angular files as standard TypeScript, - capturing: - +context: |- + The TypeScript extractor currently processes Angular files as standard TypeScript, capturing: - Functions and their signatures - - Classes and their methods - - Import/export relationships - - Module structure - However, Angular-specific semantics are not captured: - | Pattern | Current Extraction | Semantic Gap | - |---------|-------------------|--------------| + | `@Component({ selector: 'app-dashboard' })` | Class with decorator | Selector, templateUrl, styleUrls missing | + | `@Injectable({ providedIn: 'root' })` | Class with decorator | Dependency injection scope missing | + | Route definitions | Array of objects | Navigation structure, guards, lazy loading missing | + | HTML templates | Not extracted | Template bindings, component usage, directives missing | - | `@Component({ selector: ''app-dashboard'' })` | Class with decorator | Selector, - templateUrl, styleUrls missing | - - | `@Injectable({ providedIn: ''root'' })` | Class with decorator | Dependency injection - scope missing | - - | Route definitions | Array of objects | Navigation structure, guards, lazy loading - missing | - - | HTML templates | Not extracted | Template bindings, component usage, directives - missing | - - - Additionally, CSS/SCSS files contain semantic information valuable for **any** frontend - project: - + Additionally, CSS/SCSS files contain semantic information valuable for **any** frontend project: - Design tokens (CSS variables, SCSS variables) - - Responsive breakpoints - - Animation definitions - - Component styling patterns - **Impact**: Frontend components cannot be linked to: - - Their templates (component ↔ template relationship) - - Their styles (component ↔ styles relationship) - - Backend services they consume (HTTP calls → API endpoints) - - Other components they render (parent → child relationships) - - Routes that load them (route → component mapping) + The question arose: Should RECON extract Angular-specific semantics and CSS/SCSS beyond basic TypeScript? - The question arose: Should RECON extract Angular-specific semantics and CSS/SCSS - beyond basic TypeScript? - - - ---' + --- technology_stack: - category: language name: TypeScript diff --git a/adrs/physical/ADR-P-0004-ste-runtime-mcp-server-implementation.yaml b/adrs/physical/ADR-P-0004-ste-runtime-mcp-server-implementation.yaml index 9605c94..1d9ac62 100644 --- a/adrs/physical/ADR-P-0004-ste-runtime-mcp-server-implementation.yaml +++ b/adrs/physical/ADR-P-0004-ste-runtime-mcp-server-implementation.yaml @@ -2,7 +2,7 @@ schema_version: '1.0' adr_type: physical id: ADR-P-0004 title: ste-runtime MCP Server Implementation -status: accepted +status: superseded created_date: '2026-01-11' modified_date: '2026-01-11' authors: @@ -18,7 +18,9 @@ tags: - file-watching related_adrs: - ADR-P-0001 +- ADR-PS-0001 supersedes: [] +superseded_by: ADR-PS-0001 implements_logical: - ADR-L-0004 - ADR-L-0006 @@ -34,44 +36,28 @@ technologies: - testing - typescript - yaml -context: 'Per STE Architecture Section 3.1, the Workspace Development Boundary requires: - +context: |- + Per STE Architecture Section 3.1, the Workspace Development Boundary requires: - **Provisional state** maintenance (pre-merge, feature branches) - - **Soft + hard enforcement** (LLM instruction-following + validation tools) - - **Post-reasoning validation** (catch violations after generation) - - **Context assembly via RSS** (CEM Stage 2: State Loading) - Currently, ste-runtime provides: - - ✅ Incremental RECON (maintains fresh AI-DOC) - - ✅ RSS operations (semantic graph traversal) - - ✅ CLI interface (human-friendly commands) - - ❌ No long-running process (graph reloaded on every query) - - - ❌ No MCP interface (Cursor can''t discover tools automatically) - + - ❌ No MCP interface (Cursor can't discover tools automatically) - ❌ No automatic file watching (manual RECON invocation required) - **Gap:** Cursor (and other AI assistants) need: - 1. **Always-fresh semantic state** (automatic updates on file changes) - 2. **Fast queries** (in-memory graph, <100ms response) - 3. **Tool auto-discovery** (MCP protocol for semantic operations) - 4. **Deterministic context** (RSS graph traversal, not probabilistic search) - - ---' + --- technology_stack: - category: language name: TypeScript diff --git a/adrs/rendered/ADR-L-0001.md b/adrs/rendered/ADR-L-0001.md index 081c299..3e6bd8a 100644 --- a/adrs/rendered/ADR-L-0001.md +++ b/adrs/rendered/ADR-L-0001.md @@ -5,7 +5,7 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: be89fa1f5de8f4a4d2c6b37e423be67c5e2c558b0ef27dfc75bbe42061c0499d +source_hash: b2580c9488d92b842f4d0b198cebb966be00816a2fc7c0a219c8be56cd06c4a4 rendered_hash: 4efb87c6e9fcb3729c2e03e47aa2cdc41b4e5be22bdf8645e8c1d918e1f7016c --> diff --git a/adrs/rendered/ADR-L-0002.md b/adrs/rendered/ADR-L-0002.md index a0c27ed..80b7e7f 100644 --- a/adrs/rendered/ADR-L-0002.md +++ b/adrs/rendered/ADR-L-0002.md @@ -5,8 +5,8 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: 433d9a37082efd2d21e0c65fe84e695d5c695dd330f2e4d3d4311f47c7125558 -rendered_hash: bac9a5a43897dc9aaa390622b29bc9a12d057c94b73e05588c166b7ff67b1a9c +source_hash: d965dbcc563c816c64a2af2a3cc0dd502014d85ce0bf394cc3b8a7d3e84060ac +rendered_hash: 428bbd0490212fa9d1eaeb1a808b4f4cc2a32802f06f1eac9c7aff8153625aa6 --> # ADR-L-0002: RECON Self-Validation Strategy @@ -44,7 +44,7 @@ Key tensions: ## Decisions -### DEC-0001: RECON self-validation is non-blocking, report-only, and exploratory. +### DEC-0002: RECON self-validation is non-blocking, report-only, and exploratory. **Rationale:** ### 1. Non-Blocking Preserves Learning diff --git a/adrs/rendered/ADR-L-0003.md b/adrs/rendered/ADR-L-0003.md index d731304..16d9f31 100644 --- a/adrs/rendered/ADR-L-0003.md +++ b/adrs/rendered/ADR-L-0003.md @@ -5,8 +5,8 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: fa678604bf325c6d0ac2c77d488f2f481d90acc509ffb213218e123109383c36 -rendered_hash: c98c36fc489b8b12f18b14f7b7274e6b5f05bd251af47f62a23a5636bac57b1b +source_hash: f5b5172ff02d2d29315222a400774e7b1d0b276b29d8140274d74f1b908896ff +rendered_hash: c057487f7754b833aad74061142057863490e2654fd5d5af5ed275a6fafac332 --> # ADR-L-0003: CEM Implementation Deferral @@ -46,7 +46,7 @@ The question arose: Should CEM be implemented early in ste-runtime development, ## Decisions -### DEC-0001: CEM implementation is intentionally deferred. +### DEC-0003: CEM implementation is intentionally deferred. **Rationale:** ### 1. CEM Orchestrates Components That Must Exist First diff --git a/adrs/rendered/ADR-L-0004.md b/adrs/rendered/ADR-L-0004.md index 5d5b804..08025a4 100644 --- a/adrs/rendered/ADR-L-0004.md +++ b/adrs/rendered/ADR-L-0004.md @@ -5,8 +5,8 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: 75d48c8f11e44b0ead0da2c1b7e8503585b0a6b7134bf36a47c21c9ad3154aa5 -rendered_hash: 22aec5456f9ff93746a645b61d6bfbc2f8aee71a9092773e04a9fd93c6cd4595 +source_hash: f6b9d1eabe48678959ac531d438f8ea4b8134d91910d9d2ec885c72d29f09730 +rendered_hash: 8fe5039a8ae4897e26a283ea813f4bf4e31f250b7b7ce29c3557922999fc0816 --> # ADR-L-0004: Watchdog Authoritative Mode for Workspace Boundary @@ -75,7 +75,7 @@ This E-ADR defines ste-runtime's operation within the **Workspace Development Bo ## Decisions -### DEC-0001: ste-runtime is a single process that combines: +### DEC-0004: ste-runtime is a single process that combines: **Rationale:** ### The Watchdog IS the Conflict Resolution Process diff --git a/adrs/rendered/ADR-L-0005.md b/adrs/rendered/ADR-L-0005.md index 8ef9b15..c51d676 100644 --- a/adrs/rendered/ADR-L-0005.md +++ b/adrs/rendered/ADR-L-0005.md @@ -5,8 +5,8 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: af109e2352d2f1b9c50cdfde013117c435e19f955080c80c451d6ba825fbaf64 -rendered_hash: 851859b5ced152b519e2db91f9f9f245d9153ea8623fcd694bb581013747d0a1 +source_hash: 423d83460642c5258c5b2dd1cd7169b132fd900547798819db11c1a78a1abb64 +rendered_hash: 5bdb38fb5b7140f766cbc88d6b40a75dd8cb3c30735c100d88cdef3eac9648ae --> # ADR-L-0005: Self-Configuring Domain Discovery @@ -34,7 +34,7 @@ rendered_hash: 851859b5ced152b519e2db91f9f9f245d9153ea8623fcd694bb581013747d0a1 ## Decisions -### DEC-0001: +### DEC-0005: **Rationale:** diff --git a/adrs/rendered/ADR-L-0006.md b/adrs/rendered/ADR-L-0006.md index c8320ca..fcb8d0e 100644 --- a/adrs/rendered/ADR-L-0006.md +++ b/adrs/rendered/ADR-L-0006.md @@ -5,8 +5,8 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: 4037cd787350e12c4c6fac7af3bdcd0cb3b5b13287976177ad2bf67f42feda88 -rendered_hash: 0e9130131f7aa79cd5f5263a29d7feca9f8a22a2fe6bd6e66bdae6d80f5475eb +source_hash: f7ba4c64bdd9f4fa4a8183e5d9000ca4888a3cfd8ac41fee900eb9d46f500ab2 +rendered_hash: 872b554a7fa879f04f949f0c9bfda92ee7dd30d6e9c9e11f97af5b7a6719f111 --> # ADR-L-0006: Conversational Query Interface for RSS @@ -59,7 +59,7 @@ This friction degrades both human UX and AI agent efficiency. ## Decisions -### DEC-0001: Implement a Conversational Query Interface (CQI) as a layer above RSS that: +### DEC-0006: Implement a Conversational Query Interface (CQI) as a layer above RSS that: **Rationale:** ### 1. Reduces Cognitive Load for Both Humans and AI diff --git a/adrs/rendered/ADR-L-0007.md b/adrs/rendered/ADR-L-0007.md new file mode 100644 index 0000000..aec91cf --- /dev/null +++ b/adrs/rendered/ADR-L-0007.md @@ -0,0 +1,63 @@ + + +# ADR-L-0007: Graph Freshness and Obligation Projection Semantics + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** rss, obligations, freshness +**Tags:** freshness, obligations, preflight, validation + +**Related ADRs:** ADR-L-0004, ADR-L-0006 + + + +--- + +## Context + +ste-runtime now exposes graph freshness checks, invalidated validation +signals, change intent handling, and obligation projection behavior through +RSS and MCP tooling. These semantics are broader than implementation detail +and require an explicit logical authority. + + +## Capabilities + +### CAP-0007: Surface graph freshness and obligation projection semantics + +Provide canonical freshness, invalidation, and obligation semantics for runtime consumers. + + + + + + + +## Decisions + +### DEC-0007: Freshness and obligation projection are logical runtime semantics + +**Rationale:** +The current runtime models freshness and obligation data in public schemas +and assistant-facing responses, so these semantics require canonical +documentation above the component layer. + + + + + + + +--- + +*Generated from ADR-L-0007 by ADR Architecture Kit* \ No newline at end of file diff --git a/adrs/rendered/ADR-P-0001.md b/adrs/rendered/ADR-P-0001.md index dbf9428..c3bacac 100644 --- a/adrs/rendered/ADR-P-0001.md +++ b/adrs/rendered/ADR-P-0001.md @@ -5,7 +5,7 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: 453d5f92b6eb69872ebdc6ba02e4c4b54241d9d80e5542817b5a6ba2815de6cb +source_hash: 76a996396f68b8bb54499b2a5e24bfae6a5c2a364cb86b1720625f50e0485a08 rendered_hash: 69665549e411c9384a6b85080bb48d1f038d1f56b67c20ce94fe03f29db2329c --> diff --git a/adrs/rendered/ADR-P-0002.md b/adrs/rendered/ADR-P-0002.md index 8813a38..04bb561 100644 --- a/adrs/rendered/ADR-P-0002.md +++ b/adrs/rendered/ADR-P-0002.md @@ -5,13 +5,13 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: 08ae199510e50dd10b99300602d80bd1cd66cf8a606e7d900b2ea9f2f81c3d27 -rendered_hash: c3b79c3d7814cad1f3a33db1b184e472704a950a7978f4e5699c70278d7d96b6 +source_hash: 4b30ba613bbbfabd86a3fcc48e0997623fb84bae9b882af2d3285d5b9c10f9d0 +rendered_hash: e4478446f2299de9ab1555032ed2a6b8511080d1248d54daf2d40758b0c264d6 --> # ADR-P-0002: JSON Data Extraction for Compliance Controls and Schemas -**Status:** proposed +**Status:** superseded **Created:** 2026-01-07 **Modified:** 2026-01-07 **Authors:** erik.gallmann **Domains:** extraction, data, implementation @@ -19,7 +19,7 @@ rendered_hash: c3b79c3d7814cad1f3a33db1b184e472704a950a7978f4e5699c70278d7d96b6 **Implements Logical:** ADR-L-0001 **Technologies:** cli, data-extraction, file-discovery, file-watching, json, mcp, node.js, schema-validation, testing, typescript, yaml -**Related ADRs:** ADR-P-0003, ADR-P-0005 +**Related ADRs:** ADR-P-0003, ADR-P-0005, ADR-PC-0005 --- diff --git a/adrs/rendered/ADR-P-0003.md b/adrs/rendered/ADR-P-0003.md index c549965..bf8780c 100644 --- a/adrs/rendered/ADR-P-0003.md +++ b/adrs/rendered/ADR-P-0003.md @@ -5,13 +5,13 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: 75c3db11cb228670ae36d9dbe95598342bc3d4e447c5bbeccb35dfee7c446dc4 -rendered_hash: 900f978873772a3782d1acd2f3eeb5ed194954218eb62ae9591dad8ab1c39908 +source_hash: 03e2bfda49cc1bb83be6f8a85f7a5353697d59dbf7b8dc318ad5da7a334474ad +rendered_hash: e20e413211f4693c6e196a8715098310a4b2043c9925101fa1c552fa5deaa3a6 --> # ADR-P-0003: Angular and CSS/SCSS Semantic Extraction -**Status:** proposed +**Status:** superseded **Created:** 2026-01-07 **Modified:** 2026-01-07 **Authors:** erik.gallmann **Domains:** extraction, frontend, implementation @@ -19,7 +19,7 @@ rendered_hash: 900f978873772a3782d1acd2f3eeb5ed194954218eb62ae9591dad8ab1c39908 **Implements Logical:** ADR-L-0001 **Technologies:** angular, ast-parsing, cli, css, file-discovery, file-watching, mcp, node.js, schema-validation, scss, testing, typescript, yaml -**Related ADRs:** ADR-P-0002, ADR-P-0005 +**Related ADRs:** ADR-P-0002, ADR-P-0005, ADR-PC-0006 --- diff --git a/adrs/rendered/ADR-P-0004.md b/adrs/rendered/ADR-P-0004.md index 5b18dd0..2be2ec3 100644 --- a/adrs/rendered/ADR-P-0004.md +++ b/adrs/rendered/ADR-P-0004.md @@ -5,13 +5,13 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: 8422cc1807099af390396d8877b7bfba15cd358aca3fade419d0b289abb6e903 -rendered_hash: 348c075c9c2c8ee973d25eb74195c2c596c04de3853bbb79285c6fe79fad3b0b +source_hash: a61756790fd6595a3975e0b058f492a1d9c92a0edfbb530e3a369645195e2c18 +rendered_hash: c5d4a5af4020ac9e7486ba8727ee7fc6dbdfaf2197cafd80e48e13401d131051 --> # ADR-P-0004: ste-runtime MCP Server Implementation -**Status:** accepted +**Status:** superseded **Created:** 2026-01-11 **Modified:** 2026-01-11 **Authors:** erik.gallmann **Domains:** mcp, integration, implementation @@ -19,7 +19,7 @@ rendered_hash: 348c075c9c2c8ee973d25eb74195c2c596c04de3853bbb79285c6fe79fad3b0b **Implements Logical:** ADR-L-0004, ADR-L-0006 **Technologies:** cli, file-discovery, file-watching, incremental-recon, mcp, node.js, schema-validation, stdio, testing, typescript, yaml -**Related ADRs:** ADR-P-0001 +**Related ADRs:** ADR-P-0001, ADR-PS-0001 --- diff --git a/adrs/rendered/ADR-P-0005.md b/adrs/rendered/ADR-P-0005.md index d8c8ef9..2562fd8 100644 --- a/adrs/rendered/ADR-P-0005.md +++ b/adrs/rendered/ADR-P-0005.md @@ -5,7 +5,7 @@ artifact_kind: rendered_adr_markdown generator_id: adr-rendered-markdown generator_version: 1 hash_algorithm: sha256 -source_hash: ca302d811f9e2d2cdd4dc47233d415e88ba72d0035f217beb9b3d56ba6462000 +source_hash: 42ab9e33279b5fcbdc7bb02b3df8e81624f02826e92f1c76ff50ad5be020aeac rendered_hash: f835cc19c96ee70200201d2e259c77737efae61c2159895d33c78bccb6b8366a --> diff --git a/adrs/rendered/ADR-PC-0001.md b/adrs/rendered/ADR-PC-0001.md new file mode 100644 index 0000000..e55defc --- /dev/null +++ b/adrs/rendered/ADR-PC-0001.md @@ -0,0 +1,77 @@ + + +# ADR-PC-0001: MCP Server and Tool Registry + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** mcp, integration, runtime + +**Implements Logical:** ADR-L-0004, ADR-L-0006, ADR-L-0007 +**Technologies:** typescript, node.js, mcp, zod + + +--- + +## Context + +This component exposes assistant-facing runtime tools over MCP and binds +structural, operational, context, optimized, and obligation-oriented tool +surfaces into one discoverable server boundary. + + +## Technology Stack + +### TypeScript (language) + +**Version:** 5.3+ + +**Rationale:** +Existing implementation language. + +### @modelcontextprotocol/sdk (library) + +**Version:** 1.x + +**Rationale:** +MCP protocol implementation. + + + +## Component Specifications + +### COMP-0001: MCP Server and Tool Registry (service) + +**Responsibilities:** +- Serve MCP stdio runtime for assistant integration +- Register structural, operational, context, optimized, and obligation tools +- Route tool requests onto runtime graph and context services + + +**Interfaces:** +- **IFACE-0001** (CLI): Entry surfaces: +- src/mcp/mcp-server.ts +- MCP stdio tool registration for structural, operational, c... + +**Implementation Identifiers:** +- Module Path: `src/mcp/mcp-server.ts` + + + + + + + + +--- + +*Generated from ADR-PC-0001 by ADR Architecture Kit* \ No newline at end of file diff --git a/adrs/rendered/ADR-PC-0002.md b/adrs/rendered/ADR-PC-0002.md new file mode 100644 index 0000000..25d1480 --- /dev/null +++ b/adrs/rendered/ADR-PC-0002.md @@ -0,0 +1,81 @@ + + +# ADR-PC-0002: Watchdog and Update Coordination + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** watch, runtime, reconciliation + +**Implements Logical:** ADR-L-0004 +**Technologies:** typescript, node.js, chokidar + + +--- + +## Context + +This component monitors changes, detects transactions, coordinates update +batches, and safeguards write-triggered reconciliation behavior for the +runtime boundary. + + +## Technology Stack + +### TypeScript (language) + +**Version:** 5.3+ + +**Rationale:** +Existing implementation language. + +### chokidar (library) + +**Version:** 3.x + +**Rationale:** +File watching implementation. + + + +## Component Specifications + +### COMP-0002: Watchdog and Update Coordination (worker) + +**Responsibilities:** +- Watch source and state changes +- Detect coherent edit transactions +- Coordinate update batches and reconciliation triggers +- Protect runtime behavior from unsafe write loops + + +**Interfaces:** +- **IFACE-0002** (library_api): Public surfaces: +- Watchdog +- UpdateCoordinator +- TransactionDetector +- WriteTracker +... + +**Implementation Identifiers:** +- Module Path: `src/watch/watchdog.ts` + + + + + + + + +--- + +*Generated from ADR-PC-0002 by ADR Architecture Kit* \ No newline at end of file diff --git a/adrs/rendered/ADR-PC-0003.md b/adrs/rendered/ADR-PC-0003.md new file mode 100644 index 0000000..7770029 --- /dev/null +++ b/adrs/rendered/ADR-PC-0003.md @@ -0,0 +1,72 @@ + + +# ADR-PC-0003: Preflight Freshness and Reconciliation Gating + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** preflight, freshness, reconciliation + +**Implements Logical:** ADR-L-0004, ADR-L-0007 +**Technologies:** typescript, node.js, zod + + +--- + +## Context + +This component evaluates file freshness, intent scope, and reconciliation +requirements before runtime actions rely on semantic graph state. + + +## Technology Stack + +### TypeScript (language) + +**Version:** 5.3+ + +**Rationale:** +Existing implementation language. + + + +## Component Specifications + +### COMP-0003: Preflight Freshness and Reconciliation Gate (service) + +**Responsibilities:** +- Resolve intent scope +- Evaluate graph freshness +- Determine whether reconciliation is required +- Surface freshness status for downstream tools + + +**Interfaces:** +- **IFACE-0003** (library_api): Public surfaces: +- preflightReconciliation +- checkFreshness +- resolveIntentScope +... + +**Implementation Identifiers:** +- Module Path: `src/mcp/preflight.ts` + + + + + + + + +--- + +*Generated from ADR-PC-0003 by ADR Architecture Kit* \ No newline at end of file diff --git a/adrs/rendered/ADR-PC-0004.md b/adrs/rendered/ADR-PC-0004.md new file mode 100644 index 0000000..fbde8fb --- /dev/null +++ b/adrs/rendered/ADR-PC-0004.md @@ -0,0 +1,73 @@ + + +# ADR-PC-0004: Obligation Projection and Context Assembly + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** obligations, context, rss + +**Implements Logical:** ADR-L-0006, ADR-L-0007 +**Technologies:** typescript, node.js, zod + + +--- + +## Context + +This component projects invalidated validations and change-driven obligations, +assembles implementation context, and loads source-backed evidence for +assistant-facing reasoning. + + +## Technology Stack + +### TypeScript (language) + +**Version:** 5.3+ + +**Rationale:** +Existing implementation language. + + + +## Component Specifications + +### COMP-0004: Obligation Projection and Context Assembly (service) + +**Responsibilities:** +- Project obligations from change intent and graph state +- Surface invalidated validations and advisories +- Load source-backed implementation context +- Format runtime context for assistant consumption + + +**Interfaces:** +- **IFACE-0004** (library_api): Public surfaces: +- projectObligations +- assembleContextTool +- getImplementationContext +- loadSourceG... + +**Implementation Identifiers:** +- Module Path: `src/mcp/obligation-projector.ts` + + + + + + + + +--- + +*Generated from ADR-PC-0004 by ADR Architecture Kit* \ No newline at end of file diff --git a/adrs/rendered/ADR-PC-0005.md b/adrs/rendered/ADR-PC-0005.md new file mode 100644 index 0000000..b4a9104 --- /dev/null +++ b/adrs/rendered/ADR-PC-0005.md @@ -0,0 +1,71 @@ + + +# ADR-PC-0005: JSON Semantic Extraction + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** extraction, json, recon + +**Implements Logical:** ADR-L-0001 +**Technologies:** typescript, json, node.js + +**Related ADRs:** ADR-P-0002 + +--- + +## Context + +JSON semantic extraction captures controls, schemas, and configuration +semantics from JSON sources and feeds them into RECON normalization. + + +## Technology Stack + +### TypeScript (language) + +**Version:** 5.3+ + +**Rationale:** +Existing implementation language. + + + +## Component Specifications + +### COMP-0005: JSON Semantic Extractor (library) + +**Responsibilities:** +- Detect semantically relevant JSON files +- Extract controls, schemas, and configuration semantics +- Provide RECON-ready assertions for normalization + + +**Interfaces:** +- **IFACE-0005** (library_api): Public surfaces: +- src/extractors/json/index.ts +- src/extractors/json/json-extractor.ts +... + +**Implementation Identifiers:** +- Module Path: `src/extractors/json/json-extractor.ts` + + + + + + + + +--- + +*Generated from ADR-PC-0005 by ADR Architecture Kit* \ No newline at end of file diff --git a/adrs/rendered/ADR-PC-0006.md b/adrs/rendered/ADR-PC-0006.md new file mode 100644 index 0000000..c4b0580 --- /dev/null +++ b/adrs/rendered/ADR-PC-0006.md @@ -0,0 +1,70 @@ + + +# ADR-PC-0006: Frontend Semantic Extraction + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** extraction, frontend, recon + +**Implements Logical:** ADR-L-0001 +**Technologies:** typescript, angular, css, scss + +**Related ADRs:** ADR-P-0003 + +--- + +## Context + +Frontend semantic extraction captures Angular and CSS/SCSS-specific semantics +beyond generic TypeScript structure and feeds them into RECON normalization. + + +## Technology Stack + +### TypeScript (language) + +**Version:** 5.3+ + +**Rationale:** +Existing implementation language. + + + +## Component Specifications + +### COMP-0006: Frontend Semantic Extractor (library) + +**Responsibilities:** +- Extract Angular component, service, route, and template semantics +- Extract CSS/SCSS tokens, styles, and related frontend semantics +- Provide frontend assertions for RECON normalization + + +**Interfaces:** +- **IFACE-0006** (library_api): Public surfaces: +- src/extractors/angular/angular-extractor.ts +- src/extractors/css/css-extractor.ts... + +**Implementation Identifiers:** +- Module Path: `src/extractors/angular/angular-extractor.ts` + + + + + + + + +--- + +*Generated from ADR-PC-0006 by ADR Architecture Kit* \ No newline at end of file diff --git a/adrs/rendered/ADR-PC-0007.md b/adrs/rendered/ADR-PC-0007.md new file mode 100644 index 0000000..6e25572 --- /dev/null +++ b/adrs/rendered/ADR-PC-0007.md @@ -0,0 +1,71 @@ + + +# ADR-PC-0007: CloudFormation Semantic Extraction + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** extraction, cloudformation, recon + +**Implements Logical:** ADR-L-0001 +**Technologies:** typescript, cloudformation, yaml, json + + +--- + +## Context + +CloudFormation semantic extraction captures templates, resources, outputs, +parameters, infrastructure relationships, and template-level implementation +intent from CloudFormation sources. + + +## Technology Stack + +### TypeScript (language) + +**Version:** 5.3+ + +**Rationale:** +Existing implementation language. + + + +## Component Specifications + +### COMP-0007: CloudFormation Semantic Extractor (library) + +**Responsibilities:** +- Extract template, parameter, resource, and output semantics +- Derive infrastructure relationships and API/data model evidence +- Preserve template-level implementation intent metadata + + +**Interfaces:** +- **IFACE-0007** (library_api): Public surfaces: +- src/recon/phases/extraction-cloudformation.ts +- src/extractors/cfn/* +... + +**Implementation Identifiers:** +- Module Path: `src/recon/phases/extraction-cloudformation.ts` + + + + + + + + +--- + +*Generated from ADR-PC-0007 by ADR Architecture Kit* \ No newline at end of file diff --git a/adrs/rendered/ADR-PS-0001.md b/adrs/rendered/ADR-PS-0001.md new file mode 100644 index 0000000..c7d63d6 --- /dev/null +++ b/adrs/rendered/ADR-PS-0001.md @@ -0,0 +1,86 @@ + + +# ADR-PS-0001: Runtime Orchestration and Assistant Integration + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** runtime, mcp, rss, watch +**Tags:** runtime, mcp, watchdog, obligations +**Implements Logical:** ADR-L-0004, ADR-L-0006, ADR-L-0007 +**Technologies:** typescript, node.js, mcp, chokidar, zod + +**Related ADRs:** ADR-P-0004 + +--- + +## Context + +ste-runtime now contains a runtime orchestration boundary that keeps semantic +state fresh, exposes assistant-facing MCP tools, performs reconciliation +gating and freshness checks, and assembles implementation context and +obligation projections for agents and operators. + + +## Technology Stack + +### TypeScript (language) + +**Version:** 5.3+ + +**Rationale:** +Existing runtime implementation language. + +### Node.js (framework) + +**Version:** 18.x+ + +**Rationale:** +Existing runtime execution environment. + +### @modelcontextprotocol/sdk (library) + +**Version:** 1.x + +**Rationale:** +MCP protocol implementation. + +### chokidar (library) + +**Version:** 3.x + +**Rationale:** +Cross-platform file watching. + + + +## Component Specifications + + + + + + +## Operational Requirements + +### Monitoring +Track freshness status, invalidated validations, and runtime health metrics. + +### Logging +Structured runtime logs for reconciliation and tool invocation flows. + + + + +--- + +*Generated from ADR-PS-0001 by ADR Architecture Kit* \ No newline at end of file diff --git a/adrs/rendered/ADR-PS-0002.md b/adrs/rendered/ADR-PS-0002.md new file mode 100644 index 0000000..c985321 --- /dev/null +++ b/adrs/rendered/ADR-PS-0002.md @@ -0,0 +1,63 @@ + + +# ADR-PS-0002: Semantic Extraction Subsystem + +**Status:** proposed +**Created:** 2026-03-15 +**Authors:** ste-runtime +**Domains:** extraction, recon, normalization +**Tags:** extraction, recon, semantic-state +**Implements Logical:** ADR-L-0001, ADR-L-0005 +**Technologies:** typescript, node.js, json, angular, css, cloudformation + +**Related ADRs:** ADR-P-0002, ADR-P-0003 + +--- + +## Context + +ste-runtime extraction is now a subsystem containing multiple first-class +extractors and normalization flows rather than a pair of isolated physical +slices. This ADR groups the implemented extractor estate under a concrete +system boundary. + + +## Technology Stack + +### TypeScript (language) + +**Version:** 5.3+ + +**Rationale:** +Existing implementation language. + +### Node.js (framework) + +**Version:** 18.x+ + +**Rationale:** +Existing execution environment. + + + +## Component Specifications + + + + + + + + +--- + +*Generated from ADR-PS-0002 by ADR Architecture Kit* \ No newline at end of file