Allow a personal configuration layer above the shared project setup

[fastner]

Deferred — to be reviewed by Sebastian before any planning or implementation.
Open decision: is an implementation worthwhile at all? A personal configuration layer has a plausible need, but it adds a source to an already complex locator and relaxes the rule that setup is the only configuration writer. Decide whether that trade is worth it, and do so only after #484 has made resolution deterministic.

Problem

Today one configuration applies to everyone. In standard mode that is the tracked project-setup ADR. In hidden mode it is the local <RUNTIME_STATE_ROOT>/.effective-flow/project-setup.md, which replaces the ADR rather than layering on top of it (src/shared/config-migration.md step 0). Some keys express an individual preference rather than a team decision. Examples:

• language.chat: the only key that deliberately does not inherit, because it describes how a run speaks to a person;
• applyReview.defaultCommitStrategy: null means "ask at run time", and each user may want a different fixed answer;
• possibly review.profile for a solo pass.

A developer who wants a different value must either change the shared ADR or answer the same question on every run.

Proposal (to be evaluated, not approved)

• Add an optional personal file, for example <RUNTIME_STATE_ROOT>/.effective-flow/project-setup.user.md. It uses the same table encoding and is already covered by the existing ignore of .effective-flow/.
• Only an explicit allowlist of personal keys may appear in the file. Keys that change shared or forge-visible behavior stay team-only: tracker.*, delivery.*, mergeGate.*, plan.dir, concept.dir, visibility, language.forge, language.git, language.documentation.*, skills.* and executionProfiles.*. A disallowed key is reported and ignored, never applied.
• Precedence: personal file, then the effective shared source (ADR or hidden file), then the owning tool's defaults.
• The resolver from Resolve the Effective Flow configuration with a deterministic runtime script #484 reports the source of every value (personal, adr, hidden, legacy, unset). setup status from Add a read-only setup status mode that diagnoses configuration and missing domain skills #485 shows overrides.
• The file must be verified as ignored before it is read. If it is not ignored, it is not honoured, and the run reports why.

Acceptance criteria (if approved)

• The allowlist is defined in one place and enforced by the resolver. A disallowed key never changes a value.
• Every resolved value carries its source. Personal overrides appear in setup status.
• A personal file that is not ignored has no effect and produces a diagnostic.
• Hidden mode keeps its forced values. A personal file can never override them.
• Writer rule decided and documented: either setup gains a personal-scope path and stays the sole writer, or the file is explicitly user-edited and that exception is recorded in docs/developer-guide/configuration.md.

Scope

src/scripts/config-resolve-core.mjs (after #484), src/shared/config-migration.md, src/shared/config-migration-edge-cases.md, possibly src/tools/setup.md, test/, and docs/developer-guide/configuration.md.

Constraints and notes

• Questions to answer during review:
  • Which keys are really personal?
  • Does the per-run null/ask mechanism already cover the need well enough?
  • Is the added locator complexity justified?
  • Should setup or the user write the file?
• Alternatives to weigh: do nothing; an environment-variable override for language.chat only; relying on host-level user instructions.
• Any change to config-migration.md makes the merge-gate eval evidence stale, and it must be re-recorded before the next release.
• Budget: the locator prose is eager in 12 tools. With Resolve the Effective Flow configuration with a deterministic runtime script #484 the new rule should live in the script, and at most one line of prose should be added.

Related

• Depends on Resolve the Effective Flow configuration with a deterministic runtime script #484. Interacts with Add a read-only setup status mode that diagnoses configuration and missing domain skills #485.