existing-app-change: map the app first, ask about findings, park until the change is named

CHANGELOG.md

@@ -16,6 +16,7 @@ three commits past it), and a bug report can name a release instead of a sha nob
 Sections dated before 2026-09-19 predate the cycle and stay as they are.
 
 ## Unreleased
+- new(existing-app-change): **map the app first, ask what to do with the findings, and let a project park until the change is named.** Stage 0 in this mode now opens with the app analysis (`app-facts.sh` + `app-report.sh`, `skills/app-analysis.md`), run without asking since it is read-only and takes about a minute, followed by the question the user owns: fix / log / accept per top finding. Kickoff no longer opens with "which slice?"; the slice and its blast radius (read from the map's tangles and edges, not recomputed) come at Stage 0b, when the change arrives. `artifact-manifest.tsv` owes the map in this mode (`app-report`, Stage 0); gate-check reports a mapped project with no change as Stage 0 `PENDING` instead of a permanent FAIL, and its Stage 1 hint names Path D instead of an extractor. `existing-app-assurance.md` Track A starts from the same report, so an audit that turns into a change does not redo it. Fixture: `test-bug03-gates.sh` T12. Field run: a live client workflow app — 28 modules, one tangle of 7 of 9 own modules, 213 loop microflows, mapped in 76 s; gate-check read it PENDING/parked with 0 needing attention — Maurits Visser
 - docs(pipeline-walks): **`docs/pipeline-walks.html` — a process diagram per entry mode, with the scripts run at every step.** Shared spine, migration, requirements-driven (incl. the docs-ready fast path), greenfield, change-an-existing-app (opening with the app-mapping step: `SHOW STRUCTURE`, `graph-report`, `lint`, `report`, security matrix, `marketplace diff`), à-la-carte tracks A/A2/B, and the Stage 5 BUILD→GATE→PROVE→LOOK→CONFIRM loop, each as a mermaid flowchart plus a stage/what/scripts table. Linked from the README entry-modes paragraph — Maurits Visser
 - fix(bin/doctor.sh): **doctor told every Podman user "docker is not installed"** — the section advertised Podman in its advice text ("Rancher Desktop or Podman … are common substitutes") while all four probes ran `docker` only: `docker info`, the `command -v docker` gate, the not-installed warning, and a start hint that said `open -a Docker`. So a machine fully able to run the container lane on Podman, but without the docker shim, was reported broken — and on a team that cannot licence Docker Desktop that reads as "go install software you are not allowed to have" (a colleague's machine-ready status carried "Docker not installed" as a known issue; they may have had Podman all along). Detection is now docker-then-podman (`MXTK_CONTAINER_RUNTIME` forces one), the runtime is **named** in the report (`podman responding — …`), the start hint knows `podman machine start` / `podman.socket`, and the not-installed warning names Podman as the licence-free option instead of implying Docker Desktop is required. Same bounded background/poll/kill probe for both, same 0/1/2 exit contract; `mxcli docker check` invocation deliberately untouched (different repo). **Not field-run** — no container runtime in the authoring container; needs one run on a Mac with Podman and no `docker` on PATH. Driver: the Mendix migration team's Docker Desktop licensing constraint — Maurits Visser
 - learn(skills/doctor-triage.md): **"doctor.sh says red — what now?" is now on disk instead of in a Slack thread.** Three failures that render identically get separated: my environment is wrong / the toolkit's own self-check is wrong / this line does not apply in my lane. Check the machine before naming a fix — a wrong-arch binary, a missing one and a broken self-check all read the same, which is how *"install Studio Pro 10.24.18"* became the first confident answer to a Linux-ELF mxbuild on a Mac, and how a false `fail (unreadable error file)` (the self-test bug fixed in `c0ea53c`) sent people to audit their own machines. Also: the three toolchain lanes (bundled `mx` — macOS ships one only from Mendix 11 — the Linux-only CDN toolchain, and the container lane, runtime-agnostic although doctor still probes only `docker`), a derivation for which FAILs block rather than a list that rots, the N+M-lines-dispositioned bound, and the VM/arch caveat. From the macOS onboarding thread of 2026-09-22 — Yvann, and the four people in it

bin/gate-check.sh

@@ -824,6 +824,12 @@ check_stage_0() {
     }' "$f")
   if [ -z "$signer" ]; then
     echo "FAIL|no non-empty 'Confirmed by:' line inside the '## Sign-off' section of $f — anything the user actually said is enough (\"confirmed in chat\", \"agreed, move on\"); it only has to not be the shipped placeholder"
+  elif printf '%s' "$signer" | grep -q '\[' && [ "$ENTRY_MODE" = "existing-app-change" ] \
+       && [ -s "$PROJECT_DIR/analysis/app-report.json" ]; then
+    # Mapped and waiting for a change is a normal state in this mode (existing-app-change.md
+    # §"Map the app first"): there is no slice to sign off yet, so this is not-started, not wrong.
+    # Without it a parked project read "needs attention" forever (existing-app field run, 2026-09-22).
+    echo "PENDING|app mapped (analysis/app-report.html), waiting on the change — triage.md is signed off at Stage 0b, once the user names the slice and its blast radius is written ($f, ## Sign-off)"
   elif printf '%s' "$signer" | grep -q '\['; then
     echo "FAIL|'Confirmed by:' still holds the shipped placeholder: \"$signer\" — replace it with whatever the user actually said (\"confirmed in chat 2026-08-20\" is fine; a full name is not required) ($f, ## Sign-off)"
   else
@@ -837,6 +843,13 @@ check_stage_1() {
     # extractor it was never going to run (2026-08-20). "No knowledge-base directory" is true in
     # every mode; what to DO about it is not, and the KB for a document corpus is built by a
     # skill, not a pipeline. Name both routes rather than assuming the migration one.
+    if [ "$ENTRY_MODE" = "existing-app-change" ]; then
+      # Neither route above exists in this mode: there is no source to extract, only the live
+      # model, and Stage 1 cannot be scoped until the user has named the change (existing-app
+      # field run, 2026-09-22 — the generic hint pointed at an extractor the mode never runs).
+      echo "PENDING|no knowledge-base directory yet — existing app: this stage reads the live model (Path D, skills/existing-app-change.md), scoped to the change and its blast radius. Waiting on the change is a normal state: map the app first (analysis/app-report.html, skills/app-analysis.md), then scope when the user names the change"
+      return
+    fi
     echo "PENDING|no knowledge-base directory yet — migration: run the extraction pipeline; requirements-driven: build the KB from the document corpus per skills/kb-generation.md (Path B). Either way it lands at analysis/<source>/knowledge-base/"
     return
   fi

bin/lib/artifact-manifest.tsv

@@ -43,7 +43,9 @@
 #                 migration,requirements,greenfield,existing-app-change
 #                 (conversion-runbook.md §"Entry Modes", its table; existing-app-change runs
 #                 P–6 per slice, so it owes every row but coverage-ledger — that mode's ledger
-#                 is `mxcli brain plan`, existing-app-change.md §"Coverage in this mode").
+#                 is `mxcli brain plan`, existing-app-change.md §"Coverage in this mode") — plus
+#                 app-report, the one row only it owes: the map of the live app that Stage 0's
+#                 blast radius is read from (existing-app-change.md §"Map the app first").
 #                 À-la-carte projects
 #                 run no stages and are excused wholesale by artifact-check.sh, same test as
 #                 obligation-check.sh.
@@ -70,6 +72,7 @@ artifact	stage	paths	producer	consumers	modes	absence
 intake	P	intake.md	bin/init-project.sh scaffold + the Stage-P kickoff interview (conversion-runbook.md §2 Stage P)	bin/gate-check.sh:596 (check_stage_P), bin/gate-check.sh:497 (entry-mode fallback read)	migration,requirements,greenfield,existing-app-change	gate
 register	P	PROJECT.md	bin/init-project.sh (empty register); every checkpoint writes into it (CLAUDE.md §One decision register)	bin/gate-check.sh:285 (register resolution feeding every ✋ gate), bin/lib/obligation-check.sh:151 (waivers/adoption read from it)	migration,requirements,greenfield,existing-app-change	gate
 triage	0	triage.md	bin/init-project.sh scaffold, filled per skills/source-triage.md; N/A rows recorded, never deleted (conversion-runbook.md:130)	bin/gate-check.sh:684 (check_stage_0 sign-off test)	migration,requirements,greenfield,existing-app-change	gate
+app-report	0	analysis/app-report.json|analysis/app-report.html	project-bin/app-facts.sh (read-only: full catalog build + mxcli graph-report + loop sweep) then bin/app-report.sh — skills/app-analysis.md Procedure steps 1 and 5	skills/existing-app-change.md §"Map the app first" (the findings interview reads analysis/app-report.json) and §"Blast radius" (reads analysis/app-facts/dependencies.json tangles and edges)	existing-app-change	report
 extraction-report	1	analysis/*/knowledge-base/extraction-report.html|analysis/knowledge-base/extraction-report.html|knowledge-base/extraction-report.html	bin/extraction-report.sh <project-root> — one renderer for every entry mode	bin/gate-check.sh:725 (check_stage_1)	migration,requirements,existing-app-change	gate
 source-ledger	1	analysis/source-ledger.html	bin/source-ledger.sh report <project-root> — every inventoried source file and what consumed it (Stage 1 owes a disposition per row; gate-check blocks 1–2 on the check)	bin/gate-check.sh (LEDGER block — the check; the html is the human-facing table of the same rows)	migration,requirements,existing-app-change	report
 brds	2	analysis/*/knowledge-base/brd/*.brd.json|analysis/knowledge-base/brd/*.brd.json|knowledge-base/brd/*.brd.json	pipeline generators (migration), skills/kb-generation.md (documents), skills/brd-generation.md (by hand) — the reader must not care which	bin/lib/discover-brds.sh:43 (the one path authority), bin/gate-check.sh:773 (check_stage_2), bin/brd-report.sh, bin/open-questions.sh	migration,requirements,existing-app-change	gate

docs/pipeline-walks.html

@@ -244,17 +244,17 @@ <h2 id="gf"><span class="pill gf">Greenfield</span> Just an idea, or a running s
 
   <!-- ===================== CHANGE AN EXISTING APP ===================== -->
   <h2 id="chg"><span class="pill chg">Change an existing app</span> A live .mpr you are altering, not rebuilding</h2>
-  <p class="sub">The knowledge base comes from the model itself (Path D). The first real step is mapping the app for the agent: structure, quality, security, marketplace drift. Stage 0 adds the blast radius of the slice. A regression net goes under the app before anything changes, and every gate from Stage 5 on is also a regression gate.</p>
+  <p class="sub">The knowledge base comes from the model itself (Path D). The first real step is mapping the whole app, run without asking, followed by the one question the user owns: what to do with each top finding. The project may park there until a change is named; Stage 0b then adds the blast radius of the slice, read from the map. A regression net goes under the app before anything changes, and every gate from Stage 5 on is also a regression gate.</p>
   <div class="diagram"><pre class="mermaid">
 flowchart TD
-  P["P Kickoff light<br/>init-project.sh, intake from the model<br/>register: Change an existing app CONFIRMED"] --> M["Map the app for the agent"]
-  M --> M1["structure<br/>SHOW MODULES / ENTITIES / ASSOCIATIONS<br/>mxcli graph-report"]
-  M --> M2["quality<br/>mxcli lint + Starlark rules<br/>mxcli report (assess-quality)"]
-  M --> M3["security and drift<br/>SHOW SECURITY MATRIX<br/>mxcli marketplace diff"]
-  M1 --> S0
-  M2 --> S0
-  M3 --> S0
-  S0["0 Triage ✋ two questions:<br/>which slice, what is its blast radius"] --> S0a["blast radius into triage.md<br/>associations, microflows (SEARCH),<br/>pages (SHOW PAGES IN), module tangle,<br/>published / consumed services"]
+  P["P Kickoff light<br/>./mxcli in place, then init-project.sh<br/>open question: what is driving it?<br/>register: Change an existing app CONFIRMED"] --> M["0a Map the app, not asked, just run<br/>bin/app-facts.sh then bin/app-report.sh<br/>(app-analysis.md, about a minute)"]
+  M --> F["show the report, ask per top finding:<br/>fix in this work / log / accept<br/>answers into PROJECT.md"]
+  F --> PK{"change named yet?"}
+  PK -- "not yet" --> PARK["parked: a normal state<br/>Stage 1 PENDING, nothing nags"]
+  PARK -.->|change arrives| S0
+  PK -- "only audits / tests wanted" --> AS["switch to existing-app-assurance<br/>Track A starts from the same report"]
+  PK -- "yes" --> S0
+  S0["0b Triage ✋ which slice,<br/>what is its blast radius"] --> S0a["blast radius into triage.md, read from the map:<br/>dependencies.json tangles and edges,<br/>then associations, SEARCH, SHOW PAGES IN,<br/>published / consumed services"]
   S0a --> S0b["capability map from SHOW MODULES<br/>extraction rows N/A<br/>CAC-1, sign-off"]
   S0b --> RN["Regression net under the app<br/>Track B baseline from existing-app-assurance"]
   RN --> S1["1 Analysis Path D<br/>DESCRIBE ENTITY, SHOW MICROFLOWS IN,<br/>graph-report scoped to slice + blast radius<br/>counts recorded, Path A = N/A, CAC-1b"]
@@ -277,8 +277,8 @@ <h2 id="chg"><span class="pill chg">Change an existing app</span> A live .mpr yo
   <div class="tablewrap"><table class="steps">
     <tr><th>Step</th><th>What it does</th><th>Scripts and commands</th></tr>
     <tr><td>P light</td><td class="what">Scaffold. Intake answers come from the model, not from the user's memory. Run the machine check once.</td><td class="scripts"><code>bin/doctor.sh</code><br><code>bin/init-project.sh &lt;project&gt;</code></td></tr>
-    <tr><td>Map the app</td><td class="what">Give the agent a picture of the whole app before scoping: module graph and dependency tangle, current quality score, lint findings, security matrix, marketplace modules that drifted from their published version. The findings feed the blast-radius answer and the regression baseline.</td><td class="scripts"><code>./mxcli -p app.mpr -c "SHOW MODULES"</code><br><code>./mxcli -p app.mpr -c "SHOW STRUCTURE DEPTH 2"</code><br><code>./mxcli graph-report -p app.mpr</code> (<code>graph-analysis.md</code>)<br><code>./mxcli lint -p app.mpr</code><br><code>./mxcli report -p app.mpr --format html</code><br><code>./mxcli -p app.mpr -c "SHOW SECURITY MATRIX"</code><br><code>./mxcli marketplace diff &lt;content-id&gt; -p app.mpr</code> (v0.18+)</td></tr>
-    <tr><td>0 Triage ✋</td><td class="what">Two questions: which slice, and what is its blast radius. The radius is written into <code>triage.md</code> as its own section, with counts. Capability map from the module list. CAC-1 and sign-off.</td><td class="scripts"><code>SHOW ASSOCIATIONS IN &lt;Module&gt;</code> · <code>DESCRIBE ENTITY M.E</code><br><code>SEARCH '&lt;entity&gt;'</code> · <code>SHOW PAGES IN &lt;Module&gt;</code><br><code>SHOW REFERENCES OF M.E</code> · <code>SHOW IMPACT OF M.E</code><br><code>./mxcli graph-report</code> for the tangle<br><code>bin/gate-check.sh &lt;project&gt; 0</code></td></tr>
+    <tr><td>0a Map the app</td><td class="what">Run, do not ask: it is read-only and takes about a minute. Inventory, module tangles, loop-risk microflows, dead elements, with a fix-first list. Show the report and ask the user to disposition each top finding (fix in this work / log / accept); answers go to <code>PROJECT.md</code>. The project may then park until a change is named. Owed in this mode as the <code>app-report</code> artifact. Lint, security matrix and marketplace drift fill the report's Security and Lint sections.</td><td class="scripts"><code>bin/app-facts.sh</code> (<code>app-analysis.md</code>)<br><code>bin/app-report.sh &lt;project&gt;</code><br><code>./mxcli lint -p app.mpr</code><br><code>./mxcli -p app.mpr -c "SHOW SECURITY MATRIX"</code><br><code>./mxcli marketplace diff &lt;content-id&gt; -p app.mpr</code> (v0.18+)</td></tr>
+    <tr><td>0b Triage ✋</td><td class="what">Once the change is named: which slice, and what is its blast radius, starting from the map's tangles and edges. The radius is written into <code>triage.md</code> as its own section, with counts. Capability map from the module list. CAC-1 and sign-off.</td><td class="scripts"><code>SHOW ASSOCIATIONS IN &lt;Module&gt;</code> · <code>DESCRIBE ENTITY M.E</code><br><code>SEARCH '&lt;entity&gt;'</code> · <code>SHOW PAGES IN &lt;Module&gt;</code><br><code>SHOW REFERENCES OF M.E</code> · <code>SHOW IMPACT OF M.E</code><br><code>analysis/app-facts/dependencies.json</code> for the tangle<br><code>bin/gate-check.sh &lt;project&gt; 0</code></td></tr>
     <tr><td>Regression net</td><td class="what">Track B from the assurance skill, before any change: harness, action inventory, one journey per action, DB assertions, wiring sweep, LOOK pass, committed baseline.</td><td class="scripts">see <a href="#alc">Track B</a> below<br><code>project-bin/coverage-preflight.sh --assess --module &lt;M&gt;</code></td></tr>
     <tr><td>1 Path D</td><td class="what">Query the model into the knowledge base, scoped to slice plus blast radius. Record counts. Path A declared N/A with attribution. Path C matters most here: the people who know why the app is the way it is.</td><td class="scripts"><code>SHOW ENTITIES IN</code> · <code>DESCRIBE ENTITY</code> · <code>SHOW MICROFLOWS IN</code><br><code>DESCRIBE MICROFLOW</code> · <code>DESCRIBE PAGE</code><br><code>bin/extraction-report.sh &lt;project&gt;</code><br><code>bin/gate-check.sh &lt;project&gt; 1</code></td></tr>
     <tr><td>2 Requirements</td><td class="what">One as-is / to-be BRD per capability being changed. Nothing for the untouched rest.</td><td class="scripts"><code>bin/brd-report.sh</code> · <code>bin/open-questions.sh --stage 2</code></td></tr>

skills/app-analysis.md

@@ -299,12 +299,12 @@ decided otherwise.
 
 - `skills/module-dependency-review.md`, `skills/microflow-loop-antipatterns.md` (the judgement)
 - `skills/existing-app-assurance.md` (the à-la-carte audit this dossier is the map for)
-- `skills/existing-app-change.md` (the change slice, whose Stage 0 blast radius covers the same
-  ground this dossier already measured). **Not yet wired, as of 2026-09-16.** Neither of those two
-  files mentions the dossier, the facts or this skill, so nothing reads what this produces except
-  `bin/app-report.sh`. The change slice still recomputes its blast radius by hand. Until that is
-  joined, a dossier finding reaches a change slice only because a person carried it, and this
-  section describes an intended relationship, not an implemented one. Do not write a skill
-  description that claims otherwise.
+- `skills/existing-app-change.md` — **wired 2026-09-22.** Its Stage 0a runs this procedure before any
+  slice is named, asks the user to disposition the top findings, and reads the blast radius for Stage
+  0b from `analysis/app-facts/dependencies.json`. In that mode `bin/lib/artifact-manifest.tsv` owes
+  the report (`app-report`, Stage 0), so a map nobody ran reports PENDING. `existing-app-assurance.md`
+  Track A starts from the same report. What is still NOT wired: the dossier itself
+  (`architecture/app-dossier.md`) is not owed by anything, only the rendered report; and nothing
+  re-runs the facts at Stage 6 to show a change left the tangle and loop counts no worse.
 - `skills/lint-that-actually-runs.md`, `skills/report-schema.md`, `skills/measured-claims.md`
 - `skills/skills-over-scripts.md`: the instrument fetches, this file judges; keep it that way