<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-08-28-1-project-path-convention-override-precedes-doctrine/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-28-1-project-path-convention-override-precedes-doctrine/</id>
  <title>ADR: A project path_conventions override precedes the doctrine default, without changing the blocking policy</title>
  <updated>2026-11-20T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-08-28-1-project-path-convention-override-precedes-doctrine/"/>
  <summary>A project path_conventions override remaps resolved accept directories ahead of the mission-type doctrine default, leaving the #3783 blocking policy unchanged.</summary>
  <content type="html">&lt;span id=&quot;adr-a-project-path_conventions-override-precedes-the-doctrine-default-without-changing-the-blocking-policy&quot;&gt;&lt;/span&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-08-28&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Mission &lt;code dir=&quot;auto&quot;&gt;accept-path-convention-override-01M14P41&lt;/code&gt; (mission_id
&lt;code dir=&quot;auto&quot;&gt;01M14P41&lt;/code&gt;); folds #3016 and #2330 Item 1; in-radius follow-on to the honesty mission #3730/#3085
(merged as PR #3783).&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; #3016. Planning contracts under
&lt;code dir=&quot;auto&quot;&gt;kitty-specs/accept-path-convention-override-01M14P41/&lt;/code&gt; — &lt;code dir=&quot;auto&quot;&gt;spec.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;contracts/config-schema.md&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;contracts/precedence-contract.md&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;data-model.md&lt;/code&gt;.&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;The honesty mission #3783 made mission-path acceptance &lt;strong&gt;blocking by default&lt;/strong&gt;: when a mission-type
doctrine convention names a directory (e.g. software-dev’s &lt;code dir=&quot;auto&quot;&gt;workspace: src/&lt;/code&gt;) and that directory does
not exist, &lt;code dir=&quot;auto&quot;&gt;spec-kitty accept&lt;/code&gt; blocks with a &lt;code dir=&quot;auto&quot;&gt;path_violations&lt;/code&gt; finding that names two honest levers —
&lt;code dir=&quot;auto&quot;&gt;accept --lenient&lt;/code&gt; to downgrade to advisory, or adopt the convention — and never a bare &lt;code dir=&quot;auto&quot;&gt;mkdir&lt;/code&gt;.&lt;/p&gt;
&lt;p&gt;That policy is correct, but it left a real project honestly stuck. A repository whose source root is
genuinely not &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; — a Django project rooted at &lt;code dir=&quot;auto&quot;&gt;apps/&lt;/code&gt;, a Go project at &lt;code dir=&quot;auto&quot;&gt;internal/&lt;/code&gt; — has no way to
tell accept what its layout actually is. The only escapes were to fabricate an empty &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; (dishonest,
exactly what #3783 set out to stop) or to run every accept with &lt;code dir=&quot;auto&quot;&gt;--lenient&lt;/code&gt; (throws away the honest
signal for every key, not just the mislabelled one).&lt;/p&gt;
&lt;p&gt;The missing piece is a &lt;strong&gt;value channel&lt;/strong&gt;: a way for a project to declare “my &lt;code dir=&quot;auto&quot;&gt;workspace&lt;/code&gt; is &lt;code dir=&quot;auto&quot;&gt;apps/&lt;/code&gt;, not
&lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;” so that accept validates against the project’s real layout — while the strict/lenient &lt;em&gt;policy&lt;/em&gt;
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.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Non-reversal of #3783 (C-001, C-009).&lt;/strong&gt; The override is a &lt;em&gt;value&lt;/em&gt; supplied to the existing
validator; it must not reintroduce advisory-by-default or weaken any settled #3783 assertion.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Honest, non-fakeable acceptance (SC-006).&lt;/strong&gt; Overriding &lt;code dir=&quot;auto&quot;&gt;workspace&lt;/code&gt; to &lt;code dir=&quot;auto&quot;&gt;apps/&lt;/code&gt; when &lt;code dir=&quot;auto&quot;&gt;apps/&lt;/code&gt; is absent
must &lt;em&gt;still block&lt;/em&gt; under strict — the override changes the resolved directory, never the decision.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority (Directive 044).&lt;/strong&gt; One frozenset of valid path keys, reused by both
&lt;code dir=&quot;auto&quot;&gt;MissionConfig&lt;/code&gt; validation and the override reader; no second, drifting list.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Routing safety (C-010).&lt;/strong&gt; The path-convention &lt;em&gt;value&lt;/em&gt; 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.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Fail-closed on malformed config, lenient on absent config (FR-008).&lt;/strong&gt; 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.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;A project may declare &lt;code dir=&quot;auto&quot;&gt;project.path_conventions&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; — a mapping of path-convention
key to the directory that key resolves to in &lt;em&gt;this&lt;/em&gt; repository. &lt;code dir=&quot;auto&quot;&gt;validate_mission_paths&lt;/code&gt; applies it
&lt;strong&gt;remap-only&lt;/strong&gt; and &lt;strong&gt;ahead of&lt;/strong&gt; the mission-type doctrine default, then runs the unchanged #3783 blocking
policy against the resolved directory.&lt;/p&gt;
&lt;h3 id=&quot;precedence-order-per-key&quot;&gt;Precedence order (per key)&lt;/h3&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Project override&lt;/strong&gt; — if the mission declares &lt;code dir=&quot;auto&quot;&gt;key&lt;/code&gt; in &lt;code dir=&quot;auto&quot;&gt;mission.config.paths&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;key&lt;/code&gt; is not
artifact-routed, and &lt;code dir=&quot;auto&quot;&gt;project.path_conventions[key]&lt;/code&gt; is set → the resolved directory is the override.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Doctrine default&lt;/strong&gt; — otherwise the resolved directory is &lt;code dir=&quot;auto&quot;&gt;mission.config.paths[key]&lt;/code&gt; (the
mission-type convention).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Blocking-by-default + &lt;code dir=&quot;auto&quot;&gt;--lenient&lt;/code&gt;&lt;/strong&gt; — the resolved directory (whichever of 1 or 2 won) is then
subject to the &lt;em&gt;unchanged&lt;/em&gt; #3783 policy: absent under strict → blocking &lt;code dir=&quot;auto&quot;&gt;path_violations&lt;/code&gt;; absent
under &lt;code dir=&quot;auto&quot;&gt;--lenient&lt;/code&gt; → advisory warning. The override changes &lt;em&gt;which directory&lt;/em&gt; is checked, never
&lt;em&gt;whether absence blocks&lt;/em&gt; (C-001).&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;Research missions still apply their &lt;code dir=&quot;auto&quot;&gt;path_prefix&lt;/code&gt; via &lt;code dir=&quot;auto&quot;&gt;_prefix_required_path&lt;/code&gt; after the remap, unchanged.
The merge therefore happens on &lt;code dir=&quot;auto&quot;&gt;declared&lt;/code&gt; &lt;strong&gt;before&lt;/strong&gt; the &lt;code dir=&quot;auto&quot;&gt;required_paths&lt;/code&gt; prefix comprehension and
&lt;strong&gt;before&lt;/strong&gt; the artifact-token membership check, so an overridden key is prefixed for research missions
and never bypasses artifact routing (C-008).&lt;/p&gt;
&lt;h3 id=&quot;remap-only&quot;&gt;Remap-only&lt;/h3&gt;
&lt;p&gt;The override may only &lt;strong&gt;remap a key the mission already declares&lt;/strong&gt;; 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 &lt;em&gt;where&lt;/em&gt; a required directory lives, never
&lt;em&gt;which&lt;/em&gt; directories are required.&lt;/p&gt;
&lt;h3 id=&quot;deliberate-non-reversal-of-3783&quot;&gt;Deliberate non-reversal of #3783&lt;/h3&gt;
&lt;p&gt;This mission supplies a value and nothing else. The strict/lenient decision, the &lt;code dir=&quot;auto&quot;&gt;path_violations&lt;/code&gt;
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: &lt;code dir=&quot;auto&quot;&gt;override.workspace = apps/&lt;/code&gt; with &lt;code dir=&quot;auto&quot;&gt;apps/&lt;/code&gt; 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.&lt;/p&gt;
&lt;h3 id=&quot;why-deliverables-is-excluded--the-value--artifact-token-coupling-c-010&quot;&gt;Why &lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt; is excluded — the value ↔ artifact-token coupling (C-010)&lt;/h3&gt;
&lt;p&gt;Routing at the paths seam is decided by whether &lt;code dir=&quot;auto&quot;&gt;_normalize_path_token(declared[key])&lt;/code&gt; is a member of
the mission’s artifact tokens. Software-dev’s &lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt; default value is &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt;, and
&lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt; &lt;strong&gt;is&lt;/strong&gt; a mission artifact token — so &lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt; resolves against the mission’s
&lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt;, not the repository root, and carries a mission-surface artifact check. Allowing an
override to change &lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt;’ value would flip that resolution surface from &lt;code dir=&quot;auto&quot;&gt;feature_dir&lt;/code&gt; to
&lt;code dir=&quot;auto&quot;&gt;project_root&lt;/code&gt; and drop the artifact check.&lt;/p&gt;
&lt;p&gt;The path-convention &lt;em&gt;value&lt;/em&gt; and the artifact-token &lt;em&gt;vocabulary&lt;/em&gt; 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 &lt;em&gt;vocabulary&lt;/em&gt; is restricted to repo-layout keys and &lt;strong&gt;excludes any key whose
default value is a mission artifact token&lt;/strong&gt;. Concretely that is &lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt;, the sole such key across
the four built-in mission types; the reader excludes it by name (&lt;code dir=&quot;auto&quot;&gt;ARTIFACT_ROUTED_KEYS&lt;/code&gt;) 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.&lt;/p&gt;
&lt;p&gt;The remaining vocabulary is the repo-layout subset of the canonical valid path keys —
&lt;code dir=&quot;auto&quot;&gt;{workspace, tests, documentation, data}&lt;/code&gt; — validated against the single frozenset &lt;code dir=&quot;auto&quot;&gt;VALID_PATH_KEYS&lt;/code&gt;
that &lt;code dir=&quot;auto&quot;&gt;MissionConfig&lt;/code&gt; also uses.&lt;/p&gt;
&lt;h3 id=&quot;fail-closed-scope&quot;&gt;Fail-closed scope&lt;/h3&gt;
&lt;p&gt;Validation is fail-closed on the &lt;strong&gt;section shape&lt;/strong&gt;, lenient on the &lt;strong&gt;file&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;A key outside &lt;code dir=&quot;auto&quot;&gt;VALID_PATH_KEYS&lt;/code&gt; (a typo) → raise &lt;code dir=&quot;auto&quot;&gt;PathConventionsConfigError&lt;/code&gt; naming the offending key
and the known keys (FR-007a).&lt;/li&gt;
&lt;li&gt;A section present but not a mapping, or a non-string / null value → raise, naming the offending key
(FR-008).&lt;/li&gt;
&lt;li&gt;An artifact-routed key (&lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt;) → warn and ignore (C-010).&lt;/li&gt;
&lt;li&gt;An absent &lt;code dir=&quot;auto&quot;&gt;path_conventions&lt;/code&gt; key → &lt;code dir=&quot;auto&quot;&gt;{}&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;A missing, unreadable, or corrupt &lt;code dir=&quot;auto&quot;&gt;.kittify/config.yaml&lt;/code&gt; → &lt;code dir=&quot;auto&quot;&gt;{}&lt;/code&gt; (lenient), matching the co-resident
section readers.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The reader also reads &lt;strong&gt;only&lt;/strong&gt; the &lt;code dir=&quot;auto&quot;&gt;project.path_conventions&lt;/code&gt; subkey — never the whole &lt;code dir=&quot;auto&quot;&gt;project:&lt;/code&gt; block,
which carries identity fields (&lt;code dir=&quot;auto&quot;&gt;uuid&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;slug&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;node_id&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;build_id&lt;/code&gt;) that must not be rejected (C-011). The
config is read once per accept run; there is no per-key filesystem read (NFR-002).&lt;/p&gt;
&lt;h3 id=&quot;layout-auto-detection-2744-is-the-deliberate-next-step&quot;&gt;Layout auto-detection (#2744) is the deliberate next step&lt;/h3&gt;
&lt;p&gt;This ADR deliberately stops at an &lt;strong&gt;explicit&lt;/strong&gt; operator declaration. It does not infer a project’s layout
from filesystem signals (&lt;code dir=&quot;auto&quot;&gt;manage.py&lt;/code&gt; → Django &lt;code dir=&quot;auto&quot;&gt;apps/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;go.mod&lt;/code&gt; → Go &lt;code dir=&quot;auto&quot;&gt;internal/&lt;/code&gt;), 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 &lt;code dir=&quot;auto&quot;&gt;project.path_conventions&lt;/code&gt; 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.&lt;/p&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;A. Keep only &lt;code dir=&quot;auto&quot;&gt;--lenient&lt;/code&gt;.&lt;/strong&gt; 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.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;B. Explicit project &lt;code dir=&quot;auto&quot;&gt;path_conventions&lt;/code&gt; value override, remap-only, artifact-routed keys excluded
(chosen).&lt;/strong&gt; Fixes the honestly-stuck project without touching the #3783 policy.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;C. Auto-detect the layout now (#2744).&lt;/strong&gt; Deferred, not rejected: valuable, but inference before an
explicit channel exists makes the honesty contract harder to audit. It builds on B.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;h3 id=&quot;positive&quot;&gt;Positive&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;A project whose real source root is not &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; accepts honestly against an untouched working tree — no
fabricated &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;, no blanket &lt;code dir=&quot;auto&quot;&gt;--lenient&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The #3783 blocking policy, payload, and remediation string are unchanged and re-proven by additive
tests.&lt;/li&gt;
&lt;li&gt;One canonical &lt;code dir=&quot;auto&quot;&gt;VALID_PATH_KEYS&lt;/code&gt; frozenset serves both mission-config validation and the override reader.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;negative&quot;&gt;Negative&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;Operators must know the &lt;code dir=&quot;auto&quot;&gt;project.path_conventions&lt;/code&gt; config surface exists; until #2744 lands, the layout
is stated by hand rather than inferred.&lt;/li&gt;
&lt;/ul&gt;
&lt;h3 id=&quot;neutral&quot;&gt;Neutral&lt;/h3&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt; remains doctrine-owned and un-overridable by design; a project cannot relocate an
artifact-routed key through this channel.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;confirmation&quot;&gt;Confirmation&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Precedence and remap-only behaviour: &lt;code dir=&quot;auto&quot;&gt;tests/agent/test_validators_unit.py&lt;/code&gt; (override resolves &lt;code dir=&quot;auto&quot;&gt;apps/&lt;/code&gt;,
no &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; violation; SC-006 declared-but-absent still blocks under strict).&lt;/li&gt;
&lt;li&gt;Non-reversal of #3783: &lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/acceptance/test_acceptance_support.py&lt;/code&gt;
&lt;code dir=&quot;auto&quot;&gt;test_no_override_still_blocks_strict&lt;/code&gt; pins the exact &lt;code dir=&quot;auto&quot;&gt;path_violations&lt;/code&gt; payload and full
&lt;code dir=&quot;auto&quot;&gt;format_errors()&lt;/code&gt; string beside the untouched &lt;code dir=&quot;auto&quot;&gt;test_lenient_downgrades_path_conventions_to_warning&lt;/code&gt;;
the accept-boundary fail-closed and one-read cases live in the same file.&lt;/li&gt;
&lt;li&gt;Reader contract (subkey-only C-011, typo/malformed/lenient, one read NFR-002):
&lt;code dir=&quot;auto&quot;&gt;tests/specify_cli/config/test_path_conventions_reader.py&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;more-information&quot;&gt;More Information&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;Builds on the honesty settlement PR #3783 (#3730/#3085); this ADR is explicitly additive to it.&lt;/li&gt;
&lt;li&gt;Deferred follow-on: layout auto-detection via &lt;code dir=&quot;auto&quot;&gt;manage.py&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;go.mod&lt;/code&gt; signals and research-shape accept
relaxation, tracked as #2744.&lt;/li&gt;
&lt;li&gt;Reader: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/config/path_conventions.py&lt;/code&gt;. Merge site: &lt;code dir=&quot;auto&quot;&gt;src/specify_cli/validators/paths.py&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;validate_mission_paths&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;_remap_declared_paths&lt;/code&gt;). Seam wiring:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/acceptance/summary_core.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;evaluate_path_conventions&lt;/code&gt;). Canonical key set:
&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/mission.py&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;VALID_PATH_KEYS&lt;/code&gt;).&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;amendment-2026-11-10-no-mkdir-remedy-for-a-remappable-path-7512&quot;&gt;Amendment 2026-11-10: no &lt;code dir=&quot;auto&quot;&gt;mkdir&lt;/code&gt; remedy for a remappable path (#7512)&lt;/h2&gt;
&lt;p&gt;A missing path whose key the project can remap (any key outside &lt;code dir=&quot;auto&quot;&gt;ARTIFACT_ROUTED_KEYS&lt;/code&gt;, such as
&lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;tests/&lt;/code&gt; or &lt;code dir=&quot;auto&quot;&gt;docs/&lt;/code&gt;) no longer gets a &lt;code dir=&quot;auto&quot;&gt;mkdir -p&lt;/code&gt; suggestion, in the strict failure or the
&lt;code dir=&quot;auto&quot;&gt;--lenient&lt;/code&gt; warning: an empty directory passes the check without making it true. &lt;code dir=&quot;auto&quot;&gt;accept --lenient&lt;/code&gt;
and the &lt;code dir=&quot;auto&quot;&gt;project.path_conventions&lt;/code&gt; remap are the remedies named for it, and the &lt;code dir=&quot;auto&quot;&gt;--lenient&lt;/code&gt; warning
now carries the same remap guidance. A missing Mission artifact path (&lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt;) keeps its
&lt;code dir=&quot;auto&quot;&gt;mkdir -p&lt;/code&gt; suggestion, and so does every path in &lt;code dir=&quot;auto&quot;&gt;path_prefix&lt;/code&gt; 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 &lt;code dir=&quot;auto&quot;&gt;src/&lt;/code&gt; is really missing still blocks, but no longer sees a &lt;code dir=&quot;auto&quot;&gt;mkdir&lt;/code&gt; hint.&lt;/p&gt;
&lt;h2 id=&quot;amendment-2026-11-20-per-mission-type-sections-and-narrow-waivers-7566-7748&quot;&gt;Amendment 2026-11-20: per-Mission-type sections and narrow waivers (#7566, #7748)&lt;/h2&gt;
&lt;p&gt;Mission &lt;code dir=&quot;auto&quot;&gt;path-conventions-per-type-01M7VRQM&lt;/code&gt;. A plain &lt;code dir=&quot;auto&quot;&gt;project.path_conventions&lt;/code&gt; 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,
&lt;code dir=&quot;auto&quot;&gt;accept --lenient&lt;/code&gt;, also skipped the work-package metadata checks (#7566).&lt;/p&gt;
&lt;h3 id=&quot;per-type-sections&quot;&gt;Per-type sections&lt;/h3&gt;
&lt;p&gt;A mapping value under &lt;code dir=&quot;auto&quot;&gt;project.path_conventions&lt;/code&gt; is a per-type section, keyed by a Mission type
id; a string value keeps its plain meaning. The value’s shape decides, so &lt;code dir=&quot;auto&quot;&gt;documentation&lt;/code&gt; (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.&lt;/p&gt;
&lt;div class=&quot;expressive-code&quot;&gt;&lt;figure class=&quot;frame not-content&quot;&gt;&lt;figcaption class=&quot;header&quot;&gt;&lt;/figcaption&gt;&lt;pre data-language=&quot;yaml&quot;&gt;&lt;code&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;project&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;  &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;path_conventions&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;workspace&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;apps/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;        &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# every Mission type that declares workspace&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;    &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;software-dev&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;:&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;div class=&quot;ec-line&quot;&gt;&lt;div class=&quot;code&quot;&gt;&lt;span class=&quot;indent&quot;&gt;      &lt;/span&gt;&lt;span style=&quot;--0:#7FDBCA;--1:#111111&quot;&gt;workspace&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;: &lt;/span&gt;&lt;span style=&quot;--0:#ECC48D;--1:#3B61B0&quot;&gt;packs/&lt;/span&gt;&lt;span style=&quot;--0:#D6DEEB;--1:#403F53&quot;&gt;     &lt;/span&gt;&lt;span style=&quot;--0:#919F9F;--1:#5F636F&quot;&gt;# software-dev Missions only&lt;/span&gt;&lt;/div&gt;&lt;/div&gt;&lt;/code&gt;&lt;/pre&gt;&lt;/figure&gt;&lt;/div&gt;
&lt;p&gt;For a Mission of type &lt;code dir=&quot;auto&quot;&gt;T&lt;/code&gt; and a key &lt;code dir=&quot;auto&quot;&gt;k&lt;/code&gt; the Mission declares, the resolved directory is:&lt;/p&gt;
&lt;ol&gt;
&lt;li&gt;the Mission type default, when &lt;code dir=&quot;auto&quot;&gt;k&lt;/code&gt; is artifact-routed (&lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt;);&lt;/li&gt;
&lt;li&gt;otherwise &lt;code dir=&quot;auto&quot;&gt;project.path_conventions.T.k&lt;/code&gt;, when set;&lt;/li&gt;
&lt;li&gt;otherwise &lt;code dir=&quot;auto&quot;&gt;project.path_conventions.k&lt;/code&gt;, when set;&lt;/li&gt;
&lt;li&gt;otherwise the Mission type default.&lt;/li&gt;
&lt;/ol&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;T&lt;/code&gt; is the Mission’s &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;mission_type&lt;/code&gt; (software-dev when absent), the value the
Mission itself is loaded from. The remap is still remap-only, research’s &lt;code dir=&quot;auto&quot;&gt;path_prefix&lt;/code&gt; still
applies after it, and the blocking decision is unchanged: a remap to a missing directory still
blocks.&lt;/p&gt;
&lt;p&gt;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 &lt;code dir=&quot;auto&quot;&gt;..&lt;/code&gt; value each raise &lt;code dir=&quot;auto&quot;&gt;PathConventionsConfigError&lt;/code&gt;. When a section exists
and the roster cannot be read, that also raises. &lt;code dir=&quot;auto&quot;&gt;deliverables&lt;/code&gt; inside a section is warned
about and ignored, as in the plain form. The roster is read only when a section exists.&lt;/p&gt;
&lt;h3 id=&quot;remedy-order&quot;&gt;Remedy order&lt;/h3&gt;
&lt;p&gt;The failure text now reads, in order: the misses; the per-type remap snippet for the failing
Mission type; the two narrow waivers, then &lt;code dir=&quot;auto&quot;&gt;accept --lenient&lt;/code&gt;; the &lt;code dir=&quot;auto&quot;&gt;mission.yaml&lt;/code&gt; copy, as a
last resort that freezes the Mission type definition; and &lt;code dir=&quot;auto&quot;&gt;mkdir -p&lt;/code&gt; only for real
deliverables (Mission artifact and research deliverable paths), with the &lt;code dir=&quot;auto&quot;&gt;contracts: none&lt;/code&gt;
waiver named beside &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt;. &lt;code dir=&quot;auto&quot;&gt;--lenient&lt;/code&gt; still precedes every &lt;code dir=&quot;auto&quot;&gt;mkdir -p&lt;/code&gt; (#3783), and no
remappable path gets one (#7512). The advisory text keeps the remap and the last-resort line
and drops the waiver lines.&lt;/p&gt;
&lt;h3 id=&quot;narrow-waivers&quot;&gt;Narrow waivers&lt;/h3&gt;
&lt;p&gt;Both make the misses of remappable layout paths warnings while strict metadata validation is
unchanged. Neither waives a missing Mission artifact such as &lt;code dir=&quot;auto&quot;&gt;contracts/&lt;/code&gt;: that still blocks
unless the Mission declares the #5298 &lt;code dir=&quot;auto&quot;&gt;&quot;contracts&quot;: &quot;none&quot;&lt;/code&gt; waiver.&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Per run:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;accept --waive-path-conventions --waive-reason &quot;&amp;#x3C;why&gt;&quot;&lt;/code&gt; (forwarded by
&lt;code dir=&quot;auto&quot;&gt;agent mission accept&lt;/code&gt;). A missing or blank reason, or a reason without the flag, is refused
before any work. The reason is recorded as &lt;code dir=&quot;auto&quot;&gt;path_conventions_waived&lt;/code&gt; on the acceptance
history entry. &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt; has no per-run waiver.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Per Mission:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;&quot;path_conventions&quot;: &quot;waived&quot;&lt;/code&gt; with a non-empty &lt;code dir=&quot;auto&quot;&gt;&quot;path_conventions_rationale&quot;&lt;/code&gt;
in &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt;, read by &lt;code dir=&quot;auto&quot;&gt;core.paths.read_path_conventions_waiver_from_meta&lt;/code&gt;, which shares the
#5298 contracts waiver’s fail-closed rules. Every accept path honors it, &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt;
included (operator ruling Q4), and the rationale is printed in the accept warnings. Trust
model: anyone who can write the Mission’s &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; can set it, the same trust model as
the contracts waiver; the printed rationale and the committed &lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; keep it auditable.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The strict failure text names the per-run flag on every path; on &lt;code dir=&quot;auto&quot;&gt;orchestrator-api&lt;/code&gt;, use the
&lt;code dir=&quot;auto&quot;&gt;meta.json&lt;/code&gt; declaration instead.&lt;/p&gt;</content>
</entry>
