@pareto4/pp-core 1.17.1 → 1.19.0

package/pp-core/bin/lib/vault-mode.cjs

@@ -1,235 +0,0 @@
-"use strict";
-/**
- * src/vault-mode.cts — the vault mode vocabulary (Vault Assurance v1.2,
- * Phase 13-03, D-23).
- *
- * ADR-457 build-at-publish: this TypeScript file is the SOURCE OF TRUTH. It
- * compiles to the git-ignored `pp-core/bin/lib/vault-mode.cjs`; do NOT
- * hand-edit the compiled output. Behaviour is locked by
- * `tests/vault-mode.test.cjs`.
- *
- * `vault.mode` selects which vault shape governs a project: `practices` (the
- * v1.0/v1.1 practice-file matcher, check audit, review and write-back — the
- * default, byte-identical to 1.15.1) or `standards` (prose standards documents
- * indexed by the vault's INDEX.md). This module is the ONE owner of:
- *   - the config key name and the two literals,
- *   - the predicates every mode-aware surface uses,
- *   - the typed reason codes, and
- *   - every not-applicable / refusal text a parked surface prints.
- * A surface that needs to say "not applicable in standards mode" quotes a
- * function from here rather than spelling its own sentence, so the wording
- * cannot drift between the CLI verb, the gate and the workflow that relays it.
- *
- * It does NOT resolve the mode. `resolveVaultMode` lives in
- * `src/org-profile.cts` beside `resolveVaultRequired` (D-05) and reads the
- * project config raw, then the org profile, then `DEFAULT_VAULT_MODE`.
- *
- * It imports NOTHING project-internal (no node builtins either). This is
- * load-bearing: `src/org-profile.cts`, `src/vault.cts`,
- * `src/vault-command-router.cts`, `src/check-command-router.cts` and
- * `src/vault-write-back.cts` all require it, and a leaf with no dependencies
- * cannot close a require cycle among them.
- *
- * Message discipline (T-13-03): no text here takes or echoes a configured
- * value. An unrecognised mode is reported by naming the two allowed literals,
- * never by reproducing what was found, so a hand-edited config cannot inject
- * terminal escapes or agent-directed prose through the refusal.
- */
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.VAULT_MODE_REASON = exports.DEFAULT_VAULT_MODE = exports.VAULT_MODES = exports.VAULT_MODE_CONFIG_KEY = void 0;
-exports.isVaultMode = isVaultMode;
-exports.isStandardsMode = isStandardsMode;
-exports.vaultModeInvalidMessage = vaultModeInvalidMessage;
-exports.vaultModeUnresolvedMessage = vaultModeUnresolvedMessage;
-exports.vaultModeRefusalMessage = vaultModeRefusalMessage;
-exports.notApplicableMatchEnvelope = notApplicableMatchEnvelope;
-exports.notApplicableGateEnvelope = notApplicableGateEnvelope;
-exports.notApplicableReviewStatement = notApplicableReviewStatement;
-exports.notApplicableStandardsVerbMessage = notApplicableStandardsVerbMessage;
-exports.notApplicableStandardsVerbEnvelope = notApplicableStandardsVerbEnvelope;
-exports.notApplicableTraceVerbMessage = notApplicableTraceVerbMessage;
-exports.notApplicableTraceVerbEnvelope = notApplicableTraceVerbEnvelope;
-exports.notApplicableManifestVerbMessage = notApplicableManifestVerbMessage;
-exports.notApplicableManifestVerbEnvelope = notApplicableManifestVerbEnvelope;
-exports.notApplicablePromoteMessage = notApplicablePromoteMessage;
-// ─── Vocabulary ──────────────────────────────────────────────────────────────
-/** The dotted config key. Every other file references it through this constant. */
-exports.VAULT_MODE_CONFIG_KEY = 'vault.mode';
-/** The two recognised modes, in declaration order (matches capability.json `values`). */
-exports.VAULT_MODES = Object.freeze(['practices', 'standards']);
-/** The registered default (capabilities/vault/capability.json `vault.mode.default`). */
-exports.DEFAULT_VAULT_MODE = 'practices';
-/**
- * Machine-stable reason values. Frozen so a typo is a build error rather than
- * a refusal that silently reports a different code. `INVALID` equals
- * `ERROR_REASON.VAULT_MODE_INVALID` in `src/io.cts`; a test pins the equality
- * (this leaf may not import io.cjs, so the two literals are kept apart by
- * design and held together by that test).
- */
-exports.VAULT_MODE_REASON = Object.freeze({
-    INVALID: 'vault_mode_invalid',
-    // 13-REVIEW WR-01: the resolver itself failed (a throw, not a bad value).
-    // Refused exactly like INVALID — never read as the default mode.
-    UNRESOLVED: 'vault_mode_unresolved',
-    NOT_APPLICABLE: 'vault_mode_not_applicable',
-});
-// ─── Predicates ──────────────────────────────────────────────────────────────
-/**
- * True only for a string whose trimmed form is one of the two literals.
- * Case-sensitive: `Practices` is not a mode. Non-strings are never a mode.
- */
-function isVaultMode(value) {
-    if (typeof value !== 'string')
-        return false;
-    const trimmed = value.trim();
-    return exports.VAULT_MODES.includes(trimmed);
-}
-/** True only for the resolved literal `standards`. */
-function isStandardsMode(mode) {
-    return mode === 'standards';
-}
-// ─── Texts ───────────────────────────────────────────────────────────────────
-//
-// The not-applicable texts state only what is true in THIS build (13-REVIEW
-// WR-03). Phase 13 could not name the standards record, which did not exist
-// yet. Phase 15 built it: 15-07's `vault standards block` writes each plan's
-// record and 15-08's standards trace gate validates it. So Phase 15 D-22
-// rewords each parked text to point at that record and gate, and keeps the
-// practices alternative (`config-set vault.mode practices`). The texts spell
-// the record's tag and the SUMMARY heading as copies; tests/vault-mode.test.cjs
-// holds both copies to the vault-standards leaf, which owns them, and checks
-// that every gate point a text names declares a standards trace gate.
-/**
- * The refusal for an unrecognised `vault.mode`. Names both allowed values and
- * where to correct the setting; never takes or echoes the offending value.
- *
- * Names ONLY the places this refusal can come from (13-REVIEW WR-02): a
- * PROJECT value — `resolveVaultMode` level 1 reads the active workstream's
- * config.json and then the root `.planning/config.json`. An invalid org-profile
- * value never reaches here: it is dropped with a warning (D-09) and the mode
- * falls back to the default. The remedy is `config-set`, which writes the
- * planning dir's config — the workstream's when one is active — and so
- * outranks a bad value in either file.
- */
-function vaultModeInvalidMessage() {
-    return ('vault.mode is set to a value this engine does not recognise. ' +
-        'Allowed values: practices, standards. ' +
-        "The value is in the project configuration: .planning/config.json, or the active workstream's " +
-        'config.json on a workstream-partitioned project. ' +
-        'Set it with `pp-tools config-set vault.mode practices` (or `standards`) and run the command again.');
-}
-/**
- * The refusal when `vault.mode` could not be resolved at all (13-REVIEW WR-01):
- * the resolver threw. It is refused exactly like an unrecognised value (D-08)
- * — the engine does not know which mode governs the project, so it assumes
- * neither. Carries no error text: a message could hold a path or a value.
- */
-function vaultModeUnresolvedMessage() {
-    return ('vault.mode could not be resolved: reading the project configuration or the org profile failed. ' +
-        'The vault commands and gates refuse rather than assume a mode. ' +
-        'Check that the project configuration and the org profile can be read, then run the command again.');
-}
-/** The refusal text for a `vaultModeVerdict` `ok: false` reason — the ONE chooser every refusing surface asks. */
-function vaultModeRefusalMessage(reason) {
-    return reason === exports.VAULT_MODE_REASON.UNRESOLVED ? vaultModeUnresolvedMessage() : vaultModeInvalidMessage();
-}
-/**
- * Phase 15 D-22: names the standards record (each plan's block) and the verb
- * that writes it, in place of Phase 13's interim "not yet recorded" clause.
- */
-function notApplicableMatchEnvelope() {
-    return {
-        status: 'not_applicable',
-        mode: 'standards',
-        message: 'vault practices match is not applicable in standards mode (vault.mode = standards): ' +
-            'the client vault carries standards documents, not practice files, so no practice is matched; ' +
-            "the standards record is each plan's `<vault_standards>` block (`vault standards block`). " +
-            'To match practice files instead, run `pp-tools config-set vault.mode practices`.',
-    };
-}
-/**
- * Phase 15 D-22: names the gate that checks the standards record. Both
- * surfaces render only at verify:post and ship:pre, where the vault
- * capability also declares the standards trace gate (a test reads the
- * declarations), so the points this text names are points the gate runs at.
- */
-function notApplicableGateEnvelope(surface) {
-    return {
-        status: 'not_applicable',
-        block: false,
-        mode: 'standards',
-        message: `${surface} is not applicable in standards mode (vault.mode = standards): ` +
-            'there is no practice layer to audit; ' +
-            "the standards `check vault.trace` gate validates each plan's `<vault_standards>` block at verify:post and ship:pre. " +
-            'To use the practices checks instead, run `pp-tools config-set vault.mode practices`.',
-    };
-}
-/**
- * The standards-mode statement of `check vault-review` (D-14). Phase 15 D-22:
- * names where standards mode records the consulted documents.
- */
-function notApplicableReviewStatement() {
-    return ('Vault review: not applicable in standards mode (vault.mode = standards). ' +
-        'No practice was reviewed and no review payload was produced; ' +
-        "standards mode records the consulted documents in each plan's `<vault_standards>` block " +
-        "and its SUMMARY's `## Standards Consulted` section. " +
-        'To review practices instead, run `pp-tools config-set vault.mode practices`.');
-}
-/**
- * The practices-mode answer of `vault standards block|consulted` (15-07). The
- * mirror image of the not-applicable texts above: the standards record verbs
- * have nothing to record while the project runs the practices layer. One line,
- * names the mode the project is in and the way to switch.
- */
-function notApplicableStandardsVerbMessage() {
-    return ('vault standards is not applicable in practices mode (vault.mode = practices): ' +
-        'the practices trace records which practice files applied; ' +
-        'in standards mode `vault standards block` and `vault standards consulted` record the consulted documents. ' +
-        'To record standards documents instead, run `pp-tools config-set vault.mode standards`.');
-}
-function notApplicableStandardsVerbEnvelope() {
-    return { status: 'not_applicable', mode: 'practices', message: notApplicableStandardsVerbMessage() };
-}
-/**
- * Quick 261015-ect (QD-15): the standards-mode answer of `vault trace
- * scaffold|render`. The practices trace ledger is parked beside `vault
- * practices match` (PARK-01): a standards-mode plan carries no practices
- * ledger, so none is produced. Fixed text; nothing is interpolated.
- */
-function notApplicableTraceVerbMessage() {
-    return ('vault trace is not applicable in standards mode (vault.mode = standards): ' +
-        'the practices trace ledger records practice files, and the client vault carries standards documents; ' +
-        "the standards record is each plan's `<vault_standards>` block (`vault standards block`) " +
-        "and the SUMMARY's Standards Consulted section (`vault standards consulted`). " +
-        'To write practices ledgers instead, run `pp-tools config-set vault.mode practices`.');
-}
-function notApplicableTraceVerbEnvelope() {
-    return { status: 'not_applicable', mode: 'standards', message: notApplicableTraceVerbMessage() };
-}
-/**
- * Quick 261015-ect (QD-15): the standards-mode answer of `vault manifest
- * start|record`. The range the manifest anchors is read by `vault audit` and
- * `check vault.review` (both parked, PARK-02/PARK-04) and by `/pp-undo
- * --phase`, which falls back to its git-log search without it.
- */
-function notApplicableManifestVerbMessage() {
-    return ('vault manifest is not applicable in standards mode (vault.mode = standards): ' +
-        'the phase range it anchors is read by `vault audit` and `check vault.review`, which answer not-applicable in this mode, ' +
-        'and by `/pp-undo --phase`, which falls back to its git-log search without it; nothing was written. ' +
-        'To use the practices checks instead, run `pp-tools config-set vault.mode practices`.');
-}
-function notApplicableManifestVerbEnvelope() {
-    return {
-        ok: false,
-        reason: exports.VAULT_MODE_REASON.NOT_APPLICABLE,
-        status: 'not_applicable',
-        mode: 'standards',
-        message: notApplicableManifestVerbMessage(),
-    };
-}
-/** The standards-mode refusal of `vault practices promote` (D-14). */
-function notApplicablePromoteMessage() {
-    return ('This practice was not promoted: vault write-back is not applicable in standards mode ' +
-        '(vault.mode = standards). ' +
-        'Standards documents are maintained in the vault repo through its INDEX.md by the vault owner.');
-}