archgen-skill 0.1.0 → 0.1.2

package/lib/node_modules/archgen-mcp/src/core/brief-scope.mjs

@@ -0,0 +1,218 @@
+// brief-scope.mjs — derive the artifact space a dispatch brief is written
+// against, and derive EVERY path the brief carries from ONE source.
+//
+// WHY THIS EXISTS — two defects, one cause (paths were assembled by hand
+// instead of resolved):
+//
+//   1. The brief action demanded `slug` even when the caller had already
+//      passed the absolute `tasks.yaml`. That path IS `.archgen/<slug>/
+//      tasks.yaml` — the slug is derivable — so the tool asked for the same
+//      fact twice in two different shapes, and a caller that omitted `slug`
+//      got "needs tasks.yaml, plans dir, slug dir — pass slug" for a brief
+//      it had already given everything for.
+//
+//   2. The emitted brief mixed path vocabularies: `tasks.yaml` was ABSOLUTE
+//      while `slug dir` and `plans dir` were PROJECT-RELATIVE. A brief is
+//      handed to a sub-agent whose working directory may be a worktree or
+//      another repo root; `ctx.contain()` resolves a relative path against
+//      the SERVER's project root, so the relative paths in the brief
+//      silently pointed at a different tree. A brief whose paths only work
+//      from one cwd is a broken brief.
+//
+// Every path in a brief is now absolute, and every one of them comes from the
+// single scope resolved here.
+import { realpathSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { resolveSlugInput, ScopeError } from './scope.mjs';
+import { invalidInput } from './errors.mjs';
+
+// The slug is a directory name, never a path: a slug of "../../etc" must not
+// be able to steer the brief's paths out of the artifact space.
+const SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
+/**
+ * The REAL path of a path that may not exist yet.
+ *
+ * The scope gate proves paths by realpath, so the brief's paths are real
+ * paths. When the leaf does not exist yet — a brief written before the plan
+ * lands — the deepest EXISTING ancestor is realpath'd and the remaining
+ * segments are re-appended. The result is the path the file WILL have, not
+ * a different spelling of the same place.
+ *
+ * Without this, the same plan produced two different prefixes depending on
+ * whether tasks.yaml happened to exist: `/var/...` from the lexical
+ * fallback and `/private/var/...` from the realpath branch.
+ *
+ * @param {string} abs
+ * @returns {string}
+ */
+function realpathNearest(abs) {
+  const tail = [];
+  let cur = resolve(abs);
+  for (;;) {
+    try {
+      const real = realpathSync(cur);
+      return tail.length ? join(real, ...tail.slice().reverse()) : real;
+    } catch {
+      const parent = dirname(cur);
+      if (parent === cur) return resolve(abs);
+      tail.push(basename(cur));
+      cur = parent;
+    }
+  }
+}
+
+/**
+ * Derive the slug directory from a `tasks.yaml` path WITHOUT touching the
+ * filesystem — used when the file does not exist yet (a brief can be written
+ * before the plan lands) or when it cannot be realpath-resolved.
+ *
+ * The shape is EXACTLY the shape `resolveSlugInput` returns — `{root, slug}` —
+ * so the two branches cannot disagree about the field names. They did once,
+ * and the fallback silently produced `slugDir: undefined`.
+ *
+ * @param {string} p
+ * @returns {{root: string, slug: string}|null}
+ */
+function deriveFromTasksPath(p) {
+  if (basename(p) !== 'tasks.yaml') return null;
+  const slugDir = dirname(p);
+  const slug = basename(slugDir);
+  if (!SLUG_RE.test(slug)) return null;
+  if (basename(dirname(slugDir)) !== '.archgen') return null;
+  return { root: realpathNearest(slugDir), slug };
+}
+
+/**
+ * Derive the slug directory from a `plans` directory path.
+ *
+ * @param {string} p
+ * @returns {{root: string, slug: string}|null}
+ */
+function deriveFromPlansPath(p) {
+  if (basename(p) !== 'plans') return null;
+  const slugDir = dirname(p);
+  const slug = basename(slugDir);
+  if (!SLUG_RE.test(slug)) return null;
+  if (basename(dirname(slugDir)) !== '.archgen') return null;
+  return { root: realpathNearest(slugDir), slug };
+}
+
+/**
+ * Resolve the artifact space a brief is written against.
+ *
+ * The caller may name the space in any of three ways; they are equivalent and
+ * are reconciled here:
+ *
+ *   - `tasksYaml` — the absolute path to `<slugDir>/tasks.yaml` (strongest:
+ *     it names a real file, so the scope is proven, not assumed);
+ *   - `planDir`   — the absolute path to `<slugDir>/plans`;
+ *   - `slug`      — the slug name alone.
+ *
+ * @param {{
+ *   tasksYaml?: string|null,
+ *   planDir?: string|null,
+ *   slug?: string|null,
+ *   projectRoot: string,
+ * }} opts
+ * @returns {{slug: string, slugDir: string, plansDir: string, tasksYaml: string, source: 'tasksYaml'|'planDir'|'slug'}}
+ */
+export function resolveBriefScope(opts) {
+  const { tasksYaml = null, planDir = null, slug = null, projectRoot } = opts;
+  if (!projectRoot) throw invalidInput('brief scope needs a project root', {});
+
+  let slugDir = null;
+  let resolvedSlug = null;
+  let tasksFile = null;
+  let source = null;
+
+  if (tasksYaml) {
+    let scoped = null;
+    try {
+      scoped = resolveSlugInput(tasksYaml, projectRoot);
+    } catch (e) {
+      if (e instanceof ScopeError) {
+        throw invalidInput(`tasks.yaml must live in .archgen/<slug>/ — ${tasksYaml} does not`, { file: tasksYaml });
+      }
+      // The file may not exist yet. The path SHAPE still proves the scope.
+      scoped = deriveFromTasksPath(tasksYaml);
+      if (!scoped) {
+        throw invalidInput(`cannot read ${tasksYaml} (missing or unreadable)`, { file: tasksYaml });
+      }
+    }
+    slugDir = scoped.root;
+    resolvedSlug = scoped.slug;
+    // The tasks file is taken from the RESOLVED slug dir, not from the raw
+    // path the caller typed. `resolveSlugInput` realpath-resolves, so this is
+    // the same file — but it shares one prefix with the slug dir and the
+    // plans dir. A brief whose three paths carry two different prefixes
+    // (`/var/...` vs `/private/var/...` — the macOS symlink) reads as three
+    // different locations to anything comparing them.
+    tasksFile = join(slugDir, 'tasks.yaml');
+    source = 'tasksYaml';
+  } else if (planDir) {
+    const scoped = deriveFromPlansPath(planDir);
+    if (!scoped) {
+      throw invalidInput(`plans dir must live in .archgen/<slug>/plans — ${planDir} does not`, { file: planDir });
+    }
+    slugDir = scoped.root;
+    resolvedSlug = scoped.slug;
+    tasksFile = join(slugDir, 'tasks.yaml');
+    source = 'planDir';
+  } else if (slug) {
+    if (!SLUG_RE.test(slug)) {
+      throw invalidInput(`slug '${slug}' is not a valid slug (lowercase, dash-separated)`, { slug });
+    }
+    slugDir = realpathNearest(join(projectRoot, '.archgen', slug));
+    resolvedSlug = slug;
+    tasksFile = join(slugDir, 'tasks.yaml');
+    source = 'slug';
+  } else {
+    throw invalidInput('brief needs tasks.yaml, a plans dir, or a slug — pass one of them', {
+      action: 'brief',
+      missing: ['tasks.yaml', 'slug'],
+    });
+  }
+
+  // The two spellings must agree. A caller that passes a tasks.yaml from one
+  // slug and the name of another has made a mistake the brief would
+  // otherwise paper over.
+  if (slug && resolvedSlug && slug !== resolvedSlug) {
+    throw invalidInput(`slug '${slug}' does not match the artifact space '${resolvedSlug}'`, {
+      slug,
+      actual: resolvedSlug,
+    });
+  }
+
+  return {
+    slug: resolvedSlug,
+    slugDir,
+    plansDir: join(slugDir, 'plans'),
+    tasksYaml: tasksFile,
+    source,
+  };
+}
+
+/**
+ * The template variables a brief is rendered with.
+ *
+ * Every path is ABSOLUTE. The relative forms are gone: they resolved against
+ * whatever cwd the reading agent happened to have.
+ *
+ * @param {{slug: string, slugDir: string, plansDir: string, tasksYaml: string}} scope
+ * @param {{featureRequest?: string|null, topic?: string|null, round?: number|string|null}} extra
+ * @returns {Record<string, string>}
+ */
+export function briefVars(scope, extra = {}) {
+  const vars = {
+    slug: scope.slug,
+    'slug dir': scope.slugDir,
+    'plans dir': scope.plansDir,
+    'tasks.yaml': scope.tasksYaml,
+  };
+  if (extra.featureRequest) vars['feature request'] = extra.featureRequest;
+  else vars['feature request'] = scope.slug;
+  if (extra.topic) vars.topic = extra.topic;
+  if (extra.round !== undefined && extra.round !== null && extra.round !== '') vars.round = String(extra.round);
+  return vars;
+}

package/lib/node_modules/archgen-mcp/src/core/briefs.mjs

@@ -0,0 +1,168 @@
+// briefs.mjs — the dispatch brief templates, served as tool output.
+//
+// The verifier / review / survey / investigate briefs lived as prose blocks in
+// references/orchestration.md and were copy-pasted into every sub-agent
+// dispatch. A brief IS a template — a machine-shaped output — so the tool owns
+// it and the reference keeps only the policy around it.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { invalidInput, notFound } from './errors.mjs';
+
+export const BRIEF_KINDS = ['verifier', 'review', 'survey', 'investigate'];
+
+/**
+ * Load one dispatch brief.
+ *
+ * @param {string} briefsDir the directory holding the brief templates
+ * @param {string} kind one of BRIEF_KINDS
+ * @param {Record<string, string>} vars placeholder values substituted into the template
+ */
+export function loadBrief(briefsDir, kind, vars = {}) {
+  const key = String(kind ?? '').toLowerCase();
+  if (!BRIEF_KINDS.includes(key)) {
+    throw invalidInput(`unknown brief '${kind}' (allowed: ${BRIEF_KINDS.join('|')})`, { kind });
+  }
+  const path = join(briefsDir, `${key}.md`);
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch {
+    throw notFound(`brief template '${key}.md' is missing`, { kind, path });
+  }
+  for (const [name, value] of Object.entries(vars)) {
+    if (value === undefined || value === null || value === '') continue;
+    text = text.split(`<${name}>`).join(String(value));
+  }
+  return { kind: key, brief: text };
+}
+
+/**
+ * The placeholder names a brief still contains.
+ *
+ * A dispatched brief must not carry a placeholder: a worker told to read
+ * `<slug dir>` looks for a directory with that literal name.
+ *
+ * The matcher is CASE-INSENSITIVE on the first letter. It used to require a
+ * lowercase first character, so `<Domain>` — the literal placeholder that
+ * shipped in every worker prompt — was invisible to it.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function remainingPlaceholders(text) {
+  return [...new Set([...String(text ?? '').matchAll(/<([A-Za-z][A-Za-z. ]*)>/g)].map((m) => m[1]))];
+}
+
+/**
+ * Every brief, for a caller that wants them all.
+ * @param {string} briefsDir
+ */
+export function loadAllBriefs(briefsDir) {
+  const out = {};
+  for (const kind of BRIEF_KINDS) out[kind] = loadBrief(briefsDir, kind).brief;
+  return out;
+}
+
+/**
+ * The context block every dispatch brief carries — the EVIDENCE map, the
+ * pre-rendered tool results, and the rules that keep the sub-agent from
+ * re-deriving what the brief already says.
+ *
+ * WHY THIS IS RENDERED BY THE TOOL AND NOT WRITTEN INTO EACH TEMPLATE:
+ *
+ *   1. EVIDENCE. The verifier used to be told to "read plans + tasks.yaml" —
+ *      whole files, every round. The brief now carries the FILE LIST and the
+ *      SECTION ANCHORS, so the agent reads the sections that matter instead
+ *      of re-reading the plan. A map, not a copy: the agent decides what to
+ *      open, and the map is what lets it decide.
+ *
+ *   2. PRE-RENDERED RESULTS. The review brief used to say "attach the
+ *      mermaid graph and the docs-validate result" — which cost the
+ *      orchestrator two extra tool calls per round, one of which (the graph)
+ *      failed on every plan. The tool renders them once, into the brief.
+ *
+ *   3. THE FORBIDDEN LIST. Without it, a sub-agent reads the archgen skill
+ *      and its references (the orchestrator's protocol, not its) and runs the
+ *      archgen tool suite to re-derive what it was just handed. That is a
+ *      second and third reading of the same facts — pure cost, and a chance
+ *      to drift from the protocol the orchestrator is following.
+ *
+ * @param {{
+ *   scope?: {slug?: string, slugDir?: string, plansDir?: string, tasksYaml?: string}|null,
+ *   evidence?: {files: Array<{path: string, sections: Array<{slug: string, title: string}>}>, fileCount: number}|null,
+ *   graph?: string|null,
+ *   docsValidation?: {valid: boolean, broken: unknown[], warnings: unknown[]}|null,
+ *   allowedCalls?: string[],
+ * }} ctx
+ * @returns {string}
+ */
+export function renderBriefContext(ctx = {}) {
+  const out = [];
+
+  out.push('## CONTEXT — read this first');
+  out.push('');
+  out.push(
+    'Everything you need is in this brief. Do NOT read the archgen skill, its references, or any ' +
+      'protocol document — they are the ORCHESTRATOR\'s, and reading them re-derives context you were ' +
+      'already given.',
+  );
+  const allowed = ctx.allowedCalls ?? [];
+  out.push(
+    allowed.length
+      ? `Do NOT run the archgen tool suite beyond these calls: ${allowed.join(', ')}.`
+      : 'Do NOT run the archgen tool suite at all.',
+  );
+  out.push(
+    'Read ONLY the files in EVIDENCE, and only the sections named. Do not read whole documents when a ' +
+      'section is named.',
+  );
+  out.push('');
+
+  if (ctx.scope) {
+    out.push('## EVIDENCE — the plan under review');
+    out.push('');
+    if (ctx.scope.tasksYaml) out.push(`- tasks: ${ctx.scope.tasksYaml}`);
+    if (ctx.scope.plansDir) out.push(`- plans: ${ctx.scope.plansDir}`);
+    if (ctx.scope.slugDir) out.push(`- artifacts: ${ctx.scope.slugDir}`);
+    out.push('');
+  }
+
+  if (ctx.evidence?.files?.length) {
+    out.push('### Section index — pull the section, never the file');
+    out.push('');
+    for (const f of ctx.evidence.files) {
+      out.push(`- ${f.path}`);
+      for (const s of f.sections) out.push(`  - § ${s.slug} — ${s.title}`);
+    }
+    out.push('');
+  }
+
+  if (ctx.graph) {
+    out.push('### Dependency graph (rendered for you — do not re-fetch)');
+    out.push('');
+    out.push('```mermaid');
+    out.push(ctx.graph);
+    out.push('```');
+    out.push('');
+  }
+
+  if (ctx.docsValidation) {
+    const broken = ctx.docsValidation.broken?.length ?? 0;
+    const warned = ctx.docsValidation.warnings?.length ?? 0;
+    out.push('### Reference-integrity result (rendered for you — do not re-fetch)');
+    out.push('');
+    out.push(`- valid: ${ctx.docsValidation.valid === true}`);
+    out.push(`- broken references: ${broken}`);
+    out.push(`- warnings: ${warned}`);
+    if (broken > 0) {
+      out.push('');
+      out.push('Broken references (each BLOCKS approval):');
+      for (const b of ctx.docsValidation.broken) {
+        out.push(`- ${b.file ?? ''}${b.line ? `:${b.line}` : ''} — ${b.kind ?? 'broken'}: ${b.ref ?? ''}`);
+      }
+    }
+    out.push('');
+  }
+
+  return out.join('\n');
+}