config-cascade: settings resolution and convention home #7571

Parent

Refs #7555. Source: PLAN Phase 3, topic poteto-review. Thread: Settings resolution and convention
home.

Depends on

• source-control: merge authority and non-author verifier #7570 Merge authority and verifier (sequence: the verifier spine runs first; order, not a data
  dependency)

Outcome

Every plugin setting resolves through one documented cascade: plugin default, userConfig, team
file and personal overlay in the conventions home, with policy-floor keys that a personal overlay
can only tighten.

Decisions

• One config ADR superseding ADR 0061's paths, ADR 0064's fixed root and ADR 0015: plugin default,
  userConfig, team <home>/<concern>.yaml, personal <home>/<concern>.local.md overlay replacing
  sections by heading; personal beats team except policy-floor keys, which may only tighten (D77,
  D112, Q507, Q549, Q550). Origin: ours.
• Instruction text beats config, config beats plugin defaults; a skill that defers says which file
  won; one AGENTS.md line says plugin defaults are fallbacks (D77, C14).
• Default home docs/conventions/<concern>.md (+ .yaml for model-free readers) with a pointer in
  the existing AGENTS.md/CLAUDE.md; conform to an existing equivalent home; YAML never under
  .claude/; no plugin-specific convention files (D111, Q534, Q547).
• All 15 conventions-vetting fixes adopted (D112, Q549). Rename conventions/ to standards/ in
  melodic-software/standards as a pure move (refactor: rename conventions/ to standards/ standards#790) (D111, Q548): another
  repository, so this thread stops and asks before touching it; the synced-path rename follows its
  merge as its own PR.
• Guidance reaches consumers through the settings cascade; a setup action offers to write convention
  files; nothing always-loaded (Q578).
• C17: preferences where reasonable consumers differ become settings with a named default, basis and
  scope. Fixed floors only tighten: D79, Q574, D96, D88, D100, Q131, the C13 intent gate (Q553).
  Setting: research depth for routine actions "cite what is in context" (Q553, Q575). Origin:
  owner's.
• PR pipeline slice a reads the existing ADR 0061 resolver for pr_open_state; this thread migrates
  it (GUIDE 121).

Key interfaces

From the design's contracts, "Config": "One config ADR supersedes ADR 0061's paths, ADR 0064's
fixed root and ADR 0015. Layers: plugin default, userConfig, team <home>/<concern>.yaml,
personal <home>/<concern>.local.md (replaces sections by heading). Personal beats team except
policy-floor keys, which may only tighten. Instruction text beats config; config beats plugin
defaults." "Bindings: tracker <home>/work-items.yaml (schema-checked; stop and ask when
undeterminable), buffer <home>/findings-buffer.yaml (.local.yaml overlay), app driver
app-control.yaml or discovery."

Variation verdicts: "Conventions home location: contain now; docs/conventions/ default, conform to
an existing equivalent home (D111, Q547)."

Conventions followed: ADR 0015, ADR 0061, ADR 0064, the config-cascade convention.

Slices: #7934 config-adr; resolver-and-vetting-fixes and setup-writes-conventions (filed once the
verify-scripts change for scripts/sync-shared-copies.sh is open, GUIDE 134).

Done when` for #7571. Each line names the file that does the job. The current

lines point the layer and floor checks at lib/resolve-convention-home.sh, which only finds the
home directory (its header). The layers live in lib/config-cascade.mjs, and the resolver's
test already exists at plugins/harness-config/lib/resolve-convention-home.test.sh.

Done when

• lib/config-cascade.test.mjs has a passing case, for each Floor direction value other
  than "no floor", where a personal <home>/<concern>.local.yaml value that loosens a
  policy-floor key is rejected and the team value stands
  (scripts/run-test-file.sh lib/config-cascade.test.mjs exits 0). No such case exists on main.
• lib/config-cascade.test.mjs has a passing case where a <home>/<concern>.local.md
  section replaces the team <concern>.md section with the same heading and leaves the other
  sections. No such case exists on main.
• lib/config-cascade.mjs no longer reads the user-global layer
  (<userHome>/docs/conventions/<plugin>), and an invalid value drops its layer (ADR 0064 D7).
  Each has a case in lib/config-cascade.test.mjs.
• plugins/harness-config/lib/resolve-convention-home.test.sh passes with cases for root
  classification ($HOME, an ancestor of it, outside git), no duplicate: on a symlinked
  CLAUDE.md, --ref and stdin, and the declined line
  (scripts/run-test-file.sh plugins/harness-config/lib/resolve-convention-home.test.sh exits 0).
• The config-cascade README's Implementers table has a Floor direction column whose values
  the new config ADR defines, and each file that cites ADR 0061 also cites the new config ADR.
• CI's lint-repo job (scripts/check-convention-yaml.sh --check,
  scripts/sync-config-cascade-semantics.py --check) and check-plugins job
  (scripts/sync-shared-copies.sh --check) pass on each slice PR.
• Every slice sub-issue is closed by a merged PR.

Out of scope

• Writing to melodic-software/standards (owner stop).
• Per-plugin settings content; each thread adds its own settings through this cascade.

Related

• config: reconcile ADR 0061 and ADR 0064 on the invalid-value rule and the two YAML-subset parsers #7104 reconcile ADR 0061 and ADR 0064 (sub-issue of this thread); overlaps the config ADR here.
• Migrate per-skill .claude config files to userConfig, one conventions doc, or the cascade (ADR 0018) #5906 migrate per-skill config files (sub-issue of this thread).
• fix(config-cascade): resolve-convention-home.sh misresolves outside a repo and on symlinked CLAUDE.md #7540 resolve-convention-home misresolves outside a repo (sub-issue of this thread).
• docs(config-cascade): add Implementers rows for the source-control and work-items YAML team layers #7196 config-cascade Implementers rows (sub-issue of this thread).