@event4u/agent-config 14.23.0 → 15.0.0

package/src/scripts/_lib/agent_settings.ts

@@ -293,6 +293,17 @@ export const MERGEABLE_KEYS: readonly string[] = [
     'knowledge.global_sharing.auto_promote_threshold',
     'knowledge.global_sharing.freshness.hypothesis_after_days',
     'knowledge.global_sharing.freshness.stale_after_days',
+    // `design.fidelity_mode` is a per-DEVELOPER working preference, not a
+    // per-project one: whether an agent may deviate from a handed-over design
+    // is a property of how that person works, and a designer who sets it once
+    // expects it in every checkout. `design-fidelity.md` already tells the
+    // reader to resolve it through the cascade — "that file is the project
+    // layer of a cascade that starts user-global" — and the cascade then
+    // filtered it out here, silently, so the rule's own instruction could not
+    // be followed. Class C, so a user still sets it by hand or through the
+    // GUI; whitelisting decides only whether the value SURVIVES the merge
+    // (ADR-271, road-to-design-intent-conformance 2.3).
+    'design.fidelity_mode',
 ];
 
 /** The shipped template, relative to the package root. */
@@ -823,6 +834,80 @@ function _resolve_cascade_paths(
     ];
 }
 
+/** Per-layer read outcome. `absent` and `malformed` are NOT the same fact. */
+export type SettingsLayerState = 'absent' | 'valid' | 'malformed';
+
+export interface SettingsLayerReport {
+    path: string;
+    state: SettingsLayerState;
+}
+
+/**
+ * Probe one settings file WITHOUT merging it, distinguishing absent from broken.
+ *
+ * `_read_yaml` returns `null` for both, which is fine for merging — an absent
+ * layer and an unreadable one contribute nothing either way — and is wrong for
+ * anything that has to decide differently in the two cases. That conflation
+ * silently disabled a documented safety property; see
+ * {@link settings_layer_states}.
+ */
+function _probe_yaml(p: string): SettingsLayerState {
+    if (!_is_file(p)) return 'absent';
+    let YAML: typeof YamlModule;
+    try {
+        YAML = _require('yaml') as typeof YamlModule;
+    } catch {
+        // No parser: this layer cannot be validated, so it is not `valid`.
+        return 'malformed';
+    }
+    try {
+        YAML.parse(fs.readFileSync(p, 'utf-8'), { version: '1.1' });
+        return 'valid';
+    } catch (err) {
+        if (_is_yaml_error(err) || _is_os_error(err)) return 'malformed';
+        throw err;
+    }
+}
+
+/**
+ * Per-layer validity for the layers a caller can actually break.
+ *
+ * A repair, not a feature. `load_agent_settings` merges a broken layer as if it
+ * were absent, so a key's resolved value says nothing about whether the user's
+ * own file parsed — measured 2026-09-10, a project `.agent-settings.yml` of
+ * `:\n  - [\n` returns the template's values and throws nothing. Every reader
+ * shaped `try { …read… } catch { } return <default>` therefore has an
+ * UNREACHABLE catch for that case, and its "fails closed" claim is carried by
+ * its default value rather than by its own code. Worked example and the ruling
+ * that required this: `_lib/continuity_writer.ts` § `auto_record_enabled`.
+ *
+ * Scope is the user-global files and the in-project cascade — the layers a
+ * human edits. The shipped template is excluded deliberately: a malformed
+ * template is a package defect that already resolves every key to absent, so
+ * reporting it would blame a tree in which the user did nothing wrong.
+ *
+ * Reports, never decides. What a `malformed` layer MEANS is the key's polarity,
+ * which belongs to the caller.
+ */
+export function settings_layer_states(
+    options: {
+        project_path?: string | null;
+        user_global_path?: string | null;
+        cwd?: string | null;
+    } = {},
+): SettingsLayerReport[] {
+    const project_path = options.project_path ?? null;
+    const cwd = options.cwd ?? null;
+    const user_global = options.user_global_path
+        ? [options.user_global_path]
+        : user_global_settings_paths();
+    const out: SettingsLayerReport[] = [];
+    for (const p of [...user_global, ..._resolve_cascade_paths(cwd, project_path)]) {
+        out.push({ path: p, state: _probe_yaml(p) });
+    }
+    return out;
+}
+
 /**
  * Return the merged settings dict.
  *

package/src/scripts/_lib/agent_src.ts

@@ -44,6 +44,8 @@ import * as fs from 'node:fs';
 import * as path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
+import { iter_guidelines, resolve_guideline } from './guidelines_lane.js';
+
 // --- Path-root configuration (mutable to mirror Python module attributes) ----
 //
 // the retired Python implementation derives ROOT from `Path(__file__).resolve().parents[3]`
@@ -567,6 +569,18 @@ export function* iter_all_sources(): Generator<[string, string]> {
         seen.add(rel);
         yield [p, rel];
     }
+    // `docs/guidelines/` → logical `guidelines/…`. Appended here rather than
+    // added to `_root_specs` on purpose: `_root_specs` defines the artefact
+    // ESTATE, which the discovery manifest and every count/size ratchet walk,
+    // and a guideline is projected content rather than an estate artefact.
+    // Same shape and the same reason as the domains-commands lane above.
+    for (const [p, rel] of iter_guidelines(_roots.ROOT)) {
+        if (seen.has(rel)) {
+            continue;
+        }
+        seen.add(rel);
+        yield [p, rel];
+    }
 }
 
 /**
@@ -645,6 +659,13 @@ export function resolve_logical(logical_rel: string): string | null {
             }
         }
     }
+    // `guidelines/<subpath>.md` is backed by `docs/guidelines/<subpath>.md`.
+    // Paired with the `iter_all_sources` lane above so the projector's
+    // staleness check and its stale-file sweep both resolve a guideline.
+    const guideline = resolve_guideline(_roots.ROOT, rel);
+    if (guideline !== null) {
+        return guideline;
+    }
     return null;
 }
 

package/src/scripts/_lib/artifact_maturity.ts

@@ -0,0 +1,242 @@
+/**
+ * `spec.maturity` — the artefact-maturity axis as a resolved field with
+ * provenance, not as a prose table two surfaces each keep a copy of.
+ *
+ * The axis itself is already decided. `design-fidelity.md` § Two axes states
+ * it: maturity is a property of the ARTEFACT, mandate is a property of the
+ * INSTRUCTION, and reproducing a wireframe's placeholder greys 1:1 honours the
+ * wrong half of the artefact. `design-fidelity-mechanics § Artefact maturity`
+ * carries the low-versus-finished table. What was missing is a value anything
+ * can read: the table was prose, so every consumer re-derived it by eye and two
+ * consumers could disagree without either being wrong about the text.
+ *
+ * **Two-valued on purpose, and not the same axis as `ReferenceMaturity`.**
+ * `ui_authority.ts` carries a five-valued `ReferenceMaturity`
+ * (`wireframe` | `prototype` | `finished-comp` | `runnable-artifact` |
+ * `production-incumbent`) answering *what kind of thing is this*. This answers
+ * the narrower question the rule actually branches on: *does its pixel detail
+ * carry decisions*. `mapReferenceMaturity` below is the one place the two are
+ * related, so a future edit to either enum has exactly one seam to update
+ * rather than a scattering of `=== 'wireframe'` comparisons.
+ *
+ * **The resolution ladder, and why `finished` is the default.** A user signal
+ * beats everything, then the artefact's own declaration, then inference from
+ * its content, then the default. The default is `finished` because the rule
+ * says so in as many words — *"When the artefact does not declare its maturity,
+ * it is treated as finished: the 1:1 floor is stricter, and guessing low
+ * fidelity would authorise the redesign this rule prevents."* Defaulting the
+ * other way would make silence a licence.
+ */
+
+/** Does the artefact's pixel detail carry decisions, or placeholders? */
+export type ArtifactMaturity = 'low' | 'finished';
+
+/** Which rung of the ladder produced the verdict. */
+export type MaturitySource = 'user' | 'declaration' | 'inference' | 'default';
+
+export interface MaturityVerdict {
+    maturity: ArtifactMaturity;
+    source: MaturitySource;
+    /**
+     * The concrete thing that decided it, quotable back to the user. Never a
+     * restatement of the verdict — "the artefact declares itself a wireframe"
+     * is a signal, "it is low fidelity" is not.
+     */
+    signal: string;
+}
+
+/** Everything the resolver may look at. Every field is optional by design. */
+export interface MaturityInput {
+    /** What the user said this run. Beats every other rung. */
+    userSignal?: ArtifactMaturity | null;
+    /** A `spec.maturity` the artefact carries about itself. */
+    declared?: string | null;
+    /** The artefact's filename, if it has one. */
+    filename?: string | null;
+    /** The artefact's own body — markup, CSS, or a token file's text. */
+    body?: string | null;
+    /** A five-valued `ReferenceMaturity` already resolved elsewhere. */
+    referenceMaturity?: string | null;
+}
+
+/**
+ * The one seam between the five-valued `ReferenceMaturity` and this axis.
+ * Returns `null` for a value that does not decide the question.
+ */
+export function mapReferenceMaturity(value: string | null | undefined): ArtifactMaturity | null {
+    switch (value) {
+        case 'wireframe':
+            return 'low';
+        case 'finished-comp':
+        case 'runnable-artifact':
+        case 'production-incumbent':
+            return 'finished';
+        // `prototype` is deliberately unmapped: the word covers both a greybox
+        // click-through and a pixel-complete interactive build, so mapping it
+        // either way would decide by vocabulary rather than by evidence. It
+        // falls through to inference, which reads the artefact itself.
+        default:
+            return null;
+    }
+}
+
+/** Markers an artefact uses to declare itself low-fidelity. */
+const LOW_DECLARATIONS = new Set(['low', 'low-fidelity', 'lofi', 'lo-fi', 'wireframe', 'sketch']);
+/** Markers an artefact uses to declare itself finished. */
+const FINISHED_DECLARATIONS = new Set([
+    'finished',
+    'final',
+    'high',
+    'high-fidelity',
+    'hifi',
+    'hi-fi',
+    'comp',
+    'production',
+]);
+
+/** Content tells that the pixels are placeholders rather than decisions. */
+const LOW_CONTENT_TELLS: ReadonlyArray<readonly [RegExp, string]> = [
+    [/lorem\s+ipsum/i, 'placeholder copy (lorem ipsum) in the body'],
+    [/\bwireframe\b/i, 'the body calls itself a wireframe'],
+    [/\bgreybox\b|\bgraybox\b/i, 'the body describes greybox placeholders'],
+    // NOT a bare `\bplaceholder\b`. That fired on
+    // `<input placeholder="you@example.com">` in the committed finished
+    // fixture — an ordinary HTML attribute, present in most real forms, and
+    // the single broadest false positive available on this axis. The tell is
+    // the artefact CALLING ITS OWN CONTENT placeholder, so the noun has to
+    // follow.
+    [
+        /placeholder\s+(?:copy|content|text|image|images|art|asset|assets|data)\b/i,
+        'the body marks its own content as placeholder',
+    ],
+];
+
+function normalizeDeclaration(value: string): string {
+    return value.trim().toLowerCase();
+}
+
+/**
+ * True when every colour the body states is greyscale — the canonical wireframe
+ * tell, and the one the rule names by hand ("reproducing a wireframe's
+ * placeholder grays"). Requires at least two colours so a one-off `#fff`
+ * in an otherwise colourless token file does not decide anything.
+ */
+export function isGreyscaleOnly(body: string): boolean {
+    const hexes = body.match(/#[0-9a-fA-F]{3,8}\b/g) ?? [];
+    if (hexes.length < 2) return false;
+    return hexes.every((hex) => {
+        const raw = hex.slice(1);
+        const six =
+            raw.length === 3
+                ? raw
+                      .split('')
+                      .map((c) => c + c)
+                      .join('')
+                : raw.slice(0, 6);
+        if (six.length < 6) return false;
+        const r = parseInt(six.slice(0, 2), 16);
+        const g = parseInt(six.slice(2, 4), 16);
+        const b = parseInt(six.slice(4, 6), 16);
+        return r === g && g === b;
+    });
+}
+
+/**
+ * Resolve the artefact's maturity, naming the signal that decided it.
+ *
+ * Never throws: an unreadable or absent artefact resolves `finished` by
+ * default, which is the conservative direction — see the header.
+ */
+export function resolveArtifactMaturity(input: MaturityInput = {}): MaturityVerdict {
+    /** Set when rung 2 saw a declaration it could not read; reported, not obeyed. */
+    let unreadableDeclaration: string | null = null;
+    const withNote = (v: MaturityVerdict): MaturityVerdict =>
+        unreadableDeclaration === null
+            ? v
+            : {
+                  ...v,
+                  signal: `${v.signal} (the artifact also declares \`maturity: ${unreadableDeclaration}\`, which this resolver does not recognise)`,
+              };
+
+    // 1. The user. `design-fidelity` § Two axes: a user signal beats any
+    //    inference, because the human can see what the heuristic cannot.
+    if (input.userSignal === 'low' || input.userSignal === 'finished') {
+        return {
+            maturity: input.userSignal,
+            source: 'user',
+            signal: `the user stated the artefact is ${input.userSignal} fidelity`,
+        };
+    }
+
+    // 2. The artefact's own declaration — the case the rule's Iron Law names.
+    if (typeof input.declared === 'string' && input.declared.trim() !== '') {
+        const declared = normalizeDeclaration(input.declared);
+        if (LOW_DECLARATIONS.has(declared)) {
+            return {
+                maturity: 'low',
+                source: 'declaration',
+                signal: `the artefact declares \`maturity: ${declared}\``,
+            };
+        }
+        if (FINISHED_DECLARATIONS.has(declared)) {
+            return {
+                maturity: 'finished',
+                source: 'declaration',
+                signal: `the artefact declares \`maturity: ${declared}\``,
+            };
+        }
+        // An unrecognised declaration is NOT silently treated as absent, and it
+        // does NOT short-circuit the ladder either. The first version returned
+        // here, so an artifact declaring `maturity: draft` while carrying a
+        // wireframe filename, a lorem-ipsum body AND a greyscale-only palette
+        // resolved `finished` — an unparseable string outranking three signals
+        // the resolver does recognise, which inverts the ladder this module's
+        // header describes. Blind-review finding. It is remembered instead:
+        // reported on whatever verdict the remaining rungs produce, so the
+        // reader sees both the unreadable declaration and the evidence.
+        unreadableDeclaration = declared;
+    }
+
+    // 3. A ReferenceMaturity already resolved upstream, where it decides.
+    const mapped = mapReferenceMaturity(input.referenceMaturity);
+    if (mapped !== null) {
+        return withNote({
+            maturity: mapped,
+            source: 'inference',
+            signal: `reference_maturity is \`${String(input.referenceMaturity)}\``,
+        });
+    }
+
+    // 4. The filename. Cheap, and the one signal present even when the body is
+    //    not readable.
+    if (typeof input.filename === 'string' && /wireframe|wf-|lofi|lo-fi/i.test(input.filename)) {
+        return withNote({
+            maturity: 'low',
+            source: 'inference',
+            signal: `the filename \`${input.filename}\` names a wireframe`,
+        });
+    }
+
+    // 5. The body.
+    if (typeof input.body === 'string' && input.body !== '') {
+        for (const [pattern, why] of LOW_CONTENT_TELLS) {
+            if (pattern.test(input.body)) {
+                return withNote({ maturity: 'low', source: 'inference', signal: why });
+            }
+        }
+        if (isGreyscaleOnly(input.body)) {
+            return withNote({
+                maturity: 'low',
+                source: 'inference',
+                signal: 'every color in the body is greyscale',
+            });
+        }
+    }
+
+    // 6. Default — finished, deliberately. Silence is not a licence to redesign.
+    return withNote({
+        maturity: 'finished',
+        source: 'default',
+        signal: 'the artifact declares no maturity and shows no low-fidelity tell',
+    });
+}