Repository navigation
bug(init): unresolved placeholders should route to human manifest review before verify #325
Description
Completed on current
main(2026-09-04). The shared setup envelope now withholds onward verification while human-owned placeholders remain, names the manifest fields and lines, and routes throughdoctortoverifyafter resolution. #372/#459 and subsequent setup-control fixes implement the acceptance below. Revalidatedtests/test_setup_control.pyandtests/test_adoption_walk.py(the latter: 16 passed). #504/#337 owns authenticated review decisions; that distinct gap does not keep this setup-routing defect open.
Summary
init --write --json can report unresolved CHANGE_ME placeholders while its rank-1 action tells the caller to continue. The machine route must stop at the human-owned manifest decision and, after resolution, return to the adopter-facing verify flow defined by #327.
Expected behavior
When placeholders remain:
- control is non-complete;
- the next actor is human when the values are human-owned;
- the rank-1 action identifies exact manifest paths and source lines;
- no action implies that a coding agent may invent purpose, binding, effect, authority, approval, or similar declarations.
Illustrative shape:
{
"control": {
"state": "human_review_required",
"completion_allowed": false,
"next_actor": "human",
"next_action": {
"kind": "review_manifest",
"path": "shipgate.yaml",
"fields": ["agent.declared_purpose"]
}
}
}Acceptance criteria
- Any non-empty human-owned
placeholders[]prevents scan or verify from being the rank-1 action. - Output identifies exact paths and lines requiring review.
- The action states which values must come from a human and why.
- Once placeholders are resolved, doctor/validation deterministically advances to
verify, not a user-facing scan step. - Human-owned semantic declarations are never synthesized or presented as agent-executable edits.
- rollout(agent-mode): apply the shared control envelope across commands #323 applies the same setup-derived control vocabulary without pretending it came from a release decision.
Activity
pengfei-threemoonslab commentedon Aug 7, 2026
Confirmed at
7e0bfdf5.cli/_register_init.py:301-304:The string does carry the prerequisite as prose, and
:540emits"placeholders": placeholdersalongside it — so the information is present but split across a free-text instruction and a separate array, with the machine-routable part being a scan command either way. An agent switching on the command runs scan; an agent parsing the sentence has to understand English conjunctions. That is the inconsistency as filed.Note the state is not uniform across branches:
:327-328already emits a structurednext_actions=[action.model_dump(mode="json")], while:303,:340,:412, and:517emit strings. So part of the fix is finishing a migration that was started, not beginning one.This issue should settle a question #323 also needs answered. The proposed
control.state: "agent_action_required"for unresolved placeholders is the right routing, butinithas norelease_decisionto project a control state from — unlikeverifyandcheck, wherederive_agent_controlreflects the gate. Soinit's control state derives from setup facts (placeholders, manifest validity, detection confidence) rather than from the verdict. That is defensible, but it must be stated, orcontrol.statewill mean two different things depending on which command produced it. Recommend deciding it here, since this is the concrete instance, and letting #323 generalize from the answer.One caution on the proposed shape:
"kind": "edit_manifest"with"fields": ["agent.declared_purpose"]is an agent-actionable action kind, butagent.declared_purposeis a human-owned semantic declaration. The issue is explicit that Shipgate must not auto-fill these, and the acceptance criteria say so — but an action typed asagent_action_requiredinvites exactly that. Worth checking whether the placeholder set is uniformly human-owned; if it is, the honest state may be closer to a human-input requirement that the agent surfaces rather than one it discharges.Labeled P1 / v0.17.0.
pengfei-threemoonslab commentedon Aug 7, 2026
Flagging a direct conflict with the target flow now recorded in #327.
This issue's fifth acceptance criterion reads:
The adoption flow in #327 has no user-facing
scanstage — it isverify --preview→init --local-review→verify, withscanremaining the engine rather than a step an adopter runs. Under that flow, a resolved manifest should advance toverify, notscan.Worth amending the criterion before implementation, otherwise this lands correctly against a flow that is being replaced.
The rest of the issue is unaffected — the placeholder-gating requirement, the exact paths and lines, and the prohibition on synthesizing human-owned declarations all hold regardless of which command comes next.
Also carrying forward the open semantics question from my earlier comment, since #327 now makes it load-bearing:
inithas norelease_decisionto project a control state from, but the target flow requires it to emit one. Whatever this issue decides about whatagent_action_requiredmeans for a setup command becomes the definition #323 generalizes.[-]bug(init): unresolved placeholders should route to manifest review before scan[/-][+]bug(init): unresolved placeholders should route to human manifest review before verify[/+]merge: resolve #370 manifest-scope conflicts with the setup control e…
feat(agent-mode): roll the shared control envelope across the setup c…
pengfei-threemoonslab commentedon Aug 31, 2026
Moved v0.18.0 → v0.19.0: scheduled with the review-surface completion batch.