Skip to content

process(exec, entry modes): declared-position banner, refuse-once plan rule, design front end - #790

Merged
MendixMau merged 5 commits into
masterfrom
claude/entry-mode-plan-rule
Nov 17, 2026
Merged

MendixMau merged 5 commits into
masterfrom
claude/entry-mode-plan-rule

Conversation

@MendixMau

Copy link
Copy Markdown
Owner

Direct lane

What changed and why (one paragraph): Two field runs (Nov 2026, unattended, requirements-driven, a full frozen spec plus clickable HTML prototypes and a design system, several apps under apps/<App>/) built about 78 pages with no BRDs, blueprint, wireframes, plan or briefs. PROJECT.md had no entry-mode or position line, and every guard stayed silent: the runbook's "complete specs does not mean skipping to Stage 5" is prose only, the wireframe STOP only fires if the skill is opened, and the module-brief advisory is silent without a build plan. The pattern is that the less a project declares, the quieter the toolkit gets. This PR turns that around:

  1. Banner. With no Entry mode: and no Adopted at stage: (in the register or in intake §1), bin/status.sh (both views, plus a NEXT rule), the bin/gate-check.sh summary and every bin/exec.sh run print one line: "No entry mode declared: the toolkit treats this project as Stage P, not started. Declare the mode (kickoff) or adopt a stage with a reason: gate-check.sh --adopt --reason ...". The exec BUILD-LOG row is also tagged no entry mode declared. This is a warning only.
  2. Plan rule (refuse once). In Entry mode: migration or requirements-driven, the first MDL write with no plan evidence is refused once. The refusal happens before the lock, the snapshot or any write, and returns MXTK-RESULT verdict=refused.
  3. Greenfield front end (runbook): the old "Stages 1–4 collapse to whatever plan the user already has" now reuses poc-build.md steps 1–4 by reference (design questions, wireframes or the supplied prototype, a buildability check, one approval stop recorded as the Stage-4 CONFIRMED decision). After that comes a short architecture/build-plan.md (apps, modules, screen list, a ## Module brief — <M> of a few lines per module), then the normal build.
  4. Supplied design (design-artifacts.md Step 2a): every screen is mapped to its supplied prototype in design/wireframes/PAGE-MAP.tsv (Orders_List<TAB>../../prototypes/orders/list.html). The ui-preflight-pages.md STOP now accepts a mapped prototype as the wireframe. check-page-shell.sh already resolves such rows, and page-fidelity.js takes the mapped file directly.

The policy change: exec.sh refuses once in pipeline modes

The brief advisory's header says "exec.sh is not the pipeline's gatekeeper". That stays true for undeclared, a-la-carte, greenfield, poc and existing-app projects. The argument for the change:

  • Why. A project that declared migration or requirements-driven has said it runs stages 1–4. A plain warning was the field failure: nothing an unattended run would act on. A refusal forces the agent into exactly one decision, and that decision becomes a register line.
  • Scope. Only MDL writes, only those two modes, only with no plan evidence. Never refused: a-la-carte (new explicit mode: no pipeline, audit or tooling use; gate-check reads stages 0–7 as WAIVED by mode), greenfield, Build type: poc, change an existing app, --patch (the opaque repair path doctor.sh uses), and projects with no declared mode.
  • Cheap to clear (guard rule 6). Evidence the toolkit did not create counts: Adopted at stage: 5+, a reasoned Waived stage 4:, gate-check's readout at Stage 5+, or architecture/build-plan.md plus one module brief (as a file, or a ## Module brief heading in the plan), at the root or under apps/<App>/architecture/.
  • Never blocks its remedy (guard rule 7). The clearing commands (gate-check.sh --adopt/--waive, writing the plan) do not go through exec.sh. The refusal also happens only once per clone (stamp in .mpr-snapshots/.plan-rule-refused, which is gitignored). A re-run goes ahead and every row is tagged no plan (Entry mode …, before Stage 4), so the choice is visible in BUILD-LOG.

What changes for existing projects after sync-project.sh (_position.sh is a new installed file in the manifest):

  • New banner: every project whose register and intake declare neither an entry mode nor an adoption, which includes freshly scaffolded projects still at kickoff. One line per exec/status/gate-check run.
  • New one-time refusal: migration or requirements-driven projects with no adoption at 5+, no reasoned stage-4 waiver, a gate-check readout below Stage 5, and no plan plus brief. Projects mid-build normally have a plan, a brief or a Stage 5+ readout, so they are not affected. A project that was building without a plan sees one refusal, then goes on.
  • Greenfield: gate-check's greenfield waiver text changes. A greenfield project that writes the short plan now gets its Stage-4 gate evaluated (plan content plus ✋ sign-off), which was already the documented rule for a greenfield project that writes a plan.
  • Exit codes and the MXTK-RESULT format are unchanged. The refusal uses the existing refused verdict, printed before the human lines like every other refusal.

Impact

Row Answer
Process New: one refusal per clone on a pipeline-mode project's first planless write. New: a banner, warn-only. New: an optional greenfield short plan and a supplied-design mapping step. No new blocking gate beyond that one refusal.
Dependencies exec.sh, bin/lib/install-manifest.sh (+_position.sh), bin/lib/entry-mode.sh (now a shim onto project-bin/_position.sh; same entry_mode_token(), rewritten in pure bash: identical stdout and stderr on 44 inputs including every V4 and T2 case, checked by hand), gate-check.sh, status.sh. Not touched (other tasks): obligation-check.sh / obligations.tsv (T1), bin/ready.sh (T3), _common.sh (T4). Follow-up for T1: the prototype-look row keys on design/prototype.html, so a project with only supplied prototypes reads it N/A. Accepting a mapped prototype there is T1's file. Also, obligation and artifact checks treat "no PROJECT.md" as à-la-carte; a register saying Entry mode: a-la-carte reads N/A in the artifact check (mode not in any row) but not yet in the obligation check. Not changed: intake Q1's text (editing it would make every existing intake "stale boilerplate" to --repair-intake); a-la-carte is documented in the runbook. New artifact reads: the register and intake (produced at scaffold and at kickoff), build plan and briefs (Stage 4).
Context cost Baseline 64,984 → 65,198 words (+214, budget 80,000), all in conversion-runbook.md (the "Declared, or the toolkit says so" paragraph with its failure example, the greenfield row, one clause on the requirements-driven row). Per stage, lead: P 26,999 → 27,213; 4 29,249 → 29,463; 5 27,330 → 27,544. Every stage shows the same +214 for lead/ba/architect; mdl, gate, test and review are unchanged. ui-preflight-pages.md and design-artifacts.md are on demand (+0 baseline). Pasted from bin/render-routing.sh --check on base and head.
Behaviour NOT RUN: the A/B behaviour suite was not run for the runbook paragraph; the reviewer should weigh whether it is required for this baseline text.
Runtime Time cost: per exec · 0 process starts added (_position.sh is builtins only: one read loop over PROJECT.md, no $( ) on the exec path) · can force rework: n (one refusal, then pass) · offset: none needed. The budget fixture's project has no PROJECT.md, so it takes the banner branch. Not re-measured with test-exec-process-budget.sh (see Test tier).

Field evidence: the two field runs above (shape only: requirements-driven, frozen spec plus prototypes, multi-app). Neither project was available here to re-run the instrument against. What was run: a scratch project from a real init-project.sh scaffold, single tree and apps/Orders/ layouts. Results:

  • first write refused (0 mxcli check calls), second write went on and was tagged;

  • after a real gate-check.sh --adopt 5: passes;

  • plan plus brief under apps/Orders/architecture/: passes;

  • a-la-carte and poc: pass;

  • status and gate-check banners shown on the undeclared scaffold.

  • No client data anywhere in the diff (check-no-client-data.sh clean)

  • Size cap: 10 files, 351 changed lines excluding tests, fixtures and CHANGELOG

  • Test tier: T1-ish manual. tests/wave2/test-entry-mode-plan-rule.sh was written but not executed by the builder: the session was not permitted to run fixtures. The reviewer should run it, plus test-sed-tab-bracket.sh bin/lib/entry-mode.sh, test-wrong-verdicts.sh, test-exec-process-budget.sh, and the gate-check fixtures (test-bug03-gates.sh etc.) in a detached worktree. check-scripts.sh (139/139 parse), check-portability.sh (clean) and render-routing.sh --check were run.

  • Golden input captured: fixtures/entry-mode-plan-rule/{PROJECT.md,intake.md} from init-project.sh at ff4103b (H1 renamed only). Both layouts in the fixture. macOS: bash 3.2 constructs only (nocasematch in [[ ]], no ${v,,}, no case under nocasematch); not run on macOS or Git Bash.

  • CHANGELOG.md line appended

Do not merge before the independent review (Review: line).


Generated by Claude Code

…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
…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
…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
@MendixMau

Copy link
Copy Markdown
Owner Author

Review: MERGE-AFTER-FIX. The plan rule ignores plans in the nested analysis/<name>/architecture/ layout that gate-check resolves, so such a migration project gets a false refusal. Separately, the required Behaviour A/B for +225 baseline words was not run.

Value: Fixes the reported field failure: a pipeline-mode project with no declared entry mode or no plan stayed silent.

  • The banner (project-bin/_position.sh:326, exec.sh:806-810, gate-check.sh:4131, status.sh:155-181) and the one refusal (exec.sh:811-832) target it directly.
  • One parser is kept: the tokeniser moves into _position.sh and entry-mode.sh becomes a shim.
  • Step 2a and the STOP wording are on-demand text.
  • check-page-shell.sh:103-130 really resolves ../ and #/route map rows.
  • Not overbuilt.

Regression risk:

  • Refusal shape: exit 1 with verdict=refused, matching the other refusals. It fires before the lock and trap (exec.sh:1018).
  • Guard rule 7 holds: --adopt/--waive and writing the plan never go through exec.
  • Guard rule 6 holds only partly: mxtk_plan_evidence (_position.sh:345) checks <root>/architecture and apps/*/architecture, but gate-check also reads $ANALYSIS_BASE/architecture (gate-check.sh:354-372). Reproduced: a plan and brief under analysis/acme/architecture/ with readout P gives "NO EVIDENCE".
  • After sync: projects with no PROJECT.md (à-la-carte assurance use) get the banner and a no entry mode declared BUILD-LOG tag on every exec, because mxtk_pos_undeclared ignores POS_REG. This is warn-only noise.
  • Worktrees: each fresh worktree gets its own one refusal.
  • Intake: read from the root only (_position.sh:306), while gate-check uses resolve_stage_file.

Correctness: Fixtures run in a detached worktree:

Fixture Result
new fixture (single and apps/<App> layouts) 46/46
bug03 99/99
bug06-freshness 64/64
wrong-verdicts 25/25
stage-header 21/21
status-existing-app 27/27
sed-tab-bracket 11/11
status-bare-var 3/3

Not covered: the readout-at-5 evidence path, the two-tree app/ layout and the nested analysis layout. Not run on macOS bash 3.2; the code looks 3.2-safe.

Context cost: 65,148 → 65,373 always-loaded words (+225, measured). The PR body's 64,984 → 65,198 is stale against current master. The Behaviour row reads NOT RUN, but RELEASE-PROCESS.md §4a item 4 makes the A/B required for baseline text.

Time cost: process starts per exec are 132 → 132. mxtk_pos_read takes ~3–40 ms on Linux, well under the 18 s an exec takes. A refusal can force one re-run per clone.

Exact fixes required:

  1. Accept $root/analysis/*/architecture in mxtk_plan_evidence, and add a fixture case for it.
  2. Run the Behaviour A/B for the runbook paragraph, or record the maintainer's explicit OK in the Review: line.
  3. Correct the Context cost row to the measured numbers.
  4. (Recommended) Print the banner only when POS_REG=1.

CI on e57fc4c: authoring-audit passed; checks was still running when this review was written.


Generated by Claude Code

@MendixMau
MendixMau merged commit bf1d2e9 into master Nov 17, 2026
3 of 4 checks passed
MendixMau pushed a commit that referenced this pull request Nov 17, 2026
…side throughout (master's tree equals #790's tip e57fc4c, already in this branch)
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