Skip to content

process(entry modes): mode contract, unattended-first plan rule, register skeleton (stacked on #790) - #791

Merged
MendixMau merged 17 commits into
masterfrom
claude/mode-contract
Nov 17, 2026
Merged

MendixMau merged 17 commits into
masterfrom
claude/mode-contract

Conversation

@MendixMau

@MendixMau MendixMau commented Nov 17, 2026 •

Copy link
Copy Markdown
Owner

Direct lane

Stack: #790 (banner + refuse-once plan rule) ← this PR ← #792 (greenfield retirement). This PR's base is #790's branch. Review them together, in order.

What changed and why (one paragraph): The owner's design input: unattended (Interview mode: auto) is how people actually run the toolkit, and each mode (Entry mode + Build type) is a contract. Modes may move or drop gates, but the agent may not skip the declared mode's steps or quietly switch mode. A research comparison of five field builds that followed the process with the one that did not found two old gaps. G1: a hand-written PROJECT.md made init-project.sh skip the register template in silence. G2: exec.sh had no stage check, which #790 adds.

  1. Mode contract, machine-readable, no new vocabulary. The existing modes column of bin/lib/artifact-manifest.tsv (column 6) is now documented as the per-mode step list. Its values are unchanged (migration,requirements,greenfield,existing-app-change, as entry_mode_token produces them, the same vocabulary fix(obligations): quality floor — per-module passes owed by what was built; one must-have list for every build type #787 copies onto obligations.tsv column 10). Only the wording changes: a row the mode drops reads N/A — not owed (mode <token>; manifest modes: …) instead of "entry mode … does not owe it". Build type: poc is a separate axis, read by gate-check.sh only: Stages 0–4, 6, 7 read WAIVED "not owed (mode: Build type: poc)" instead of PENDING. Stage 5 stays MANUAL and P is still checked. (A first push of this PR renamed the tokens and added poc and all; that was reverted in 86114c5 after the vocabulary correction.)

  2. Auto mode refuses until the pre-build steps are done. Under Interview mode: auto, a migration or requirements-driven project's MDL write is refused every time (no refuse-once) until one of these holds:

    • gate-check.sh <p> build-ready has passed (its PASS now writes .mpr-snapshots/.build-ready-pass, local and gitignored; sticky, so a later FAIL never blocks the repair, per guard rule 7);
    • the register adopts at 5+;
    • the register waives Stage 4.

    A plan on disk alone does not clear it under auto. Interactive mode keeps process(exec, entry modes): declared-position banner, refuse-once plan rule, design front end #790's refuse-once.

  3. --adopt under auto is not a silent escape. --adopt at 4 or later on a migration or requirements-driven project under auto also writes an ASSUMED consentBy: auto-mode decision row: Stage 4 when adopting at 5+, Stage 3 when adopting at 4. The existing auto_hand_pending() lists it on every run, and Stage 6 FAILs until a person confirms it. The refusal text says so.

  4. Mode changes are decisions: one statement in the runbook's Entry Modes; poc-build.md points to it.

  5. G1. init-project.sh and sync-project.sh append the missing register sections (Current stage, Decisions, Open questions, and Change log on init) to a PROJECT.md written by hand first, loudly, never touching existing lines. There is one template, bin/lib/register-skeleton.sh; a fresh scaffold is byte-identical to before (diffed). The generated CLAUDE.local.md gains an item 0: init runs before any PROJECT.md or model write.

  6. Unattended kick-off brief: CONVERSION-RUNBOOK.md → "Running unattended" is the one text a project brief quotes (five lines plus the failure note).

Column values changed (both tables): none in this PR. #792 drops greenfield from artifact-manifest.tsv column 6. obligations.tsv column 10 gets the same drop once #787 is on master.

What changes for existing projects after sync-project.sh:

  • Auto, migration or requirements-driven, no build-ready record, no adoption at 5+, no Stage-4 waiver: every MDL write is refused until build-ready passes or they adopt. This is the largest change; it hits once, until gate-check.sh <p> build-ready runs. Alternative the reviewer may prefer: accept gate-check's readout at Stage 5+ under auto. I did not, because the readout skips the build-ready wiring checks.
  • POC projects: stages 0–4, 6, 7 change from PENDING to WAIVED "not owed (mode: Build type: poc)", so those stage queries exit 0.
  • Any project: artifact-check and close-out N/A lines change wording. test-closeout.sh's one assertion was updated; anything grepping the old text needs the same.
  • A register missing Decisions, Current stage or Open questions: sync appends them once, with a ⚠ line.

Impact

Row Answer
Process New blocking path: auto-mode pipeline projects can't write the model until build-ready passes or they adopt. New ✋ row on auto adoptions past Stage 3/4. POC stage rows reported as not owed.
Dependencies exec.sh, _position.sh (reads interview mode in pure bash, in bin/interview-mode.sh's order), gate-check.sh, init-project.sh, sync-project.sh, artifact-manifest.tsv (header text only), artifact-check.sh and closeout.sh (wording), new bin/lib/register-skeleton.sh. Not touched: obligations.tsv / obligation-check.sh (T1). New artifact read: .mpr-snapshots/.build-ready-pass, produced by the mandatory gate-check.sh <p> build-ready step.
Context cost Baseline 65,198 (#790 head) → 65,322 words (+124; budget 80,000), all in conversion-runbook.md. Lead: P 27,213 → 27,337; 4 29,463 → 29,587; 5 27,544 → 27,668. From bin/render-routing.sh --check.
Behaviour NOT RUN: A/B suite not run for the runbook clauses.
Runtime Time cost: per exec · 0 process starts added · can force rework: y (auto projects must run build-ready or adopt) · offset: none — maintainer OK needed.

Field evidence: the research comparison above. Manual runs on real init-project.sh scaffolds:

  • auto mode: refused twice; refused again with a plan on disk; passed after the build-ready record;

  • --adopt 5 under auto wrote the ASSUMED auto-mode Stage-4 row, and gate-check listed it as a ✋ decision to confirm;

  • POC readout: 7 of 7 stages "not owed (mode: Build type: poc)";

  • hand-written PROJECT.md: init appended the sections; a second init skipped.

  • No client data (check-no-client-data.sh clean)

  • Size cap: over, at 13 files. Splitting G1 into its own PR is possible if the reviewer wants it.

  • Test tier: new fixture tests/wave2/test-mode-contract.sh not executed by the builder (fixtures not permitted in this session). The reviewer should run it, plus test-entry-mode-plan-rule.sh, test-closeout.sh, test-progress-report.sh, test-exec-process-budget.sh, the init and sync fixtures, and the gate-check fixtures. check-scripts.sh and check-portability.sh are clean.

  • CHANGELOG.md line appended

Do not merge before the independent review.

🤖 Generated with Claude Code

https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8

…n rule, design front end

With no Entry mode and no Adopted at stage line, status.sh, gate-check.sh's
summary and every exec.sh run print one banner. In Entry mode migration or
requirements-driven, the first MDL write with no plan evidence is refused
once (remedy: run stages 1-4, or gate-check.sh --adopt 5 --reason ...).
Outside evidence clears it; a-la-carte (new), greenfield, poc,
change-an-existing-app and --patch are never refused.

The entry-mode tokeniser moves to project-bin/_position.sh (pure bash, no
process starts) so the installed exec.sh can read it; bin/lib/entry-mode.sh
is a shim. Runbook greenfield row reuses poc-build steps 1-4 plus a short
plan; design-artifacts Step 2a maps supplied prototypes in PAGE-MAP.tsv and
ui-preflight-pages' wireframe STOP accepts a mapped prototype.

Field evidence: two field runs (2026-11), requirements-driven with a frozen
spec and clickable prototypes, built ~78 pages with no plan or target.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
…ster skeleton

- artifact-manifest.tsv modes column is the per-mode step list (vocabulary
  migration, requirements-driven, poc, existing-app, a-la-carte, all);
  dropped rows read "not owed (mode ...)". Build type: poc mode-waives
  stages 0-4, 6, 7 in gate-check.
- Interview mode: auto: exec.sh refuses every pipeline-mode write until
  gate-check build-ready has passed (new .build-ready-pass record) or an
  adoption/stage-4 waiver exists; --adopt 4+ under auto writes an ASSUMED
  consentBy: auto-mode decision row (Stage 6 FAILs until confirmed).
- "Mode changes are decisions": one rule in the runbook; poc-build points.
- init/sync append missing register sections to a hand-written PROJECT.md
  (bin/lib/register-skeleton.sh, one template; fresh scaffold unchanged).
- CONVERSION-RUNBOOK.md "Running unattended": the one kick-off brief.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
…wn axis

Per the vocabulary correction: artifact-manifest.tsv column 6 keeps
migration,requirements,greenfield,existing-app-change (the tokens
entry_mode_token produces, copied by obligations.tsv column 10 in #787).
No poc or all token; Build type: poc is read by gate-check.sh only. Only
the N/A wording changes ("not owed (mode ...)").

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
…e reader emits

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
…tamp dir, rendered rules page

- mxtk_pos_read honours "Waived stages: ..., 4 — reason" as gate-check does
  (was a false refusal on a project gate-check reads WAIVED at stage 4).
- .mpr-snapshots/ is git-ignored before the refuse-once stamp is written,
  so "once per clone" cannot become once per repository; docs say plainly
  it is one refusal ever per clone.
- skills/generated/rules-page.md re-rendered (bin/mdl-rules.sh --render)
  after the ui-preflight-pages.md STOP-row edit; CI was DRIFTED.
- fixture: the status NEXT case accepts the intake-§1 needs-attention line
  that outranks the banner rule; aggregate-waiver and .gitignore cases.
- _position.sh header: the shared tokeniser plus exec.sh's reader, not the
  only register reader.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
# Conflicts:
#	project-bin/exec.sh
#	skills/conversion-runbook.md
…D line stays first

CI (wave2, run 44013599260): test-bug06-freshness copies gate-check.sh
alone into a scratch toolkit, so the shim's banner text was never defined
and `set -u` aborted the summary with exit 1 (reproduced: master 0,
cb7c0fa 1, this 0). The banner is now an `if` with a defaulted variable.
status.sh guards the reader the same way and prints the banner after the
CWD line (test-status-session-cwd A: the CWD line must be first).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
# Conflicts:
#	CHANGELOG.md
#	bin/init-project.sh
….) (check-portability rule 3, bash 3.2)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
… ignored, SIGPIPE, refusal cost

- gate-check fit-gap line: the poc branch runs before stage_waiver(3), and a
  mode reason "not owed (mode: m) — why" prints as "m entry mode — why"
  (was "not owed — not owed (mode: ...)"; test-fitgap-review F11a/F15a).
- build-ready PASS git-ignores .mpr-snapshots/ before writing its record,
  as exec.sh does for its stamp.
- test-mode-contract G: second init captured to a file, not piped into
  grep -q (SIGPIPE under pipefail).
- auto-mode refusal says the cost for a project past Stage 5: one
  build-ready pass per clone.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
…sh now (test-file-bugs.sh:472)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01HXpQSifRwo7EWWDP1hPps8
@MendixMau

Copy link
Copy Markdown
Owner Author

Review: MERGE-AFTER-FIX. The auto-mode plan rule works on both layouts. But sync's new skeleton step writes Must-haves: bound before the advisory decision is made, and nothing exercises the producer of the build-ready stamp.

Value: Fixes G1 and adds the auto-mode refusal as described. One template (bin/lib/register-skeleton.sh) now feeds both init and sync. Not overbuilt: POC "not owed" is 8 lines (gate-check.sh:737-741).

Regression risk:

  • (a) Verdict flip. sync-project.sh:828-837 (2b0) appends the Current-stage block, Must-haves: bound included, before 2b1a2 (:867) decides advisory. I tested a register with no Current stage and Adopted at stage: 6: base process(exec, entry modes): declared-position banner, refuse-once plan rule, design front end #790 writes advisory, this head writes bound, so the must-haves row turns PENDING.
  • (b) Auto-mode refusals. As intended and stated, every auto-mode migration or requirements-driven project is refused on every write (exec.sh:789-805) until build-ready passes. The stamp is per clone and gitignored, so each fresh clone is refused once more. Guard rule 6 is met only through the register's adopt/waive lines. The PR's own Runtime row asks for the maintainer's OK.
  • (c) POC projects. Stages 0-4, 6 and 7 flip from PENDING to WAIVED, which is intended. A real Stage-6 FAIL on a POC is now hidden.
  • (d) No conflict. Process starts per exec: 132 → 132.

Correctness: All fixtures pass in a detached worktree. mode-contract is 21/0, and still 21/0 with every project on the apps/<X> layout. The other 11 targeted fixtures are green.

Gaps:

  • test-mode-contract.sh:86 writes .build-ready-pass by hand. The producer (gate-check.sh:4712-4723, including its .gitignore write) is untested.
  • Sync's 2b0 path is untested.
  • Protected text moved. The "~78 pages built with no plan" failure line is now at conversion-runbook.md:80. The plan-before-build rule it illustrates (:78) has no failure example left.

Context cost: 65,373 → 65,497 (+124, measured on the #790 head and this head). Behaviour is NOT RUN with no reason given, although §4a.4 makes it required for always-loaded runbook text.

Time cost: process starts per exec are unchanged. Auto projects pay one build-ready run per clone, with no offset, so a maintainer OK is needed.

Exact fixes required:

  1. Leave Must-haves: out of the block 2b0 appends, or run 2b1a2 first. Add a sync case: no Current stage, Adopted at stage: 6.
  2. Add a fixture step: gate-check.sh <p> build-ready PASS writes .mpr-snapshots/.build-ready-pass plus its .gitignore line, and a FAIL writes neither.
  3. Put the ~78-pages failure line back under the plan-before-build rule.
  4. Run the behaviour A/B, or record the maintainer's waiver together with the OK for the auto blocking path.

CI on a918bd2: green.


Generated by Claude Code

@MendixMau
MendixMau changed the base branch from claude/entry-mode-plan-rule to master November 17, 2026 08:18
…side throughout (master's tree equals #790's tip e57fc4c, already in this branch)
@MendixMau
MendixMau merged commit e19dec6 into master Nov 17, 2026
2 checks passed
MendixMau pushed a commit that referenced this pull request Nov 17, 2026
MendixMau added a commit that referenced this pull request Nov 17, 2026
…ion check (#793)

The composition check of #787/#788/#790/#791/#792 found three ways an unattended agent could still get past the plan gate. This closes them:
- Auto detection uses one first-word rule (mxtk_auto_word in project-bin/_position.sh) shared by exec.sh, gate-check.sh's --adopt check and ready.sh. `Interview mode: auto (…)` and `unattended — …` now count as auto, and the strictest of env, state file and register wins.
- ready.sh reports NOT READY while any `consentBy: auto-mode` adoption row is unconfirmed, so an agent cannot approve its own plan skip and reach READY.
- Under auto, an undeclared Entry mode is refused before build-ready. Attended behaviour is unchanged.
- The checkpoint skills no longer describe greenfield as a live mode.

Review: MERGE — no findings (the H/K/W/U order fix restores test-mode-contract to 28/0; the strictest-wins change is now in the CHANGELOG; CI green on d3c4ced)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@MendixMau MendixMau mentioned this pull request Nov 17, 2026
MendixMau added a commit that referenced this pull request Nov 17, 2026
This is the output of bin/cut-release.sh. The 24 entries under `## Unreleased` become `## v2026.11.17`. Included: #787, #788, #790, #791, #792 and #793. #789 is held.

Review: MERGE — no findings (CHANGELOG heading only; the release section has no client names; CI green on 072e417)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants