@pareto4/pp-core 1.22.0 → 1.23.1

package/pp-core/bin/lib/messages/discovery.cjs

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * Catalog slice: discovery messages (Phase 41, plan 41-06). Data only.
+ *
+ * ADR-457 build-at-publish: compiles to the gitignored
+ * `pp-core/bin/lib/messages/discovery.cjs`. Imports nothing but the entry type.
+ *
+ * The `developer` text of every entry is the wording the untouched code printed
+ * (tests/fixtures/message-oracle.json pins it byte for byte). `engineer` and
+ * `business` follow pp-core/references/audience.md: what happened, then what to
+ * do; the session by its number, the section by its title, the line, and the
+ * file in backticks. Slots a reworded text uses beyond the developer text are
+ * listed in `params` and supplied by `src/violation-render.cts`:
+ *   session_number  the session as a number ("3")
+ *   none            the literal a section holds when a session found nothing
+ *   marker          the open-topic marker the checks count
+ *   status_word     the canonical status word, always shown in backticks
+ *   status          the same word relabelled for the audience (label())
+ * The text a person must write stays canonical (D-13); only `status` is a label.
+ * `Ref:` lines are added by the engine at render time, never written here.
+ *
+ * The `discovery.status*` entries (Phase 42, D-07) are the sprint view that
+ * `pp-tools discovery status` prints; `src/discovery-status.cts` supplies every
+ * slot, already cleaned of control and format characters:
+ *   project, done, total, in_progress, pre_filled, not_started  the headline
+ *   session, name, status       a session by number, name and relabelled status
+ *   command                     the command to run next, always shown in backticks
+ *   charter_status              the Project Charter's status word, or a fallback phrase
+ *   sessions                    the session numbers with an unrecognised status
+ *   file                        the progress sheet's path (developer text only)
+ * Only `discovery.status` carries `explain`; the rest are parts of that view.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.discovery = void 0;
+exports.discovery = Object.freeze({
+    // ─── Session check: one entry per violation reason ─────────────────────────
+    'discovery.session.session_missing': {
+        reach: 'business',
+        developer: '  - {artifact}: session_missing',
+        engineer: 'Session {session_number} has no notes file at `{artifact}`. The check needs the file to exist. Run the session so it writes the file, then run the check again.',
+        business: 'Session {session_number} has no notes file yet (`{artifact}`). Hold that session first, then run the check again.',
+        explain: 'The discovery check reads the notes file each session leaves behind. This one does not exist, so there is nothing to check. Run the session, let it write its notes, and check again.',
+        params: ['session_number'],
+    },
+    'discovery.session.template_missing': {
+        reach: 'business',
+        developer: '  - {artifact}: template_missing ({id})',
+        engineer: 'The outline for session {session_number} was not found (`{artifact}`). The check reads each session outline from the pp-core install, so the install is incomplete. Reinstall pp-core, then run the check again.',
+        business: 'The outline for session {session_number} could not be found (`{artifact}`). Ask Pareto to repair your pp-core installation, then run the check again.',
+        explain: 'Each session has an outline that lists the sections its notes must hold. The check could not find the outline for this session, which means the pp-core installation is missing a file. Reinstalling pp-core fixes it.',
+        params: ['session_number'],
+    },
+    'discovery.session.missing_section': {
+        reach: 'business',
+        developer: '  - {artifact}: missing_section ({id})',
+        engineer: 'Session {session_number} has no section titled "{id}" in `{artifact}`. The session outline requires every section exactly once. Add the section under its bold title, then run the check again.',
+        business: 'Session {session_number} has no section called "{id}" in `{artifact}`. Add that section with exactly that title, then run the check again.',
+        explain: 'Every session outline lists sections the notes must hold, each under its own bold title. A section that is not there counts as not covered, so the session cannot score full marks. Add the section with the exact title from the outline.',
+        params: ['session_number'],
+    },
+    'discovery.session.duplicate_section': {
+        reach: 'business',
+        developer: '  - {artifact}:{line}: duplicate_section ({id})',
+        engineer: 'Session {session_number} holds the section "{id}" more than once; the second copy starts at line {line} of `{artifact}`. The outline allows each section once. Merge or delete the extra copy, then run the check again.',
+        business: 'Session {session_number} has the section "{id}" twice; the second one starts at line {line} of `{artifact}`. Merge the two into one, then run the check again.',
+        explain: 'Each section may appear once in a session file, so the check knows which one to read. A second copy makes that unclear. Keep one copy that holds everything, and remove the other.',
+        params: ['session_number'],
+    },
+    'discovery.session.bad_table_shape': {
+        reach: 'business',
+        developer: '  - {artifact}:{line}: bad_table_shape ({id})',
+        engineer: 'The table in section "{id}" of session {session_number} (line {line} of `{artifact}`) does not match the outline: its columns differ from the header the outline defines. Make the header row match the outline, then run the check again.',
+        business: 'The table in section "{id}" of session {session_number} (line {line} of `{artifact}`) has the wrong columns. Make its columns match the session outline, then run the check again.',
+        explain: 'Tables in the session notes are read by column, so their columns must be the ones the outline names, in the same order. Compare the header row with the outline of the session and correct it.',
+        params: ['session_number'],
+    },
+    'discovery.session.empty_section': {
+        reach: 'business',
+        developer: '  - {artifact}:{line}: empty_section ({id})',
+        engineer: 'Section "{id}" of session {session_number} is empty (line {line} of `{artifact}`). The check needs at least one row or line of text, or `{none}` on its own line under the title. Fill the section, then run the check again.',
+        business: 'Section "{id}" of session {session_number} has nothing in it (line {line} of `{artifact}`). Add what the session found, or write `{none}` under the title, then run the check again.',
+        explain: 'A section that is empty is counted as not covered. If the session found nothing to record, say so with the exact sentence the check expects, on its own line under the section title. Otherwise add what the session found.',
+        params: ['session_number', 'none'],
+    },
+    'discovery.session.artifact_unreadable': {
+        reach: 'business',
+        developer: '  - {artifact}: artifact_unreadable',
+        engineer: 'The notes file `{artifact}` for session {session_number} exists but could not be read. It may be a folder or lack read permission. Fix that, then run the check again.',
+        business: 'The notes file for session {session_number} (`{artifact}`) could not be opened. Check that it is a normal file you can open, then run the check again.',
+        explain: 'The check found something at the place where the session notes belong, but could not read it. This usually means it is a folder instead of a file, or its permissions block reading. Put the notes file back in place.',
+        params: ['session_number'],
+    },
+    discovery_session_check_failed: {
+        reach: 'business',
+        developer: 'discovery session-check: {count} violation(s):\n{lines}',
+        engineer: 'The discovery session check found {count} problem(s):\n{lines}\nFix each one in its session file, then run the check again.',
+        business: 'Your discovery notes have {count} to fix:\n{lines}\nFix each one, then run the check again.',
+        explain: 'The session check reads the notes of each discovery session and compares them with the session outline. Each problem above names the session, the section and the file. Fix them one by one and run the check again until none are left.',
+        rawParams: ['lines'],
+    },
+    // ─── Input check ───────────────────────────────────────────────────────────
+    'discovery.input.completed_with_unconfirmed': {
+        reach: 'business',
+        developer: '  {session}: completed_with_unconfirmed (markers: {markers})',
+        engineer: 'Session {session_number} (`{session}`) is {status}, but `{marker}` still appears {markers} time(s) in it. The file says `{status_word}`. Resolve each open topic and remove its `{marker}`, then run the check again.',
+        business: 'Session {session_number} (`{session}`) counts as {status}, but `{marker}` still appears {markers} time(s) in it. The file says `{status_word}`; settle each open topic and remove its `{marker}`, then run the check again.',
+        explain: 'A session may only be closed when nothing in it is still waiting for confirmation. The marker shows a topic someone has not confirmed yet. Confirm each topic and remove the marker, then check again.',
+        params: ['session_number', 'marker', 'status', 'status_word'],
+    },
+    'discovery.input.score_counts_unconfirmed': {
+        reach: 'business',
+        developer: '  {session}: score_counts_unconfirmed (score: {score}, markers: {markers})',
+        engineer: 'Session {session_number} (`{session}`) scores {score} while topics are still unconfirmed (`{marker}` count: {markers}, or the session is still pre-filled). Confirm what is open and complete the session, or lower the score, then run the check again.',
+        business: 'Session {session_number} (`{session}`) scores {score} but still counts topics nobody has confirmed (`{marker}` count: {markers}). Confirm what is open and complete the session, or lower the score, then run the check again.',
+        explain: 'A full score means every topic of the session is confirmed. A topic still waiting for confirmation, or a session that was only prepared from documents, cannot count as covered. Confirm the open topics before the session scores full marks.',
+        params: ['session_number', 'marker'],
+    },
+    'discovery.input.confidential_tracked': {
+        reach: 'business',
+        developer: '  {file}: confidential_tracked',
+        engineer: 'The confidential input file `{file}` is tracked by git, so it would travel with the repository. Remove it from tracking (for example with `git rm --cached`) and keep it ignored, then run the check again.',
+        business: 'The private file `{file}` has been added to the project, and private files must stay out of it. Ask an engineer to take it out again; your own copy stays where it is.',
+        explain: 'Files in the confidential input folder must never be saved with the project, because everyone who gets the project would get them too. Take the file out of the project but keep your copy, and the check passes.',
+    },
+    discovery_input_check_failed: {
+        reach: 'business',
+        developer: 'discovery input-check: {count} violation(s):\n{lines}',
+        engineer: 'The discovery input check found {count} problem(s):\n{lines}\nFix each one, then run the check again.',
+        business: 'Your discovery input has {count} to fix:\n{lines}\nFix each one, then run the check again.',
+        explain: 'The input check looks at the discovery sessions that are closed or scored, and at the private input folder. Each problem above names the file to look at. Fix them one by one and run the check again until none are left.',
+        rawParams: ['lines'],
+    },
+    // ─── discovery status view (Phase 42, D-07) ────────────────────────────────
+    'discovery.status': {
+        reach: 'business',
+        developer: '## Discovery Sprint — {project}',
+        engineer: '## Discovery Sprint: {project}',
+        business: '## Discovery Sprint — {project}',
+        explain: 'This view shows where the Discovery Sprint stands: how many sessions are done, the state of each session, where the work stopped, and the step to take next. The next step is the one `/pp-discovery` recommends when you run it without a number.',
+    },
+    'discovery.status.counts': {
+        reach: 'business',
+        developer: 'Completed: {done}/{total} · In Progress: {in_progress} · Pre-Filled: {pre_filled} · Not Started: {not_started}',
+        engineer: '{done} of {total} sessions completed · {in_progress} in progress · {pre_filled} pre-filled from documents · {not_started} not started',
+        business: '{done} of {total} sessions done · {in_progress} being worked on · {pre_filled} prepared from your documents · {not_started} not started yet',
+        part: true,
+    },
+    'discovery.status.header': {
+        reach: 'business',
+        developer: '| # | Session | Status |\n|---|---------|--------|',
+        engineer: '| # | Session | Status |\n|---|---------|--------|',
+        business: '| # | Session | Where it stands |\n|---|---------|-----------------|',
+        part: true,
+    },
+    'discovery.status.stopped.in_progress': {
+        reach: 'business',
+        developer: 'Stopped at: Session {session} — {name} ({status})',
+        engineer: 'Stopped at session {session}, {name} ({status}).',
+        business: 'You stopped in session {session}, {name} ({status}).',
+        part: true,
+    },
+    'discovery.status.stopped.completed': {
+        reach: 'business',
+        developer: 'Last completed: Session {session} — {name}',
+        engineer: 'The last completed session is session {session}, {name}.',
+        business: 'The last session finished was session {session}, {name}.',
+        part: true,
+    },
+    'discovery.status.stopped.none': {
+        reach: 'business',
+        developer: 'Stopped at: not started yet',
+        engineer: 'No session has been started yet.',
+        business: 'No session has been held yet.',
+        part: true,
+    },
+    'discovery.status.next.resume': {
+        reach: 'business',
+        developer: 'Next: resume Session {session} — {name}. Run `{command}`.',
+        engineer: 'Next: resume session {session}, {name}, which is in progress. Run `{command}` to continue.',
+        business: 'Next: carry on with session {session}, {name}. Type `{command}` to continue.',
+        part: true,
+    },
+    'discovery.status.next.confirm': {
+        reach: 'business',
+        developer: 'Next: confirm Session {session} — {name} (Pre-Filled). Run `{command}` to walk its open markers.',
+        engineer: 'Next: confirm session {session}, {name}, which was pre-filled from documents. Run `{command}` to walk its open markers.',
+        business: 'Next: check session {session}, {name}, which was prepared from your documents. Type `{command}` to go through what still needs your confirmation.',
+        part: true,
+    },
+    'discovery.status.next.start': {
+        reach: 'business',
+        developer: 'Next: start Session {session} — {name}. Run `{command}`.',
+        engineer: 'Next: start session {session}, {name}. Run `{command}`.',
+        business: 'Next: start session {session}, {name}. Type `{command}` to begin.',
+        part: true,
+    },
+    'discovery.status.next.charter_draft': {
+        reach: 'business',
+        developer: 'Next: every session is done and there is no Project Charter. Run `{command}` to draft it.',
+        engineer: 'Next: every session is completed, but the Project Charter has not been drafted. Run `{command}` to draft it.',
+        business: 'Next: every session is done. The Project Charter has not been written yet. Type `{command}` to draft it.',
+        part: true,
+    },
+    'discovery.status.next.charter_sign': {
+        reach: 'business',
+        developer: 'Next: the Project Charter is {charter_status}, not signed. Run `{command}` to record signatures.',
+        engineer: "Next: the Project Charter's status is {charter_status}, so it still needs signing. Run `{command}` to record the signatures.",
+        business: 'Next: the Project Charter is not signed yet (it says: {charter_status}). Type `{command}` to record the signatures.',
+        part: true,
+    },
+    'discovery.status.next.to_build': {
+        reach: 'business',
+        developer: 'Next: the Project Charter is signed. Run `{command}`.',
+        engineer: "Next: the Project Charter is signed. Run `{command}` to set the build up from the sprint's results.",
+        business: 'Next: the Project Charter is signed. Type `{command}` to start building from what the sprint agreed.',
+        part: true,
+    },
+    'discovery.status.next.check_sheet': {
+        reach: 'business',
+        developer: 'Next: correct the unrecognised status first, then run `{command}`.',
+        engineer: 'Next: correct the unrecognised status in the tracker first, so a finished session is not run again. Then run `{command}` to carry on.',
+        business: 'Next: check the unexpected state in the progress sheet first, so a session already held is not held again. Then type `{command}` to carry on.',
+        part: true,
+    },
+    'discovery.status.unknown_status': {
+        reach: 'business',
+        developer: 'Unrecognised status in session(s) {sessions}; counted as not started.',
+        engineer: 'Session(s) {sessions} have a status this view does not recognise; they are counted as not started.',
+        business: 'The progress sheet shows an unexpected state for session(s) {sessions}; they are counted as not started yet.',
+        part: true,
+    },
+    'discovery.status.project_unknown': {
+        reach: 'business',
+        developer: '(unnamed project)',
+        engineer: 'unnamed project',
+        business: 'your project',
+        part: true,
+    },
+    'discovery.status.session_unnamed': {
+        reach: 'business',
+        developer: '(no name)',
+        engineer: '(no name in the tracker)',
+        business: '(no name given)',
+        part: true,
+    },
+    'discovery.status.charter_no_status': {
+        reach: 'business',
+        developer: 'without a status',
+        engineer: 'missing',
+        business: 'no status yet',
+        part: true,
+    },
+    'discovery.status.unreadable': {
+        reach: 'business',
+        developer: 'Discovery Sprint tracker `{file}` could not be read (no Session Progress table). Run `{command}`.',
+        engineer: 'This project is in the Discovery Sprint, but the session table in its sprint tracker could not be read, so the sessions cannot be shown. Run `{command}` to see the sprint and carry on.',
+        business: 'This project is in the Discovery Sprint, but its progress sheet could not be read, so the sessions cannot be shown here. Type `{command}` to see where the sprint stands and carry on.',
+        explain: 'The sprint keeps one progress sheet with a table of its sessions. The sheet exists, but the table is missing or damaged, so this view cannot count the sessions. The project still counts as being in the Discovery Sprint, and `/pp-discovery` shows the sprint directly.',
+    },
+    'discovery.status.none': {
+        reach: 'business',
+        developer: 'No Discovery Sprint in this project (no `{file}`). Run `{command}` to start one.',
+        engineer: 'This project has no Discovery Sprint: there is no sprint tracker yet. Run `{command}` to start one.',
+        business: 'This project has no Discovery Sprint yet. Type `{command}` to start one.',
+        explain: 'The progress sheet is how a project shows it is in the Discovery Sprint. This project has none, so there is no sprint to show. `/pp-discovery 1` starts the sprint and creates the sheet.',
+    },
+});

package/pp-core/bin/lib/messages/gate.cjs

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * Catalog slice: stopped-check cards (Phase 43, TPL-02; D-09, D-10). Data only.
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/messages/gate.cjs`; do NOT
+ * hand-edit the compiled output. Imports nothing but the entry type.
+ *
+ * One facts table (`GATE_FACTS`) holds, per quality check, its name, the reason
+ * it stops a step and what to do about it, once for a business user and once
+ * for a business engineer. The catalog entries are built from it with three
+ * frames written once, so every card reads the same way (D-10):
+ *
+ *   blocked:  The {name} check stopped this step: {why}. What to do: {action}.
+ *   advisory: The {name} check found something to look at, and this step carries on: {why}. What to do: {action}.
+ *   error:    The {name} check could not run, so its answer is missing. What to do: if this step stopped, run it again; ...
+ *
+ * The error frame reads true on both command-error paths: the step stopped
+ * (`onError: halt`) or it carried on without the answer (`onError: skip`).
+ *
+ * The `developer` text of every entry is the line the shipped workflow prints
+ * today, byte for byte, glyph included: check-query-gate.md (blocked, advisory
+ * and command-error lines), the vault-fetch.md STRICT-03 line, the plan-phase.md
+ * decision-coverage fallback and the `vault admission --explain` repair line.
+ * The capability lines keep `{point}` as the only slot; the query name is
+ * inserted at build time.
+ *
+ * Business and engineer text uses no slot: the check's name, reason and next step
+ * are fixed words, so nothing typed or read from a file reaches the card. Business
+ * text follows pp-core/references/audience.md (no hidden term, no glossary
+ * term); engineer text keeps real terms and never a term hidden from both.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gate = exports.GATE_QUERIES = exports.GATE_FACTS = exports.GATE_STATES = void 0;
+exports.GATE_STATES = ['blocked', 'advisory', 'error'];
+const ALL = exports.GATE_STATES;
+const BLOCKED_ONLY = ['blocked'];
+exports.GATE_FACTS = Object.freeze([
+    {
+        query: 'vault.trace',
+        states: ALL,
+        business: {
+            name: 'standards record',
+            why: "some of the work does not say which of your organisation's standards it followed",
+            action: 'ask me to list what is missing, then plan that part again',
+        },
+        engineer: {
+            name: 'standards record',
+            why: "a plan has no valid standards block, or a summary's Standards Consulted section does not match the standards that were loaded",
+            action: "fix the plan's standards block or the summary's section named in the details, then run this step again",
+        },
+        explain: "This check looks at each plan and each finished summary and asks whether it says which of your organisation's standards the work followed. It stops the step when a record is missing or does not match what was loaded, because the standards are only a promise if every piece of work shows it used them.",
+    },
+    {
+        query: 'vault.status',
+        states: ALL,
+        business: {
+            name: 'organisation standards',
+            why: "your organisation's standards are missing, out of date or did not load",
+            action: 'ask me to load them again, or ask your Pareto contact to fix the connection',
+        },
+        engineer: {
+            name: 'standards vault',
+            why: 'the standards vault is missing, stale or did not load, and `vault.required` is on',
+            action: 'load the vault again, or check the vault connection and `vault.cache_ttl_hours`',
+        },
+        explain: "This check looks at whether your organisation's standards are present, recent and loaded for this project. When the project requires them and they are not there, the step stops, so work is never built without the standards it was meant to follow.",
+    },
+    {
+        query: 'ship.platform-drift',
+        states: ALL,
+        business: {
+            name: 'platform version',
+            why: 'the platform version this project uses is behind the newest one by more than your settings allow',
+            action: 'ask me to update it, or ask your Pareto contact whether to carry on with this version',
+        },
+        engineer: {
+            name: 'platform version',
+            why: 'the platform tag pinned in `.platform-bindings.json` is behind the latest by at least the level set in `pareto.drift_block_on`',
+            action: 'update the pinned tag, or raise `pareto.drift_block_on` if staying on this version is intended',
+        },
+        explain: 'This check compares the platform version your project uses with the newest one. A small gap is only noted; a gap larger than your settings allow stops the step, so you do not ship on a version that is far behind.',
+    },
+    {
+        query: 'verify.schema-drift',
+        states: ALL,
+        business: {
+            name: 'data structure',
+            why: 'the data structure files changed but the matching update was not applied',
+            action: 'ask me to apply the update before testing',
+        },
+        engineer: {
+            name: 'schema',
+            why: 'schema or ORM files changed and the matching migration or push was not applied',
+            action: 'apply the migration, then run the verification again',
+        },
+        explain: 'This check notices when the files that describe your data structure changed but the update that applies them to the database was not run. Testing against a database that does not match the code gives answers that cannot be trusted, so the step stops until the update is applied.',
+    },
+    {
+        query: 'verify.codebase-drift',
+        states: ALL,
+        business: {
+            name: 'code map',
+            why: 'the saved map of the code is out of date',
+            action: 'ask me to refresh the map',
+        },
+        engineer: {
+            name: 'codebase map',
+            why: 'files or folders were added or moved since `STRUCTURE.md` was written, so it no longer matches the code',
+            action: 'refresh the map with `/pp-map-codebase`',
+        },
+        explain: 'This check compares the saved map of your code with what is in the project now. When new files or folders appeared that the map does not show, it stops the step, because later work leans on that map to find its way around.',
+    },
+    {
+        query: 'ui.safety-gate',
+        states: ALL,
+        business: {
+            name: 'screen design',
+            why: 'screens were built without a screen design',
+            action: 'create the screen design first, or tell me to carry on without one',
+        },
+        engineer: {
+            name: 'UI design contract',
+            why: 'UI files changed in a frontend phase and no `UI-SPEC.md` exists',
+            action: 'run `/pp-ui-phase` to write `UI-SPEC.md`, or choose to continue without it',
+        },
+        explain: 'This check looks at stages that build screens. If screen files were changed and there is no screen design for the stage, it stops the step, so the screens are built against an agreed design and not guessed.',
+    },
+    {
+        query: 'ui.plan-gate',
+        states: ALL,
+        business: {
+            name: 'screen design',
+            why: 'screens are being planned without a screen design',
+            action: 'design the screens first, or tell me to plan without a design',
+        },
+        engineer: {
+            name: 'UI design contract',
+            why: 'a frontend phase is being planned and no `UI-SPEC.md` exists',
+            action: 'run `/pp-ui-phase` to write `UI-SPEC.md` first, or choose to plan without it',
+        },
+        explain: 'This check looks at stages that include screens. If the stage has no screen design yet, it stops planning, so the plan is written against an agreed design and not against a guess.',
+    },
+    {
+        query: 'tdd.review-checkpoint',
+        states: ALL,
+        business: {
+            name: 'test-first',
+            why: 'some work meant to be built test-first is missing its test step or its build step',
+            action: 'ask me which plans, then decide whether to add the missing step',
+        },
+        engineer: {
+            name: 'TDD review',
+            why: 'a `type: tdd` plan lacks its `test(...)` commit or its `feat(...)` commit',
+            action: 'see which plans in the details, then decide whether to add the missing commit',
+        },
+        explain: 'This check looks at plans that are meant to be built test-first: a test is written and seen to fail, then the code is written to make it pass. When a plan is missing one of those two steps, the check tells you, so you can decide whether to add it.',
+    },
+    {
+        query: 'gap-analysis.plan-post',
+        states: ALL,
+        business: {
+            name: 'requirement coverage',
+            why: 'some requirements or decisions are not in any plan yet',
+            action: 'ask me to add them to a plan or move them to a later stage',
+        },
+        engineer: {
+            name: 'requirement coverage',
+            why: 'some requirement or decision IDs from `REQUIREMENTS.md` and `CONTEXT.md` appear in no `PLAN.md`',
+            action: 'add them to a plan, or move them to a later phase',
+        },
+        explain: 'After a stage is planned, this check lists every requirement and decision and shows which ones no plan mentions. It only tells you; it never stops the work by itself.',
+    },
+    {
+        query: 'vault.admission',
+        states: BLOCKED_ONLY,
+        business: {
+            name: 'standards connection',
+            why: 'a project settings file the standards connection needs cannot be read',
+            action: 'ask your Pareto contact to repair that file, then run this again',
+        },
+        engineer: {
+            name: 'standards vault admission',
+            why: 'a settings file it must read, named under Details, is not valid JSON, so the check refuses to pass having checked nothing',
+            action: 'fix the JSON in that file or remove the key that broke it, then run this again',
+        },
+        explain: "Before any step that uses your organisation's standards, this check reads the project settings that say whether the standards apply. If one of those files is broken it cannot tell, and it stops instead of letting the work through unchecked. The file and the problem are listed under Details.",
+        developer: '{file}: {error} — repair: fix the JSON in {file} (or remove the key that broke it) and re-run; ' +
+            'the gate cannot read this file and refuses to pass having checked nothing',
+    },
+    {
+        query: 'vault.fetch',
+        states: BLOCKED_ONLY,
+        business: {
+            name: 'organisation standards',
+            why: "your organisation's standards could not be loaded, and this project requires them",
+            action: 'run this step again; if it fails again, ask your Pareto contact',
+        },
+        engineer: {
+            name: 'standards vault',
+            why: 'the vault could not be fetched or its summary could not be written, and `vault.required` is on',
+            action: 'run this step again; if it fails again, check the vault connection or ask your Pareto contact',
+        },
+        explain: "This check runs when a step starts. If your organisation's standards could not be loaded and the project says they are required, the step stops, so nothing is built without them.",
+        developer: '✗ vault could not be loaded and vault.required is true (STRICT-03)',
+    },
+    {
+        query: 'decision-coverage',
+        states: BLOCKED_ONLY,
+        business: {
+            name: 'decisions',
+            why: 'some decisions you made are not used in any plan yet',
+            action: 'ask me to plan again so each decision is covered, or mark it as one the assistant may decide',
+        },
+        engineer: {
+            name: 'decision coverage',
+            why: 'some decisions in `CONTEXT.md` are cited by no plan',
+            action: "cite each as `D-NN` in a plan, or move it to the Claude's Discretion section of `CONTEXT.md`",
+        },
+        explain: 'After a stage is planned, this check compares the decisions you made with the plans. If one of your decisions is not used in any plan, planning stops, so a decision you took is never quietly dropped.',
+        developer: 'Decision coverage gate failed.',
+    },
+]);
+exports.GATE_QUERIES = Object.freeze(exports.GATE_FACTS.map((f) => f.query));
+const DEV_FRAMES = {
+    blocked: (q) => `⚠ Gate blocked at {point} (${q}). Resolve before continuing.`,
+    advisory: (q) => `ℹ Gate advisory at {point} (${q}). Continuing.`,
+    error: (q) => `⚠ Gate check command failed ({point} / ${q}): command error. Resolve before continuing.`,
+};
+function card(state, w, who) {
+    if (state === 'blocked')
+        return `The ${w.name} check stopped this step: ${w.why}. What to do: ${w.action}.`;
+    if (state === 'advisory') {
+        return `The ${w.name} check found something to look at, and this step carries on: ${w.why}. What to do: ${w.action}.`;
+    }
+    return who === 'business'
+        ? `The ${w.name} check could not run, so its answer is missing. What to do: if this step stopped, run it again; if it stops the same way, give your Pareto contact the code below.`
+        : `The ${w.name} check could not run, so its answer is missing. What to do: if this step stopped, run it again; if it stops the same way, run \`pp-tools explain\` with the code below and share what it prints with your Pareto contact.`;
+}
+function build() {
+    const out = {};
+    for (const f of exports.GATE_FACTS) {
+        for (const state of f.states) {
+            out[`gate.${f.query}.${state}`] = {
+                reach: 'business',
+                developer: f.developer ?? DEV_FRAMES[state](f.query),
+                engineer: card(state, f.engineer, 'engineer'),
+                business: card(state, f.business, 'business'),
+                explain: f.explain,
+            };
+        }
+    }
+    for (const code of Object.keys(out))
+        Object.freeze(out[code]);
+    return Object.freeze(out);
+}
+exports.gate = build();

package/pp-core/bin/lib/messages/hook.cjs

@@ -0,0 +1,114 @@
+"use strict";
+/**
+ * Catalog slice: the statusline and the update banner (Phase 43, MSG-06; D-17..D-20). Data only.
+ *
+ * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
+ * compiles to the gitignored `pp-core/bin/lib/messages/hook.cjs`; do NOT
+ * hand-edit the compiled output. Imports nothing but the entry type.
+ *
+ * The `developer` text of every entry is the string the hooks print today,
+ * byte for byte (PR #36's command names included), so a developer's statusline
+ * and update notice do not change (D-17). The statusline entries are fragments
+ * (`part: true`): they never carry a `Ref:` line, because the statusline is one
+ * line of a status bar. The two banner entries are whole messages and end with
+ * a `Ref:` line for a business user and an engineer.
+ *
+ * The hooks load this slice through the light entry `hook-messages.cjs`, never
+ * through `messages.cjs` (D-18), and fall back to the developer text when the
+ * slice cannot load (D-20). ANSI colour codes stay in the hooks, never here.
+ *
+ * Business wording follows pp-core/references/audience.md: "stage" for phase
+ * and "release" for milestone, no internal word. The lifecycle words and next
+ * actions that fill `{stage}` and `{action}` are relabelled by the hook before
+ * they reach this slice (`state.status`, `state.next_action` in message-labels).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hook = void 0;
+exports.hook = Object.freeze({
+    // ─── statusline fragments ──────────────────────────────────────────────────
+    'hook.statusline.update': {
+        reach: 'business',
+        developer: '⬆ /pp-update',
+        engineer: '⬆ update ready: /pp-update',
+        business: '⬆ new version ready: /pp-update',
+        part: true,
+    },
+    'hook.statusline.stale': {
+        reach: 'business',
+        developer: '⚠ stale hooks — run /pp-update',
+        engineer: '⚠ pp-core hooks out of date — run /pp-update',
+        business: '⚠ pp-core needs an update — run /pp-update',
+        part: true,
+    },
+    'hook.statusline.dev_install': {
+        reach: 'business',
+        developer: '⚠ dev install — re-run installer to sync hooks',
+        engineer: '⚠ development install — re-run the installer to sync hooks',
+        business: '⚠ pp-core needs reinstalling — ask your Pareto contact',
+        part: true,
+    },
+    'hook.statusline.phase': {
+        reach: 'business',
+        developer: 'Phase {number}',
+        engineer: 'Phase {number}',
+        business: 'Stage {number}',
+        part: true,
+    },
+    'hook.statusline.phase_stage': {
+        reach: 'business',
+        developer: 'Phase {number} {stage}',
+        engineer: 'Phase {number}: {stage}',
+        business: 'Stage {number}: {stage}',
+        part: true,
+    },
+    'hook.statusline.next': {
+        reach: 'business',
+        developer: 'next {action} {numbers}',
+        engineer: 'next: {action} {numbers}',
+        business: 'next: {action} {numbers}',
+        part: true,
+    },
+    'hook.statusline.milestone_complete': {
+        reach: 'business',
+        developer: 'milestone complete',
+        engineer: 'milestone complete (all phases done)',
+        business: 'release complete',
+        part: true,
+    },
+    'hook.statusline.phase_count': {
+        reach: 'business',
+        developer: 'ph {num}/{total}',
+        engineer: 'phase {num}/{total}',
+        business: 'stage {num} of {total}',
+        part: true,
+    },
+    'hook.statusline.phase_named': {
+        reach: 'business',
+        developer: '{name} ({num}/{total})',
+        engineer: '{name} (phase {num}/{total})',
+        business: '{name} (stage {num} of {total})',
+        part: true,
+    },
+    'hook.statusline.status_shipped': {
+        reach: 'business',
+        developer: 'Phase {number} shipped — PR #{pr}',
+        engineer: 'phase {number} shipped (PR #{pr})',
+        business: 'stage {number} sent for review (#{pr})',
+        part: true,
+    },
+    // ─── update banner ─────────────────────────────────────────────────────────
+    'hook.banner.update_available': {
+        reach: 'business',
+        developer: 'pp-core update available: {installed} → {latest}. Run /pp-update.',
+        engineer: 'pp-core {latest} is available (you have {installed}). Run /pp-update to install it.',
+        business: 'A new version of pp-core is ready ({installed} → {latest}). Type /pp-update to install it.',
+        explain: 'A newer version of pp-core is available. Nothing has changed on your machine yet: typing /pp-update installs it, and your work stays as it is.',
+    },
+    'hook.banner.check_failed': {
+        reach: 'business',
+        developer: 'pp-core update check failed.',
+        engineer: 'pp-core could not check for updates; it tries again next session.',
+        business: 'pp-core could not check for a new version. You can carry on; it will try again next time.',
+        explain: 'pp-core looks for a newer version when a session starts, and this time it could not reach the answer. Nothing is wrong with your work, and the notice appears at most once a day.',
+    },
+});