@event4u/agent-config 14.10.0 → 14.12.0

package/src/agent-src/templates/scripts/work_engine/directives/ui/scaffold.ts

@@ -59,6 +59,146 @@ export const BRAND_TOKEN_PATHS: ReadonlyArray<string> = [
     'agents/settings/brand/tokens.json',
 ];
 
+/**
+ * Conventional location of the project's `Playbook` contexts (ADR-244).
+ *
+ * A playbook is this repository's OWN procedure for a task, and it outranks a shipped
+ * skill: the generic skill answers a generic question, while the playbook carries decisions
+ * the repository already made (file layout, barrel exports, naming) that no shipped skill
+ * can know. Mirrors {@link BRAND_TOKEN_PATHS} deliberately — same acyclic,
+ * degrades-gracefully shape: present → the repository's command is proposed first, absent →
+ * nothing is emitted and the lane is byte-identical.
+ */
+export const PLAYBOOK_HOME = path.join('agents', 'settings', 'contexts');
+
+/** A playbook the lane may act on: `configured` grade, matching scope, non-empty `invokes`. */
+export interface ScaffoldPlaybook {
+    readonly file: string;
+    readonly task: string;
+    readonly invokes: readonly string[];
+}
+
+/**
+ * Read a playbook's head. Only `configured` playbooks with a `scope` that covers
+ * `scope_root` are returned — an `observed` playbook is advisory (per the
+ * `playbook-precedence` rule) and MUST NOT be dispatched ahead of a shipped skill, because
+ * at least one of its ids was never resolved in the tree.
+ */
+export function _read_playbook(file: string, scope_root: string): ScaffoldPlaybook | null {
+    let text = '';
+    try {
+        text = fs.readFileSync(file, 'utf8');
+    } catch {
+        return null;
+    }
+    if (!text.startsWith('---')) return null;
+    const end = text.indexOf('\n---', 3);
+    if (end < 0) return null;
+    const head = text.slice(3, end);
+
+    const grade = /^grade:\s*["']?([A-Za-z]+)["']?\s*$/m.exec(head);
+    if (grade === null || grade[1] !== 'configured') return null;
+
+    const scope = /^scope:\s*["']?(.+?)["']?\s*$/m.exec(head);
+    const scope_value = scope?.[1] ?? '';
+    // `repo` covers everything; otherwise the playbook's scope must be a prefix of the
+    // project's scope_root (or equal to it). A partial match is NOT a match — a playbook
+    // for `packages/ui` says nothing about `packages/api`.
+    const in_scope =
+        scope_value === 'repo' ||
+        (scope_value !== '' && (scope_root === scope_value || scope_root.startsWith(`${scope_value}/`)));
+    if (!in_scope) return null;
+
+    const task = /^task:\s*["']?(.+?)["']?\s*$/m.exec(head);
+    const invokes: string[] = [];
+    let in_list = false;
+    for (const line of head.split('\n')) {
+        if (/^invokes:\s*$/.test(line)) {
+            in_list = true;
+            continue;
+        }
+        if (in_list) {
+            const item = /^\s+-\s*["']?(.+?)["']?\s*$/.exec(line);
+            if (item?.[1] !== undefined) {
+                invokes.push(item[1]);
+                continue;
+            }
+            in_list = false;
+        }
+        const inline = /^invokes:\s*\[(.*)\]\s*$/.exec(line);
+        if (inline?.[1] !== undefined) {
+            for (const part of inline[1].split(',')) {
+                const v = part.trim().replace(/^["']|["']$/g, '');
+                if (v.length > 0) invokes.push(v);
+            }
+        }
+    }
+    // A `configured` playbook with no ids cannot be dispatched: there is nothing to propose,
+    // and proposing the empty set as "the repository's procedure" would be worse than silence.
+    if (invokes.length === 0) return null;
+    return { file, task: task?.[1] ?? '(untitled)', invokes };
+}
+
+/**
+ * The `configured` playbooks whose scope covers this project, for the given verb.
+ *
+ * `verb` is matched against the playbook's `task` as a plain lower-cased substring. That is
+ * deliberately loose: a playbook titled "Add a new component to this repository" must match
+ * the `scaffold` lane's component work, and a stricter match would make the whole mechanism
+ * unreachable for the phrasing `playbook-authoring` actually generates.
+ */
+export function _scaffold_playbooks(
+    state: DeliveryState,
+    verb_terms: ReadonlyArray<string>,
+    root: string | null = null,
+): ScaffoldPlaybook[] {
+    const base = root !== null ? root : process.cwd();
+    const home = path.join(base, PLAYBOOK_HOME);
+    let names: string[] = [];
+    try {
+        names = fs.readdirSync(home).filter((n) => n.endsWith('.md')).sort();
+    } catch {
+        return [];
+    }
+    const stack = _pyTruthy(state.stack) ? state.stack : {};
+    const scope_root_raw = _isDict(stack) ? stack['scope_root'] : undefined;
+    const scope_root = typeof scope_root_raw === 'string' ? scope_root_raw : '';
+
+    const out: ScaffoldPlaybook[] = [];
+    for (const name of names) {
+        const pb = _read_playbook(path.join(home, name), scope_root);
+        if (pb === null) continue;
+        const task_lower = pb.task.toLowerCase();
+        if (!verb_terms.some((t) => task_lower.includes(t))) continue;
+        out.push(pb);
+    }
+    return out;
+}
+
+/**
+ * The lines that put the repository's own procedure ahead of the stack skill.
+ *
+ * Empty array when no playbook matches — that is what keeps a project with no playbook home
+ * byte-identical to before this existed. The commands are PROPOSED, never run: the
+ * engine-never-writes contract is unchanged, and a playbook is authoritative about *what*,
+ * never about who runs it.
+ */
+export function _playbook_lines(playbooks: ReadonlyArray<ScaffoldPlaybook>): string[] {
+    if (playbooks.length === 0) return [];
+    const lines: string[] = [
+        '> **This repository has its own procedure for this, and it goes FIRST.** A shipped ' +
+            'skill is a generic answer; the playbook below carries decisions this repository ' +
+            'already made. Use the stack skill only for what the playbook does not cover.',
+    ];
+    for (const pb of playbooks) {
+        lines.push(
+            `> \`${pb.file}\` — ${pb.task}: propose \`${pb.invokes.join('`, `')}\` ` +
+                'before any stack-skill step. Propose, never run — the human runs it.',
+        );
+    }
+    return lines;
+}
+
 /**
  * Stack-agnostic directive that derives the scaffold plan.
  *
@@ -67,6 +207,23 @@ export const BRAND_TOKEN_PATHS: ReadonlyArray<string> = [
  */
 export const PLAN_DIRECTIVE = 'ui-scaffold-plan';
 
+/**
+ * Task words that make a playbook relevant to the `scaffold` verb.
+ *
+ * Kept small and concrete rather than clever: these are the nouns
+ * `playbook-authoring` derives from a repository's own creation scripts
+ * (`new:component`, `new:package`, `generate:page`), so the terms and the generator are
+ * two halves of one contract.
+ */
+export const SCAFFOLD_VERB_TERMS: ReadonlyArray<string> = [
+    'component',
+    'page',
+    'package',
+    'workspace',
+    'route',
+    'screen',
+];
+
 /**
  * Map `state.stack.frontend` → build-stage agent-directive skill name.
  *
@@ -324,10 +481,12 @@ function _delegate_build(state: DeliveryState, scaffold: Record<string, Any>): S
     const page_count = Array.isArray(pages) ? pages.length : 0;
     const routes = scaffold['routes'];
     const route_count = Array.isArray(routes) ? routes.length : 0;
+    const playbook_lines = _playbook_lines(_scaffold_playbooks(state, SCAFFOLD_VERB_TERMS));
     return new StepResult({
         outcome: Outcome.BLOCKED,
         questions: [
             agent_directive(directive),
+            ...playbook_lines,
             `> Stack: \`${stack_label}\`. Scaffold plan is ready ` +
                 `(${page_count} page(s), ${route_count} route(s)). Create the ` +
                 'skeleton from `state.ui_scaffold` — routes, layout shell, and ' +

package/src/agent-src/templates/scripts/work_engine/directives/ui/stack_bundles.ts

@@ -212,17 +212,86 @@ export function unsupported_stack_questions(
     for (const c of conflicts) {
         lines.push(`> - \`${c}\``);
     }
+    // A scope conflict has a *closed* option set — the detector already named
+    // every candidate — so enumerate them instead of asking the open question.
+    // "Which workspace?" answered from a list is a pick; answered as free text
+    // it is a guess the agent has to validate, which is the same silent-pick
+    // failure one layer up.
+    const roots = workspace_roots_from_conflicts(conflicts);
+    let n = 1;
+    for (const root of roots) {
+        lines.push(
+            `> ${n}. Build for \`${root}\` — write it to \`state.stack.scope_root\` ` +
+                'and re-run detection against that workspace.',
+        );
+        n += 1;
+    }
+    if (roots.length === 0) {
+        lines.push(
+            `> ${n}. Name the project to build for — the workspace path, or which ` +
+                'framework owns this surface. Detection re-runs against that scope.',
+        );
+        n += 1;
+    }
     lines.push(
-        '> 1. Name the project to build for — the workspace path, or which ' +
-            'framework owns this surface. Detection re-runs against that scope.',
-        '> 2. Continue on the stack-neutral floor anyway — `ui-apply-generic` ' +
+        `> ${n}. Continue on the stack-neutral floor anyway — \`ui-apply-generic\` ` +
             'plus its companions. Output will not be idiomatic for either ' +
             'framework; say so in the result.',
-        '> 3. Abort — drop this UI request.',
+        `> ${n + 1}. Abort — drop this UI request.`,
     );
     return lines;
 }
 
+/** Prefix of the ambiguity string the detector emits for a scope conflict. */
+const _WORKSPACE_CONFLICT_PREFIX = 'workspace roots: ';
+
+/**
+ * The workspace names carried by a `workspace roots: a + b` conflict.
+ *
+ * Parsed back out of the ambiguity string rather than passed alongside it,
+ * because `StackResult.ambiguity` is the serialized contract the halt already
+ * echoes — adding a parallel field would give the same fact two representations
+ * that can disagree after a round-trip through `state.stack`.
+ */
+export function workspace_roots_from_conflicts(
+    conflicts: ReadonlyArray<string>,
+): string[] {
+    for (const c of conflicts) {
+        if (c.startsWith(_WORKSPACE_CONFLICT_PREFIX)) {
+            return c
+                .slice(_WORKSPACE_CONFLICT_PREFIX.length)
+                .split('+')
+                .map((name) => name.trim())
+                .filter((name) => name !== '');
+        }
+    }
+    return [];
+}
+
+/**
+ * Name the workspace a dispatch is scoped to, when it is not the project root.
+ *
+ * Returns an empty array for every non-monorepo project, so those halts stay
+ * byte-identical. The line exists because the skills downstream read
+ * `components.json`, `components/ui/*` and the styling config by path, and in a
+ * monorepo none of those live at the repository root — which is the M5 prose
+ * defect, restated where the agent actually acts on it.
+ */
+export function scope_lines(stack_state: unknown): string[] {
+    if (typeof stack_state !== 'object' || stack_state === null) {
+        return [];
+    }
+    const raw = (stack_state as Record<string, unknown>)['scope_root'];
+    if (typeof raw !== 'string' || raw === '') {
+        return [];
+    }
+    return [
+        `> Scope: \`${raw}\` — the workspace this stack was detected in. Read ` +
+            'and write component files, `components.json`, and the styling ' +
+            'config under that path. The repository root carries none of them.',
+    ];
+}
+
 /**
  * Render the "load these skills" line for a dispatch halt.
  *