Skip to content

File-System Knowledge Repository

Intent

Persist and organize institutional architectural state, decisions, and governance models directly within a version-controlled directory hierarchy on disk to enable transparent peer-review, offline portability, and git-native governance.

Context

Applied enterprise-wide across continuous architecture steering runtimes, multi-agent evaluation workflows, and project repositories requiring durable knowledge storage without external database infrastructure dependencies.

Agentic Profile

Provides autonomous agents with predictable filesystem-backed read and write boundaries for architectural knowledge ingestion, runtime state evaluation, and delta projection without requiring networked database protocols.

Forces

The pattern balances git-native auditability and zero-infrastructure persistence against potential filesystem merge contention under concurrent multi-agent or parallel pipeline commits.

Drivers

  • Elimination of external database infrastructure overhead
  • Transparent reviewability of architectural decisions via standard Git pull-request workflows
  • Auditable, branchable, and reproducible state history across distributed environments

Constraints

  • Local filesystem I/O operations and Git storage conventions
  • Consistent directory structures and serialization standards required across distributed projects

Tradeoffs

  • Simplicity and auditability of plain-text file storage versus query flexibility of relational database engines
  • Decentralized offline execution access versus potential merge contention under highly concurrent write operations

Solution

Establish a standardized hierarchical folder structure on the local filesystem (partitioning global policies, project-scoped assets, templates, and runtime trace states) accessed through dedicated repository abstractions to serve as an authoritative, version-controlled blackboard memory.

Operationalisation

Implemented through repository IO abstractions and bootstrap scaffolding routines integrated into continuous integration pipelines and agent runtimes.

Workflow Implications

  • All architectural policy and catalog state modifications must flow through Git commit and pull-request review cycles
  • Runner steps must read and write state artifacts through dedicated knowledge provider interfaces rather than direct hardcoded paths

Automation Opportunities

  • Automated CI validation of markdown frontmatter and JSON/YAML schemas on repository changes
  • Automated synchronization and serialization of runtime evaluation traces and steering projections

Implementation Signals

Recurring persistence decoupling signals, successful consolidation across file-backed knowledge proposal variants, and implementation within LocalKnowledgeProvider and workspace bootstrap modules.

Evidence

Demonstrated through ratified Reference Architecture in ArchGov and proven production usage in LocalKnowledgeProvider and bootstrap modules.

Signals

  • Thirteen duplicate proposals consolidated under file-backed blackboard workspace and file-system knowledge repository
  • Ratified Reference Architecture in ArchGov

Supporting Evidence

  • LocalKnowledgeProvider implementation in src/cas_runner/io.py
  • Workspace bootstrap routines in src/cas_runner/bootstrap.py

Confidence Basis

Empirically verified across local runner execution, continuous architecture CI pipelines, and ArchGov reference architecture ratification.

Consequences

Guarantees transparent, database-free architecture versioning and inspectability while requiring serialization discipline to prevent concurrent git conflicts.

Benefits

  • Transparent, human-readable, and git-traceable knowledge substrate
  • Decoupled runner execution with zero external database dependencies
  • Reproducible offline execution across distributed multi-project environments

Risks

  • Filesystem merge contention when multiple parallel workflows or autonomous agents commit concurrent state deltas

Governance Implications

  • Enforces peer-reviewed Git pull requests as the mandatory governance control gate for all architectural state changes
  • Requires machine validation of file schemas during CI to guarantee repository integrity

Reuse Notes

Globally applicable to enterprise continuous architecture steering repositories, agentic runners, and software workspaces requiring auditable, offline-capable architectural persistence.

Confidence

High confidence grounded in ratified reference architecture specifications and verified production operation in runner IO pipelines.

Level: high

Rationale

Validated through successful implementation in core runner modules (LocalKnowledgeProvider) and formal Architecture Forum ratification.