archledger 0.1.0__tar.gz

archledger-0.1.0/.archledger/records/building_blocks/al_0041.md

@@ -0,0 +1,47 @@
+---
+id: al_0041
+type: white_box
+title: Overall System
+schema_version: 2
+date: "2026-05-21"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: null
+order: 10
+diagram: null
+quality_characteristics: []
+tags: []
+created_at: "2026-05-20T05:52:14Z"
+updated_at: "2026-05-22T07:00:00Z"
+source_refs:
+  - path: archledger/
+    reason: All source code under the archledger package
+---
+
+## Motivation
+
+archledger is decomposed into fifteen black boxes organized as a layered pipeline: the CLI accepts user input and delegates output formatting, the Config layer parses and renders project configuration, the Repository orchestrates business logic, the Model layer defines core data structures, the Record Type Registry maps record types to templates and defaults, the Check layer validates record content per type, the Source Ref Validation layer normalizes traceability links, the Storage layer handles file I/O, the Assembly layer renders the document, the Dialect layer abstracts format-specific markup, the Section Rendering layer handles per-record-type output, the Render layer orchestrates the build pipeline, the Converter layer handles multi-format export, the Source Tracking layer detects changes and impacts, and the Migration layer converts between source dialects.
+
+## Contained building blocks
+
+- **CLI Layer** (`cli.py`, `cli_formatting.py`, `cli_payloads.py`, `launcher.py`): Typer-based command-line interface with 11 top-level commands and a `source` subgroup (snapshot, changed, convert), JSON payload construction, and human-readable output formatting
+- **Config Layer** (`config/`): Project configuration model, TOML parsing, default config rendering
+- **Repository Layer** (`repository.py`): Business logic orchestration for init, create, list, check, status
+- **Model Layer** (`model.py`, `errors.py`): Core data structures, validation constants, record lifecycle
+- **Record Type Registry** (`record_types.py`): Record type specifications, directory/template/section mappings, CLI kind aliases
+- **Check Layer** (`checks.py`): Per-record-type content validation including multi-type diagram validation (text/ascii/unicode/svgbob/mermaid) with dialect-specific block detection and line-length checks
+- **Source Ref Validation** (`source_refs.py`): Traceability link normalization and path validation
+- **Storage Layer** (`storage/`): File system access, front matter parsing, source state persistence
+- **Assembly Layer** (`assembly.py`): Jinja2-based document assembly from records and sections
+- **Dialect Layer** (`dialects.py`): Format-neutral markup abstraction (Markdown, AsciiDoc)
+- **Section Rendering Layer** (`section_rendering.py`): Per-record-type rendering via dialects
+- **Render Layer** (`render.py`): Build pipeline facade
+- **Converter Layer** (`converters.py`, `conversion_plan.py`, `formats.py`): Multi-format export planning and execution via pandoc/asciidoctor
+- **Source Tracking Layer** (`source_tracking.py`, `storage/source_state.py`): Change detection and impact analysis
+- **Migration Layer** (`migration.py`): Source dialect conversion (Markdown to AsciiDoc)
+
+## Important interfaces
+
+The primary interface is the CLI (`archledger` console script). The CLI delegates to `cli_payloads.py` for JSON output construction and `cli_formatting.py` for human-readable messages. Internally, the Repository exposes methods that the CLI calls, and the Repository delegates to Storage, Model, Record Type Registry, Check, and Source Ref Validation. Config parsing is handled by the Config Layer independently from Storage. The Render Layer delegates to Assembly and Converters. The Converter Layer uses `conversion_plan.py` to plan each format conversion. Source Tracking is used by the CLI `source` subgroup for snapshot/changed/convert commands.

archledger-0.1.0/.archledger/records/building_blocks/al_0042.md

@@ -0,0 +1,36 @@
+---
+id: al_0042
+type: black_box
+title: CLI Layer
+schema_version: 2
+date: "2026-05-21"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 10
+interfaces:
+  - archledger console script (stdin/stdout)
+location:
+  - archledger/cli.py
+  - archledger/cli_formatting.py
+  - archledger/cli_payloads.py
+  - archledger/launcher.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T05:52:14Z"
+updated_at: "2026-05-21T16:00:00Z"
+source_refs:
+  - archledger/cli.py
+  - archledger/cli_formatting.py
+  - archledger/cli_payloads.py
+  - archledger/launcher.py
+---
+
+The Typer-based CLI exposes top-level commands: `init`, `status`, `paths`, `schema`, `new`, `seed`, `list`, `show`, `read`, `check`, `build`, and the `source` subgroup. The `source` subgroup contains `snapshot`, `changed`, and `convert` for source tracking and dialect migration. Each command resolves the project config, constructs a Repository, and delegates to it. Two output modes are supported: human-readable text (default) and structured JSON (`--json` flag). Error handling maps domain exceptions (`ArchledgerError` subclasses) to appropriate exit codes and error output.
+
+Output is split across three modules: `cli.py` defines Typer commands and dispatches to the Repository, `cli_payloads.py` constructs structured JSON dictionaries from domain result types, and `cli_formatting.py` renders human-readable messages from those payloads. This separation keeps the command definitions thin and testable.
+
+The `source snapshot` and `source changed` commands integrate the source tracking subsystem. The `source convert` command delegates to the migration module for Markdown-to-AsciiDoc source conversion.

archledger-0.1.0/.archledger/records/building_blocks/al_0043.md

@@ -0,0 +1,32 @@
+---
+id: al_0043
+type: black_box
+title: Repository Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 20
+interfaces:
+  - create_record()
+  - list_records()
+  - get_record()
+  - load_all_records()
+  - check()
+  - init()
+  - status()
+location:
+  - archledger/repository.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T05:52:15Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/repository.py
+---
+
+The `ArchitectureRepository` class is the central business logic layer. It orchestrates record creation (allocating IDs via the Record Type Registry, rendering templates, writing files), record loading (parsing front matter, validating fields, normalizing source refs via the Source Ref Validation layer), integrity checks (delegating per-record-type content warnings to the Check Layer, plus cross-reference validation and source contract validation), and initialization (directory scaffolding, section file generation). It holds a Jinja2 environment for template rendering.

archledger-0.1.0/.archledger/records/building_blocks/al_0044.md

@@ -0,0 +1,26 @@
+---
+id: al_0044
+type: black_box
+title: Render Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 30
+interfaces:
+  - build_document()
+location:
+  - archledger/render.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T05:52:15Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/render.py
+---
+
+The render module (`render.py`) is a thin facade that orchestrates the build pipeline. It resolves requested output formats via the formats module, delegates document assembly to the Assembly Layer, and then delegates multi-format conversion to the Converter Layer. The actual rendering logic is split across the Assembly Layer (template orchestration) and the Section Rendering Layer (per-record-type output).

archledger-0.1.0/.archledger/records/building_blocks/al_0045.md

@@ -0,0 +1,33 @@
+---
+id: al_0045
+type: black_box
+title: Storage Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 40
+interfaces:
+  - read_text() / write_text()
+  - read_markdown_front_matter()
+  - resolve_project_paths()
+  - read_source_state() / write_source_state()
+location:
+  - archledger/storage/common.py
+  - archledger/storage/frontmatter.py
+  - archledger/storage/meta.py
+  - archledger/storage/paths.py
+  - archledger/storage/source_state.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T05:52:15Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/storage/
+---
+
+The storage subpackage handles all file system I/O. `paths.py` discovers the project config and resolves directory layout (including `source_state_path` for tracking baselines). `project_config.py` holds the `ProjectConfig` dataclass with all configuration fields (source, build, arc42, skill, tracking). Config parsing and TOML loading now lives in the Config Layer (`config/` subpackage). `frontmatter.py` parses Markdown/AsciiDoc files with YAML front matter into metadata dict and body string, and provides `iter_source_files` for directory enumeration. `meta.py` manages the storage metadata file (`storage.yaml`). `source_state.py` reads and writes source tracking state as JSON. `common.py` provides `write_text`, `read_text`, `ensure_dir`, and `utc_now_iso`.

archledger-0.1.0/.archledger/records/building_blocks/al_0046.md

@@ -0,0 +1,33 @@
+---
+id: al_0046
+type: black_box
+title: Model Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 50
+interfaces:
+  - ArchitectureRecord dataclass
+  - SourceRef dataclass
+  - validate_record()
+  - filename_for()
+  - record_sort_key()
+  - normalize_kind()
+location:
+  - archledger/model.py
+  - archledger/errors.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T05:52:16Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/model.py
+  - archledger/errors.py
+---
+
+The model module defines the core data structures and validation rules. `ArchitectureRecord` is a frozen dataclass holding id, type, title, status, section, order, path, metadata, body, and source_refs. `SourceRef` holds path, symbols, and reason for traceability linking. `validate_record()` checks field types, status values, and ID/filename consistency. Constants for valid formats, status values, and file extension mappings remain in `model.py`. Record type to directory/template/section mappings have been extracted to the Record Type Registry (`record_types.py`). Source ref validation and normalization have been extracted to the Source Ref Validation layer (`source_refs.py`). The `errors.py` module defines the exception hierarchy: `ArchledgerError` base with `ConfigError`, `StorageError`, `FrontMatterError`, `ValidationError`, and `RenderError` subclasses.

archledger-0.1.0/.archledger/records/building_blocks/al_0047.md

@@ -0,0 +1,27 @@
+---
+id: al_0047
+type: black_box
+title: Assembly Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 60
+interfaces:
+  - assemble_document()
+  - assemble_asciidoc_document()
+location:
+  - archledger/assembly.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T12:00:00Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/assembly.py
+---
+
+The assembly module loads all records from the repository, groups them by arc42 section, filters by visibility, selects the correct dialect, and renders a single document using a Jinja2 template (`arc42_document.md.j2` or `arc42_document.adoc.j2`). It delegates to the Section Rendering Layer for per-record-type output formatting. The assembly runs a check first and blocks the build if errors are found.

archledger-0.1.0/.archledger/records/building_blocks/al_0048.md

@@ -0,0 +1,28 @@
+---
+id: al_0048
+type: black_box
+title: Dialect Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 70
+interfaces:
+  - get_dialect()
+  - Dialect base class
+  - MarkdownDialect / AsciiDocDialect
+location:
+  - archledger/dialects.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T12:00:00Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/dialects.py
+---
+
+The dialects module provides a format-neutral abstraction for document rendering. The `Dialect` base class defines methods for headings, tables, bullets, and strong text. `MarkdownDialect` and `AsciiDocDialect` implement these using the respective markup conventions (e.g., `#` vs `=` for headings, `|...|` vs `|===` tables). Both the Assembly Layer and Section Rendering Layer use dialects to produce format-correct output without conditional branching.

archledger-0.1.0/.archledger/records/building_blocks/al_0049.md

@@ -0,0 +1,32 @@
+---
+id: al_0049
+type: black_box
+title: Section Rendering Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 75
+interfaces:
+  - section_body()
+  - building_block_hierarchy()
+  - adr_sections()
+  - quality_scenarios()
+  - risk_table()
+  - glossary_table()
+  - (and other per-type renderers)
+location:
+  - archledger/section_rendering.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T12:00:00Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/section_rendering.py
+---
+
+The section rendering module contains all per-record-type rendering functions. Each function takes a list of `ArchitectureRecord` and a `Dialect`, and returns a format-appropriate string (Markdown or AsciiDoc). Functions include table renderers (quality goals, stakeholders, quality scenarios, risks, glossary), list renderers (constraints, context interfaces), hierarchy renderers (building blocks with white/black boxes and interfaces), and prose renderers (ADRs, runtime scenarios, deployment, concepts, strategy items).

archledger-0.1.0/.archledger/records/building_blocks/al_0050.md

@@ -0,0 +1,32 @@
+---
+id: al_0050
+type: black_box
+title: Converter Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 80
+interfaces:
+  - convert_assembled_document()
+location:
+  - archledger/converters.py
+  - archledger/conversion_plan.py
+  - archledger/formats.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T12:00:00Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/converters.py
+  - archledger/conversion_plan.py
+  - archledger/formats.py
+---
+
+The converter module handles multi-format export. It takes an assembled document (from the Assembly Layer) and produces output in the requested formats. For native format builds (Markdown source to Markdown output, or AsciiDoc source to AsciiDoc output), it does a direct file copy. For other formats, it invokes external converters: pandoc for Markdown-to-HTML/PDF/DOCX/RST/Textile, asciidoctor for AsciiDoc-to-HTML/PDF (direct or via DocBook intermediate), and pandoc for AsciiDoc-to-DOCX/Markdown/RST/Textile (via DocBook). The formats module (`formats.py`) defines the `OutputFormat` enum and resolves requested formats from CLI options and config.
+
+Conversion planning is handled by `conversion_plan.py`, which produces a `ConversionPlan` dataclass for each requested format. Each plan specifies whether the conversion is a native copy, a direct tool invocation, or requires a DocBook intermediate step. Tool resolution uses `shutil.which` by default. The `require_tool()` function raises `RenderError` with install hints when a required converter is unavailable. DocBook intermediates are cleaned up unless `build_keep_intermediate` is set.

archledger-0.1.0/.archledger/records/building_blocks/al_0051.md

@@ -0,0 +1,32 @@
+---
+id: al_0051
+type: black_box
+title: Source Tracking Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 90
+interfaces:
+  - scan_workspace()
+  - diff_source_states()
+  - resolve_impacts()
+location:
+  - archledger/source_tracking.py
+  - archledger/storage/source_state.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T12:00:00Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/source_tracking.py
+  - archledger/storage/source_state.py
+---
+
+The source tracking module detects changes between a baseline snapshot and the current workspace state. `scan_workspace` enumerates tracked files using git or filesystem scanning, computes SHA-256 content hashes, and stores SHA-256-only file entries. It also derives directory hashes and file counts from the scanned file tree. `diff_source_states` compares two snapshots to produce a `ChangeSet` listing added, modified, and deleted files with possible rename detection. `resolve_impacts` cross-references changed files with architecture record `source_refs` to identify impacted records and unlinked changed files.
+
+The storage sub-module (`storage/source_state.py`) handles JSON serialization and deserialization of the source state, persisted alongside `storage.yaml`.

archledger-0.1.0/.archledger/records/building_blocks/al_0052.md

@@ -0,0 +1,26 @@
+---
+id: al_0052
+type: black_box
+title: Migration Layer
+schema_version: 2
+date: "2026-05-20"
+body_format: markdown
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 95
+interfaces:
+  - convert_sources()
+location:
+  - archledger/migration.py
+fulfilled_requirements: []
+risks: []
+tags: []
+created_at: "2026-05-20T12:00:00Z"
+updated_at: "2026-05-20T12:00:00Z"
+source_refs:
+  - archledger/migration.py
+---
+
+The migration module converts source fragments from one dialect to another. Currently supports Markdown-to-AsciiDoc conversion. It iterates over all section and record files, converts the body using pandoc (falling back to keeping the original body if pandoc is unavailable), updates the YAML front matter to reflect the new body format, and optionally replaces the original files. It also rewrites the project config to target the new source format.

archledger-0.1.0/.archledger/records/building_blocks/al_0053.md

@@ -0,0 +1,34 @@
+---
+schema_version: 2
+id: al_0053
+type: black_box
+title: Config Layer
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 105
+date: "2026-05-21"
+interfaces:
+  - load_project_config()
+  - render_default_config()
+  - ProjectConfig dataclass
+location:
+  - archledger/config/__init__.py
+  - archledger/config/model.py
+  - archledger/config/parse.py
+  - archledger/config/render.py
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-05-21T11:30:43Z"
+updated_at: "2026-05-22T07:00:00Z"
+source_refs:
+  - path: archledger/config/
+    reason: Config subpackage with model, parse, render
+---
+
+The `config` subpackage owns all project configuration concerns. `config/model.py` defines frozen dataclasses for each configuration domain: `SourceConfig`, `BuildConfig` (with nested `BuildOutputConfig`), `Arc42Config`, `SkillConfig`, `TrackingConfig`, and the unified `ProjectConfig` facade that composes them via properties. `config/parse.py` loads and validates `archledger.toml` using `tomllib` (or `tomli` for Python < 3.11), with strict key validation and environment variable expansion. `config/render.py` generates default configuration files for `archledger init`. The subpackage re-exports key types from `__init__.py`.
+
+The `[diagrams]` section supports five diagram types (`text`, `ascii`, `unicode`, `svgbob`, `mermaid`) and six renderers (`pass-through`, `mermaid-cli`, `svgbob`, `goat`, `asciidoctor-diagram`, `kroki`). The default diagram type is `text`, ensuring that new diagram records produce readable text-based diagrams in native builds without any external tooling.

archledger-0.1.0/.archledger/records/building_blocks/al_0054.md

@@ -0,0 +1,36 @@
+---
+schema_version: 2
+id: al_0054
+type: black_box
+title: Record Type Registry
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 115
+date: "2026-05-21"
+interfaces:
+  - RECORD_TYPES registry
+  - CLI_KIND_ALIASES
+  - RecordTypeSpec dataclass
+location:
+  - archledger/record_types.py
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-05-21T11:31:25Z"
+updated_at: "2026-05-22T07:00:00Z"
+source_refs:
+  - archledger/record_types.py
+  - path: archledger/templates/records/diagram.md.j2
+    reason: Diagram template scaffolding per diagram type
+  - path: archledger/templates/records/diagram.adoc.j2
+    reason: Diagram template scaffolding per diagram type
+---
+
+The `record_types.py` module is the central registry for all arc42 record types. It defines `RecordTypeSpec`, a frozen dataclass mapping each record kind to its directory name, filename prefix, default section, template basename, CLI aliases, default status/level, and a context factory function. The `RECORD_TYPES` dictionary provides the authoritative lookup. `CLI_KIND_ALIASES` maps alternative names (e.g., `qg` for `quality_goal`) for the CLI.
+
+The diagram context factory defaults `diagram_type` to `"text"` (previously `"mermaid"`). Supported diagram types are `text`, `ascii`, `unicode`, `svgbob`, and `mermaid`. The default can be overridden per-project via the `[diagrams].default_type` config key, which the Repository Layer passes through when creating diagram records.
+
+This module was extracted from `model.py` to keep the model focused on data structures while record type configuration lives in one discoverable location.

archledger-0.1.0/.archledger/records/building_blocks/al_0055.md

@@ -0,0 +1,30 @@
+---
+schema_version: 2
+id: al_0055
+type: black_box
+title: Check Layer
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 125
+date: "2026-05-21"
+interfaces:
+  - content_warnings()
+location:
+  - archledger/checks.py
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-05-21T11:32:00Z"
+updated_at: "2026-05-22T07:00:00Z"
+source_refs:
+  - archledger/checks.py
+---
+
+The `checks.py` module provides per-record-type content validation beyond structural checks. The main entry point is `content_warnings()`, which returns a list of warning strings for a given `ArchitectureRecord`. It dispatches to type-specific checkers registered in `_CONTENT_WARNING_CHECKERS`: quality goals require scenarios, stakeholders require expectations, constraints require impact and valid categories, ADRs require Context/Decision/Consequences sections and deciders, quality scenarios require measurable response measures, risks require valid severity/probability and mitigation, and so on. It also detects placeholder text in record bodies and cross-dialect syntax contamination (e.g., AsciiDoc headings in Markdown records).
+
+For diagram records, the check layer validates the `diagram_type` field against the allowed set (`text`, `ascii`, `unicode`, `svgbob`, `mermaid`), verifies that the body contains the appropriate fenced or literal block for the declared type and source dialect (Markdown uses ` ```textdiagram `/` ```svgbob `/` ```mermaid ` fences; AsciiDoc uses `[source,text]`+`----`, `[svgbob]`+`....`, or `[mermaid]`+`....` blocks), and checks for empty diagram blocks. Text-type diagrams (`text`, `ascii`, `unicode`) receive an additional line-length check (120 characters max) to keep diagrams readable in terminals and Git diffs.
+
+This module was extracted from `repository.py` to isolate validation logic.

archledger-0.1.0/.archledger/records/building_blocks/al_0056.md

@@ -0,0 +1,27 @@
+---
+schema_version: 2
+id: al_0056
+type: black_box
+title: Source Ref Validation
+status: accepted
+section: building_block_view
+level: 1
+parent: al_0041
+order: 135
+date: "2026-05-21"
+interfaces:
+  - normalize_source_refs()
+  - validate_relative_posix_path()
+location:
+  - archledger/source_refs.py
+fulfilled_requirements: []
+risks: []
+tags: []
+body_format: markdown
+created_at: "2026-05-21T11:32:28Z"
+updated_at: "2026-05-21T11:32:28Z"
+source_refs:
+  - archledger/source_refs.py
+---
+
+The `source_refs.py` module handles validation and normalization of source traceability links on architecture records. `validate_relative_posix_path()` enforces that source ref paths are relative, use POSIX separators, and do not traverse parent directories. `normalize_source_refs()` processes the raw `source_refs` list from YAML front matter, supporting both shorthand string syntax (`path/to/file.py#SymbolName`) and full mapping syntax with explicit path, symbols, and reason. It verifies that referenced paths and directories actually exist in the workspace. `RelativePosixPathError` provides structured error reporting for invalid paths. This module was extracted from `model.py` to keep source ref validation independent from the core data model.

archledger-0.1.0/.archledger/records/concepts/al_0071.md

@@ -0,0 +1,19 @@
+---
+id: al_0071
+type: concept
+title: Record lifecycle and status
+schema_version: 2
+date: "2026-05-21"
+body_format: markdown
+status: accepted
+section: cross_cutting_concepts
+order: 10
+applies_to:
+  - Repository Layer
+  - CLI Layer
+source_refs:
+  - README.md
+  - archledger/section_rendering.py
+---
+
+Every record has a status field that controls its lifecycle: `draft` (incomplete, excluded from default builds), `proposed` (visible but not formally confirmed), `accepted` (confirmed, included by default), `deprecated` (visible but no longer preferred), and `superseded` (hidden unless explicitly included). The `check` command warns about draft records and empty sections. The `build` command only includes records with visible statuses by default; `--include-draft` and `--include-superseded` flags override this.

archledger-0.1.0/.archledger/records/concepts/al_0072.md

@@ -0,0 +1,22 @@
+---
+id: al_0072
+type: concept
+title: Config discovery and path resolution
+schema_version: 2
+date: "2026-05-21"
+body_format: markdown
+status: accepted
+section: cross_cutting_concepts
+order: 20
+applies_to:
+  - Storage Layer
+  - CLI Layer
+  - Config Layer
+source_refs:
+  - README.md
+  - archledger/section_rendering.py
+---
+
+archledger discovers its project configuration by walking up from the current directory looking for `archledger.toml` or `.archledger.toml`. The `archledger_dir` setting in the config can be relative (resolved from the config file's directory) or absolute (used as-is). This allows the storage directory to live outside the source tree, for example in a separate state repository.
+
+Config parsing is handled by the Config Layer (`config/` subpackage): `config/parse.py` loads and validates the TOML file, `config/model.py` defines typed dataclasses for each configuration domain (source, build, arc42, skill, tracking), and `config/render.py` generates default configuration files for `archledger init`. Path resolution happens in `storage/paths.py`.

archledger-0.1.0/.archledger/records/concepts/al_0073.md

@@ -0,0 +1,22 @@
+---
+id: al_0073
+type: concept
+title: Dialect abstraction for dual-source support
+schema_version: 2
+date: "2026-05-22"
+body_format: markdown
+status: accepted
+section: cross_cutting_concepts
+order: 30
+applies_to:
+  - Dialect Layer
+  - Section Rendering Layer
+  - Assembly Layer
+source_refs:
+  - README.md
+  - archledger/section_rendering.py
+---
+
+archledger supports both Markdown and AsciiDoc as first-class source formats. The dialect abstraction (`dialects.py`) defines a `Dialect` base class with methods for headings, tables, bullets, and strong text. `MarkdownDialect` and `AsciiDocDialect` implement these using their respective markup conventions. All rendering code in the Section Rendering Layer and Assembly Layer uses dialects rather than hardcoded markup, ensuring that a single rendering codebase produces correct output for both source formats. Templates exist in both `.md.j2` and `.adoc.j2` variants.
+
+For diagram records, the dialect determines the block syntax used in both templates and validation: Markdown diagrams use fenced code blocks (` ```textdiagram `, ` ```svgbob `, ` ```mermaid `), while AsciiDoc diagrams use literal or source blocks (`[source,text]`+`----`, `[svgbob]`+`....`, `[mermaid]`+`....`). Text-based diagram types (`text`, `ascii`, `unicode`) use the same fenced/literal block syntax within each dialect, differing only in the content characters used.

archledger-0.1.0/.archledger/records/concepts/al_0074.md

@@ -0,0 +1,20 @@
+---
+id: al_0074
+type: concept
+title: Source tracking and change impact analysis
+schema_version: 2
+date: "2026-05-21"
+body_format: markdown
+status: accepted
+section: cross_cutting_concepts
+order: 40
+applies_to:
+  - Source Tracking Layer
+  - CLI Layer
+  - Repository Layer
+source_refs:
+  - README.md
+  - archledger/section_rendering.py
+---
+
+The source tracking subsystem allows agents to detect which workspace files changed since the last baseline snapshot and which architecture records are impacted. A snapshot (`archledger source snapshot`) records SHA-256 hashes of all tracked files. The `source changed` command computes the diff between the baseline and current state, then cross-references changed files with record `source_refs` to identify impacted records and sections. Files that changed but have no linked records are reported as unlinked. This enables agents to update only the documentation affected by code changes.

archledger-0.1.0/.archledger/records/concepts/al_0075.md

@@ -0,0 +1,31 @@
+---
+schema_version: 2
+id: al_0075
+type: concept
+title: Multi-type diagram records
+status: accepted
+section: cross_cutting_concepts
+order: 50
+date: "2026-05-22"
+applies_to:
+  - Record Type Registry
+  - Check Layer
+  - Config Layer
+  - Assembly Layer
+body_format: markdown
+created_at: "2026-05-22T07:07:32Z"
+updated_at: "2026-05-22T07:07:32Z"
+source_refs:
+  - archledger/record_types.py
+  - archledger/checks.py
+  - archledger/templates/records/diagram.md.j2
+  - archledger/templates/records/diagram.adoc.j2
+---
+
+Diagram records support five types: `text`, `ascii`, `unicode`, `svgbob`, and `mermaid`. The default type is `text`, configured via `[diagrams].default_type` in `archledger.toml` and overridable per-record with `--diagram-type` on the CLI.
+
+Text-based types (`text`, `ascii`, `unicode`) store diagram content as plain text in fenced Markdown blocks (` ```textdiagram `) or AsciiDoc literal blocks (`[source,text]` + `----`). They render directly in native builds without external tools, are readable in Git diffs and terminals, and are validated with a 120-character line-length limit.
+
+`svgbob` uses the svgbob markup syntax in dedicated fenced/literal blocks. `mermaid` uses Mermaid syntax in dedicated fenced/literal blocks and requires an external renderer (mermaid-cli, asciidoctor-diagram, or Kroki) for image output.
+
+The Check Layer validates diagram type against the allowed set, verifies that the body contains the correct block syntax for the declared type and dialect, checks for empty blocks, and enforces line-length limits on text diagrams. Templates produce type-appropriate scaffolding when creating new diagram records.