Skip to content

SYSTEM-OVERVIEW.md

Latest commit

 

History

History
260 lines (182 loc) · 10.5 KB

SYSTEM-OVERVIEW.md

File metadata and controls

260 lines (182 loc) · 10.5 KB

document_type: system-overview audience: ai-first project: ste-runtime status: active purpose: > Single-file orientation for AI and human contributors. Use this file first to discover repository authority, canonical workflows, generated documentation, and safe extension points before making changes. authority_order:

  • PROJECT.yaml PROJECT.yaml
  • adrs/ adrs/
  • adrs/manifest.yaml adrs/manifest.yaml
  • package.json package.json
  • src/ src/ first_read: true last_updated: generated-from-source generation_rule: > Generated by SystemOverviewGenerator. Edit repository metadata, ADRs, or the generator/template, not this file directly.

SYSTEM-OVERVIEW

Why This File Exists

This file is the fastest correct orientation path for an AI working in this repository.

Its job is to prevent two common failures:

  1. Missing project-native capabilities that already exist, such as generators, validators, and CLI commands.
  2. Making path, scope, or artifact assumptions that conflict with repository authority.

Read this file before writing code, generating artifacts, or hand-crafting repository outputs.

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.

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

Primary package manager: npm.

Authority Hierarchy

Use this order when resolving ambiguity:

  1. PROJECT.yaml Project-local metadata: ownership, automation posture, repository intent, and ADR locations.
  2. adrs/ Architectural authority for this repository.
  3. adrs/manifest.yaml Generated ADR index used for fast discovery and summary-level reasoning.
  4. package.json Runtime, scripts, package metadata, and Node-based workflow authority.
  5. src/, scripts/, python-scripts/ Primary implementation surface.

If code and ADRs disagree, treat the ADRs and project policy as authoritative unless the task is explicitly to correct the ADRs.

First Discovery Order

When an AI enters this repo cold, use this order:

  1. Read PROJECT.yaml.
  2. Read this file.
  3. Inspect adrs/ and adrs/manifest.yaml.
  4. Inspect adrs/rendered/ for generated human-readable ADR views.
  5. Inspect package.json for scripts, runtime boundaries, and entrypoints.
  6. Inspect the primary implementation surface: src/, scripts/, python-scripts/.
  7. Inspect .github/workflows/test.yml for enforced CI checks.
  8. Only then decide whether new code or documentation is needed.

Do not start by hand-writing artifacts if a generator or validator already exists.

Canonical Capabilities

Core implementation areas:

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

Artifact Model

Repository artifact classes:

Subtype authority comes from document content, not folders:

  • adr_type
  • id

Do not infer physical subtype from directory names when frontmatter already tells you the type.

ADR Taxonomy

Use this type model when reasoning about repository architecture artifacts:

  • ADR-L-XXXX: Conceptual logical design: capabilities, boundaries, contracts, constraints, and invariants.
  • 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.

Canonical Workflows

Generate rendered ADR markdown

Run adr generate-rendered-docs --scope C:\Users\Erik\Documents\Projects\ste-runtime. Do not hand-edit files under adrs/rendered/.

Regenerate this overview

Run adr generate-system-overview --scope C:\Users\Erik\Documents\Projects\ste-runtime. Do not hand-edit SYSTEM-OVERVIEW.md.

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.

Build the project

Run npm run build.

Lint the project

Run npm run lint.

Run automated tests

Run npm test.

Refresh semantic self-documentation

Run npm run recon:self and review generated state noise before committing.

Respect project quality gates

Current declared gates: type_checking, test_suite_passing, linting, dependency_security_audit.

Tooling Priority Rules

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.

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.

Use ADR metadata and project metadata as placement authority before relying on directory folklore.

High-Value Invariants

Start here when you need the non-negotiables:

  • INV-0001 - Single repository only: RECON discovers files within the current repository. Cross-repository reconciliation is out of scope.
  • INV-0002 - Incremental reconciliation: Only files that have changed since the last run are re-extracted (when timestamp detection is available).
  • INV-0003 - Configurable source directories: Specified via ste.config.json or auto-detected.
  • INV-0004 - Shallow extraction: Extract structural elements (functions, classes, imports, exports) without deep semantic analysis.
  • INV-0005 - No deep semantic analysis: Do not attempt to understand function behavior, side effects, or complex type flows.
  • INV-0006 - Multi-language support: TypeScript, Python, CloudFormation, JSON (see E-ADR-005), Angular, CSS/SCSS (see E-ADR-006).
  • INV-0007 - Portable execution: RECON must work when dropped into any project.
  • INV-0008 - Provisional mapping: Normalization to AI-DOC schema is best-effort, not canonical.
  • INV-0009 - Schema evolution expected: The AI-DOC schema is still evolving; normalization will change.
  • INV-0010 - ID stability: Element IDs should be stable across runs for the same source element.

Practical meaning:

  • schema-invalid artifacts are not acceptable
  • deprecated runtime APIs are not acceptable
  • dependency security must be checked
  • dependency freshness must be surfaced continuously
  • derived artifacts must be regenerated, not manually drifted

Fast Target Discovery

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.

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

Completion Criteria

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

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.