config-cascade: consumer config file location outliers (repo root, docs/standards, songwriting/templates, .github)

[kyle-sexton]

Observation

Consumer config location is .claude/<name> by convention, but work-items binds at the repo root (ADR 0015), standards live under docs/standards/, songwriting under songwriting/templates/, and the recurring schedule under .github/recurring-schedule.json. Only the first is ADR-ratified.

Ask

Ratify or relocate each outlier; record the decision in config-cascade's conformance table.

Follow-up filed at Phase 1 close of the customization-consistency program (plan: docs/topics/customization-consistency/PLAN.md on chore/customization-consistency). INVENTORY §6 item 9.

[claude]

---

Generated by Claude Code

[claude]

This was generated by AI during triage.

Triage verification (2026-09-06)

Claim holds. The convention names a single consumer config home, and the outliers exist as described, including the recurring-schedule file under the repository's workflow directory, which is present in this repository today. The body's own framing is the important part: only one of the outliers is ratified by an ADR, so the rest are undeclared deviations rather than approved exceptions.

Triage outcome: human-gated (doctrine decision)

Why not agent-ready. The ask is to ratify or relocate each outlier. Each is a separate judgment with real reasons on both sides, and some of the placements are load-bearing rather than accidental:

• A file under the workflow directory may be read by workflow tooling that expects it there, so relocating it is not free.
• A standards directory placement may be deliberate, since standards are consumed by people as well as tooling.
• A template directory placement may reflect that the content is templates rather than configuration.

Relocating a consumer-facing config path is also a breaking change for existing consumers, so each ratify-or-relocate answer carries a migration cost that only a maintainer can weigh.

What must be decided: for each outlier, ratify in place or relocate to the conventional home, and record the outcome in the convention's conformance table so the deviation stops being undeclared. Where relocation is chosen, whether existing consumers get a migration path or a hard cutover is part of the same decision.

Cluster: customization-consistency INVENTORY section 6

This item is one of six open follow-ups filed together at Phase 1 close of the
customization-consistency program: #3573, #3574, #3575, #3576, #3577, #3579. Each asks the
same shape of question about a different surface: a divergence was inventoried, each variant is
locally justified, and someone must decide whether the variants converge or are ratified as
declared exceptions.

They should be resolved together, in one sitting, by one person. Answering them one at a time
invites six inconsistent answers to what is really one posture question, which is the exact
failure the program exists to fix.

They are already in the program's path. The program's plan (docs/topics/customization-consistency/PLAN.md,
on the chore/customization-consistency branch) charters a Phase 2 doctrine amendment to
docs/conventions/config-cascade/, docs/PLUGIN-PHILOSOPHY.md and docs/MIGRATION-PLAYBOOK.md,
recorded in one ADR. Five of the six asks land squarely in those documents. The most likely correct
outcome is that Phase 2 absorbs this set rather than each being handled separately.

Recommended for a future pass: give these six a container item under the program so the
decision has one home. This triage pass deliberately did not create, merge, or close anything.

---

Generated by Claude Code

[kyle-sexton]

Folding in a retired local handoff item that asked the same question from the location/format axis. Most of it is already settled on main; three points it carries are not in this issue yet.

Already settled (no action here). The expression axis landed with ADR 0018 (#3587): team-shared prose configuration is a convention doc at the consumer's convention home bound by one pointer line, and structured, per-operator, policy-floor and mutable surfaces stay dedicated files (docs/conventions/config-cascade/README.md:132-159). That covers the item's "CLAUDE.md / AGENTS.md as the home for model-read config" proposal.

What this issue lacks:

1. An empirical test of the .claude/ write guard, before ruling on standards. The standards location deviation rests on "writes under .claude/ are permission-guarded" (config-cascade/README.md:249-253, and the Implementers row at :290, still "observed, not ratified"). No measurement of it is recorded. The ruling depends on the answer: if plugin-owned .claude/<name> writes are guarded everywhere, the standards placement is the correct pattern and the .claude/ surfaces are the outliers; if only harness-owned files (.claude/settings*.json) are guarded, the standards placement is a preference. Measure, in a sandbox repo:
   • local CLI: can a setup skill create and edit .claude/<surface> without a prompt, versus .claude/settings.json;
   • a Claude Code on the web / cloud session: same two cases, read and write separately (the operator's hypothesis is that .claude/ is write-restricted there; unverified);
   • record each result with a version stamp and a recheck trigger, per the repo's upstream-drift rule.
     Note that context-budget ships a hook that forces a prompt on writes to settings surfaces, so a local prompt on settings files alone is expected and does not settle the plugin-owned case.
2. The one-pointer-file option as an alternative to per-surface ratify-or-relocate: one fixed, tiny pointer (the shape .claude/standards.yaml -> standards_dir already proves) naming a configurable root, with today's paths as defaults. Cost to weigh: a bootstrap lookup in every setup resolution ladder, and no path knowable in advance for cross-repo tooling. The ADR 0018 pointer line already plays this role for prose surfaces, so this only matters for the dedicated-file surfaces.
3. Fold the overlay-spelling drift into whichever migration lands. The contract's "Overlay spelling drift" section records four .gitignore spellings for the overlay layer; any relocation touches the same files.

This belongs with the #3573 to #3579 cluster the triage comment names, decided in one sitting.

Source: local handoff item 20260817-224500-config-surface-locations-prescribed-not-configurable.md (retired into this comment).

[kyle-sexton]

Decision packet (short; the joint packet is on #3573: #3573 (comment)). This comes from the 2026-09-29 audit of the Cursor run. The issue is reopened and needs an owner decision. #3574 packet: #3574 (comment). The 2026-09-06 triage asked for one sitting on the whole cluster.

1. What fix PR #5313 (draft) does

Removes the agent's ratification of the standards location, the songwriting override path and .github/recurring-schedule.json (README Ratified bullet, two Declared bullets, three Implementers rows, the matching glance-table cells, CHANGELOG bullet), restoring "Observed, not ratified" for standards as at baseline 7acaf08. ADR 0015 (work-items repo-root binding) is unaffected. No replacement option is written.

2. Measurement still owed (operator)

Your 2026-09-27T21:18:56Z comment asked for three things before any ruling; none was done. Steps an unattended agent cannot run: in a sandbox repo on the local CLI, can a plugin-owned surface .claude/<name> be created and edited without a permission prompt, versus .claude/settings.json, in default, acceptEdits and auto modes; then the same two cases, read and write separately, in a Claude Code on the web (cloud) session. Record each result with the Claude Code version and a recheck trigger per docs/conventions/upstream-drift/README.md. A prompt on settings files alone is expected, because context-budget ships a hook that forces one, and it does not settle the plugin-owned case.

3. Question (after the measurement)

Ratify each outlier in place, relocate under .claude/, or adopt the one-pointer-file option (a tiny fixed pointer like .claude/standards.yaml -> standards_dir naming a configurable root; cost: a bootstrap lookup in every resolution ladder and no path known in advance for cross-repo tooling)? Fold the overlay-spelling drift into whichever migration lands; decide in the same sitting as #3573, #3574 and #3575.

4. Recommended (not decided)

Run the measurement first, then decide per surface with the cluster. Basis: your comment's sentence "if only harness-owned files are guarded, the standards placement is a preference".

5. Unblocks

The config-cascade Implementers rows for standards, songwriting and the work-items schedule, and the ADR for the cluster.