Repository navigation
feat(lib): let the shared setup writer converge by detected state (init, migrate, configure) #9862
Description
Refs #6594. Slice 3 of 4. Blocked by #9809 (slice 2; migrate must carry provenance).
Problem
docs/plugin-philosophy.md:629-631 calls apply state-assessing, but the shared writer lib/setup-apply.mjs only creates or updates <home>/<plugin>.yaml from key=value arguments. It does not detect which of three states a repository is in and act on it (#6594 Setup actions):
- no conventions: init;
- config at an old location declared in the plugin's
retirements.yaml(docs/conventions/retired-conventions/README.md): migrate; - existing config: configure.
So every plugin's setup skill re-describes this in prose, and a migration can drop a value silently.
Fix
Add state detection to lib/setup-apply.mjs (and its generated copies):
- A
--stateflag prints exactly one ofinit,migrate,configure, with the evidence path, and writes nothing. - In the
migratestate,--yesmoves every value from the retired location named by the plugin'sretirements.yamlrecord into<home>/<plugin>.yaml, carrying its provenance (slice 2); a value it cannot carry is printed and the old file is left in place. When both locations exist, the new one wins and the run warns, naming both paths. - A second run with no changed inputs writes nothing.
- Document the three states in
docs/conventions/setup-lifecycle/README.md.
Out of scope: moving any real plugin's surface (#5906 carries those).
Done when
-
bash lib/setup-apply.test.shexits 0, with new cases for:--stateprintinginit,migrateandconfigureon three fixtures; a migrate that carries every value and its provenance entry; a value that cannot be carried leaving the old file in place; both locations present (new wins, warning names both); a second run producing no diff (git status --porcelainempty in the fixture) -
bash scripts/sync-shared-copies.sh --checkexits 0 -
ci-statusis green on the PR head
Activity
github-actions commentedon Oct 24, 2026
Proposed work class: work-class: scoped
Basis: automated intake triage; the lanes App applied this class.
Size: Medium
Complexity: Medium
Uncertainty: Known
Flags: none
Blocked by: #9809
Understood: add state detection (init, migrate, configure) to the shared setup writer. That means a read-only
--stateflag, a--yesmigrate that carries values and provenance from the retired location, a rule that the new location wins when both exist, idempotent reruns, and docs for the three states. The done-when checks are concrete. The issue says it is blocked by #9809 (provenance in the writer), which is still open. Related parent: #6594.Automated triage, applied by the lanes App.
melodic-automation-lanes commentedon Oct 24, 2026
Not admitted to the issue lane: a Feature needs an open parent issue a listed human filed that awaits no decision. Admission takes the issue once each of those is met, when intake triages it again (
.github/actions/resolve-config/admission-rules.json).kyle-sexton commentedon Oct 26, 2026
Released for re-triage under the owner's 2026-10-26 rule: a person is involved only for "1. A change in original intent/vision 2. Something comes up during implementation ... that alters intent/vision or the primary design 3. If there is a HIGH/CRITICAL security issue". None applies here, so the hold label came off and intake triage runs again now.
To hold this issue again, add
needs-human(orstatus: needs-decision) and name which of the three applies.melodic-automation-lanes commentedon Oct 26, 2026
The latest triage verdict holds nothing: admission moved the issue to
status: confirmed; its comment says why.