Skip to content

ADR: A project path_conventions override precedes the doctrine default, without changing the blocking policy

Status: Accepted

Date: 2026-08-28

Deciders: Mission accept-path-convention-override-01M14P41 (mission_id 01M14P41); folds #3016 and #2330 Item 1; in-radius follow-on to the honesty mission #3730/#3085 (merged as PR #3783).

Technical Story: #3016. Planning contracts under kitty-specs/accept-path-convention-override-01M14P41/ — spec.md, contracts/config-schema.md, contracts/precedence-contract.md, data-model.md.


Context and Problem Statement

The honesty mission #3783 made mission-path acceptance blocking by default: when a mission-type doctrine convention names a directory (e.g. software-dev’s workspace: src/) and that directory does not exist, spec-kitty accept blocks with a path_violations finding that names two honest levers — accept --lenient to downgrade to advisory, or adopt the convention — and never a bare mkdir.

That policy is correct, but it left a real project honestly stuck. A repository whose source root is genuinely not src/ — a Django project rooted at apps/, a Go project at internal/ — has no way to tell accept what its layout actually is. The only escapes were to fabricate an empty src/ (dishonest, exactly what #3783 set out to stop) or to run every accept with --lenient (throws away the honest signal for every key, not just the mislabelled one).

The missing piece is a value channel: a way for a project to declare “my workspace is apps/, not src/” so that accept validates against the project’s real layout — while the strict/lenient policy stays exactly as #3783 settled it. This ADR records how that override resolves, why it is remap-only, why one key is excluded, and what the deliberate next step is.

Decision Drivers

  • Non-reversal of #3783 (C-001, C-009). The override is a value supplied to the existing validator; it must not reintroduce advisory-by-default or weaken any settled #3783 assertion.
  • Honest, non-fakeable acceptance (SC-006). Overriding workspace to apps/ when apps/ is absent must still block under strict — the override changes the resolved directory, never the decision.
  • Single canonical authority (Directive 044). One frozenset of valid path keys, reused by both MissionConfig validation and the override reader; no second, drifting list.
  • Routing safety (C-010). The path-convention value and the mission artifact-token vocabulary are coupled at the routing seam; the override must not be able to flip an artifact-routed key’s resolution surface.
  • Fail-closed on malformed config, lenient on absent config (FR-008). A typo or a wrong-typed value is an operator error worth a clear, actionable raise; an absent section or an unreadable file must never break accept.

Decision Outcome

A project may declare project.path_conventions in .kittify/config.yaml — a mapping of path-convention key to the directory that key resolves to in this repository. validate_mission_paths applies it remap-only and ahead of the mission-type doctrine default, then runs the unchanged #3783 blocking policy against the resolved directory.

Precedence order (per key)

  1. Project override — if the mission declares key in mission.config.paths, key is not artifact-routed, and project.path_conventions[key] is set → the resolved directory is the override.
  2. Doctrine default — otherwise the resolved directory is mission.config.paths[key] (the mission-type convention).
  3. Blocking-by-default + --lenient — the resolved directory (whichever of 1 or 2 won) is then subject to the unchanged #3783 policy: absent under strict → blocking path_violations; absent under --lenient → advisory warning. The override changes which directory is checked, never whether absence blocks (C-001).

Research missions still apply their path_prefix via _prefix_required_path after the remap, unchanged. The merge therefore happens on declared before the required_paths prefix comprehension and before the artifact-token membership check, so an overridden key is prefixed for research missions and never bypasses artifact routing (C-008).

Remap-only

The override may only remap a key the mission already declares; it never introduces a new required path. An override for a key the mission does not declare is ignored. This keeps the set of required paths under the mission-type doctrine’s control — the project chooses where a required directory lives, never which directories are required.

Deliberate non-reversal of #3783

This mission supplies a value and nothing else. The strict/lenient decision, the path_violations payload shape, and the two-lever remediation string are all inherited verbatim from #3783; the mission’s test coverage is strictly additive and deletes or weakens no #3783 assertion (C-009). The non-fakeable discriminator (SC-006) is the proof: override.workspace = apps/ with apps/ absent still blocks under strict. An implementation that silently demoted conventions to advisory would fail that test — which is exactly the #3783 regression this ADR forbids.

Why deliverables is excluded — the value ↔ artifact-token coupling (C-010)

Routing at the paths seam is decided by whether _normalize_path_token(declared[key]) is a member of the mission’s artifact tokens. Software-dev’s deliverables default value is contracts/, and contracts/ is a mission artifact token — so deliverables resolves against the mission’s feature_dir, not the repository root, and carries a mission-surface artifact check. Allowing an override to change deliverables’ value would flip that resolution surface from feature_dir to project_root and drop the artifact check.

The path-convention value and the artifact-token vocabulary are therefore coupled: overriding an artifact-routed key is not a repo-layout remap, it is a routing change. Rather than special-case the routing seam, the override vocabulary is restricted to repo-layout keys and excludes any key whose default value is a mission artifact token. Concretely that is deliverables, the sole such key across the four built-in mission types; the reader excludes it by name (ARTIFACT_ROUTED_KEYS) and warns-and-ignores an override that targets it. The override thus never reaches an artifact-routed key, and the routing check is provably unaffected.

The remaining vocabulary is the repo-layout subset of the canonical valid path keys — {workspace, tests, documentation, data} — validated against the single frozenset VALID_PATH_KEYS that MissionConfig also uses.

Fail-closed scope

Validation is fail-closed on the section shape, lenient on the file:

  • A key outside VALID_PATH_KEYS (a typo) → raise PathConventionsConfigError naming the offending key and the known keys (FR-007a).
  • A section present but not a mapping, or a non-string / null value → raise, naming the offending key (FR-008).
  • An artifact-routed key (deliverables) → warn and ignore (C-010).
  • An absent path_conventions key → {}.
  • A missing, unreadable, or corrupt .kittify/config.yaml → {} (lenient), matching the co-resident section readers.

The reader also reads only the project.path_conventions subkey — never the whole project: block, which carries identity fields (uuid/slug/node_id/build_id) that must not be rejected (C-011). The config is read once per accept run; there is no per-key filesystem read (NFR-002).

Layout auto-detection (#2744) is the deliberate next step

This ADR deliberately stops at an explicit operator declaration. It does not infer a project’s layout from filesystem signals (manage.py → Django apps/, go.mod → Go internal/), and it does not relax accept for research plan/tasks/WP shape. Automatic layout auto-detection is tracked separately as #2744 and is the intended follow-on: the explicit project.path_conventions channel this ADR establishes is the substrate an auto-detector would populate, not a competitor to it. Shipping the explicit channel first keeps the honesty contract auditable (the operator states the layout; nothing is guessed) before inference is layered on top.

Considered Options

  • A. Keep only --lenient. Rejected: throws away the honest signal for every key to fix one mislabelled key, and still leaves no record of the project’s real layout.
  • B. Explicit project path_conventions value override, remap-only, artifact-routed keys excluded (chosen). Fixes the honestly-stuck project without touching the #3783 policy.
  • C. Auto-detect the layout now (#2744). Deferred, not rejected: valuable, but inference before an explicit channel exists makes the honesty contract harder to audit. It builds on B.

Consequences

Positive

  • A project whose real source root is not src/ accepts honestly against an untouched working tree — no fabricated src/, no blanket --lenient.
  • The #3783 blocking policy, payload, and remediation string are unchanged and re-proven by additive tests.
  • One canonical VALID_PATH_KEYS frozenset serves both mission-config validation and the override reader.

Negative

  • Operators must know the project.path_conventions config surface exists; until #2744 lands, the layout is stated by hand rather than inferred.

Neutral

  • deliverables remains doctrine-owned and un-overridable by design; a project cannot relocate an artifact-routed key through this channel.

Confirmation

  • Precedence and remap-only behaviour: tests/agent/test_validators_unit.py (override resolves apps/, no src/ violation; SC-006 declared-but-absent still blocks under strict).
  • Non-reversal of #3783: tests/specify_cli/acceptance/test_acceptance_support.py test_no_override_still_blocks_strict pins the exact path_violations payload and full format_errors() string beside the untouched test_lenient_downgrades_path_conventions_to_warning; the accept-boundary fail-closed and one-read cases live in the same file.
  • Reader contract (subkey-only C-011, typo/malformed/lenient, one read NFR-002): tests/specify_cli/config/test_path_conventions_reader.py.

More Information

  • Builds on the honesty settlement PR #3783 (#3730/#3085); this ADR is explicitly additive to it.
  • Deferred follow-on: layout auto-detection via manage.py/go.mod signals and research-shape accept relaxation, tracked as #2744.
  • Reader: src/specify_cli/config/path_conventions.py. Merge site: src/specify_cli/validators/paths.py (validate_mission_paths, _remap_declared_paths). Seam wiring: src/specify_cli/acceptance/summary_core.py (evaluate_path_conventions). Canonical key set: src/specify_cli/mission.py (VALID_PATH_KEYS).

Amendment 2026-11-10: no mkdir remedy for a remappable path (#7512)

A missing path whose key the project can remap (any key outside ARTIFACT_ROUTED_KEYS, such as src/, tests/ or docs/) no longer gets a mkdir -p suggestion, in the strict failure or the --lenient warning: an empty directory passes the check without making it true. accept --lenient and the project.path_conventions remap are the remedies named for it, and the --lenient warning now carries the same remap guidance. A missing Mission artifact path (deliverables) keeps its mkdir -p suggestion, and so does every path in path_prefix mode (research Missions): there the prefixed paths sit in the Mission’s own deliverables directory, are Mission output rather than build layout, and are not offered the remap. Which paths are checked, and whether a missing path blocks, is unchanged, so a plain Python project whose src/ is really missing still blocks, but no longer sees a mkdir hint.

Amendment 2026-11-20: per-Mission-type sections and narrow waivers (#7566, #7748)

Mission path-conventions-per-type-01M7VRQM. A plain project.path_conventions key remapped the path for every Mission type that declared it, so a repository could not change one type’s layout without moving the others (#7748). And the only in-command escape from a path miss, accept --lenient, also skipped the work-package metadata checks (#7566).

Per-type sections

A mapping value under project.path_conventions is a per-type section, keyed by a Mission type id; a string value keeps its plain meaning. The value’s shape decides, so documentation (both a path key and a Mission type) is a plain value when it is a string and the documentation type’s section when it is a mapping.

project:
path_conventions:
workspace: apps/ # every Mission type that declares workspace
software-dev:
workspace: packs/ # software-dev Missions only

For a Mission of type T and a key k the Mission declares, the resolved directory is:

  1. the Mission type default, when k is artifact-routed (deliverables);
  2. otherwise project.path_conventions.T.k, when set;
  3. otherwise project.path_conventions.k, when set;
  4. otherwise the Mission type default.

T is the Mission’s meta.json mission_type (software-dev when absent), the value the Mission itself is loaded from. The remap is still remap-only, research’s path_prefix still applies after it, and the blocking decision is unchanged: a remap to a missing directory still blocks.

Fail-closed rules extend to sections: an id outside the project’s layered Mission type roster (built-in, org, project), a section that is not a mapping, an unknown key, and a non-string, blank, absolute or .. value each raise PathConventionsConfigError. When a section exists and the roster cannot be read, that also raises. deliverables inside a section is warned about and ignored, as in the plain form. The roster is read only when a section exists.

Remedy order

The failure text now reads, in order: the misses; the per-type remap snippet for the failing Mission type; the two narrow waivers, then accept --lenient; the mission.yaml copy, as a last resort that freezes the Mission type definition; and mkdir -p only for real deliverables (Mission artifact and research deliverable paths), with the contracts: none waiver named beside contracts/. --lenient still precedes every mkdir -p (#3783), and no remappable path gets one (#7512). The advisory text keeps the remap and the last-resort line and drops the waiver lines.

Narrow waivers

Both make the misses of remappable layout paths warnings while strict metadata validation is unchanged. Neither waives a missing Mission artifact such as contracts/: that still blocks unless the Mission declares the #5298 "contracts": "none" waiver.

  • Per run: accept --waive-path-conventions --waive-reason "<why>" (forwarded by agent mission accept). A missing or blank reason, or a reason without the flag, is refused before any work. The reason is recorded as path_conventions_waived on the acceptance history entry. orchestrator-api has no per-run waiver.
  • Per Mission: "path_conventions": "waived" with a non-empty "path_conventions_rationale" in meta.json, read by core.paths.read_path_conventions_waiver_from_meta, which shares the #5298 contracts waiver’s fail-closed rules. Every accept path honors it, orchestrator-api included (operator ruling Q4), and the rationale is printed in the accept warnings. Trust model: anyone who can write the Mission’s meta.json can set it, the same trust model as the contracts waiver; the printed rationale and the committed meta.json keep it auditable.

The strict failure text names the per-run flag on every path; on orchestrator-api, use the meta.json declaration instead.