statecraft.
Catalog/spec-spine

036-declared-state-dir

`layout.state_dir`: a declared, ungoverned tool-state root

Lifecycle approvedImplementation completeVerification unknownQualification unknown

A repo governed by spec-spine increasingly hosts tooling that keeps state inside it: a build daemon's journal, a local database, captured transcripts, attestation bundles. There is nowhere agreed to put any of it. Every such tool invents a directory, and every invented directory is then a surprise to the gates: `couple` sees changed files no spec claims and refuses the merge under `require_ownership`, `index coverage` counts them as untraced debt, and the resolver walks them. The adopter's only recourse is to keep appending private paths to `bypass_prefixes` and `resolver_exclusions`, one list per concern, none of which states what the directory *is*. This spec adds `layout.state_dir`: a single declared root, unset by default, that spec-spine agrees to know about and refuses to govern. Declared means the gates recognize it (bypassed by `couple`, excluded from coverage classification and from the resolver scan, and never hashed); ungoverned means spec-spine never reads its contents, never writes into it, and refuses a spec that tries to claim a unit inside it, which `lint` reports as `L-006`, a contradiction rather than a precedence question resolved silently in either direction. Unset by default, so no existing repo changes behavior.

Read the full pinned specification ↗

Relationships

Claimed units

  • extends
    {
  "nature": "additive",
  "spec": "000-spec-spine-bootstrap",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/src/config.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "000-spec-spine-bootstrap",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-types/tests/config.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "005-coupling-gate",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/couple.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "005-coupling-gate",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/tests/couple.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "004-codebase-index",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/index.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "004-codebase-index",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/symbols.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "022-index-sharding",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/shard.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "029-ownership-coverage",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/coverage.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "029-ownership-coverage",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/tests/coverage.rs"
  }
}
  • extends
    {
  "nature": "additive",
  "spec": "003-conformance-lint",
  "unit": {
    "kind": "file",
    "path": "crates/spec-spine-core/src/lint.rs"
  }
}

Source headings

  1. 036: `layout.state_dir`
  2. 1. Purpose
  3. 2. Territory
  4. 3. Behavior
  5. 3.1 Unset by default
  6. 3.2 Declared: the gates recognize it
  7. 3.3 Ungoverned: spec-spine never reads or writes it
  8. 3.4 A claim inside `state_dir` is a contradiction, and `lint` says so
  9. 3.5 Relationship to the existing lists
  10. 3.6 Tests (minimum)
  11. 4. Out of scope
  12. 5. Resolved decisions

Frozen anchors

No frozen anchors declared.