Source tracking

Snapshots

snapshot stores a baseline of the tracked workspace files:

archledger --json source snapshot --reason after-archledger-update

source-state.json stores a monotonic snapshot version and SHA-256 content hashes only for files. It does not persist timestamps, mtimes, or file sizes. Directory hashes are derived from file hashes after scanning.

Changes

changed compares the current workspace against the stored baseline:

archledger --json source changed
archledger --json source changed --fail-on-unlinked
archledger --json source changed --include-drafts

Results report baseline and current versions rather than scan dates.

If [tracking].enabled = false, both commands fail explicitly instead of creating or reading misleading tracking state.

Linking source_refs

When a fragment documents concrete implementation artifacts, add source_refs that point at relative workspace paths:

source_refs:
  - archledger/repository.py#ArchitectureRepository
  - path: archledger/storage/project_config.py
    symbols:
      - ProjectConfig
      - load_project_config
    reason: "Tracking configuration validation"
  - path: archledger/templates/
    reason: "Bundled templates"

Use POSIX separators, keep the paths relative to the workspace root, and end directory references with /.

Recommended workflow

Use tracking as a repeatable drift loop instead of a one-off report:

archledger --json source changed
archledger --json source changed --fail-on-unlinked
archledger --json read --body --include-drafts
archledger --json check --strict
archledger --json source snapshot --reason after-archledger-update

In practice:

1. Add source_refs when a fragment describes real code, configuration, or directories.

2. Run changed to see what moved since the last accepted baseline.

3. Update only the impacted fragments and validate them with check --strict.

4. Record a fresh snapshot only after the documentation update is complete and all validation passes.

Canonical source tracking scans the project root and excludes the complete .ledger/** tree, including .ledger/archledger/data/source-state.json. Tracking state is stored relative to the Archledger data mount, not relative to the nested stable configuration file.