mandrel 1.72.0 → 1.74.0

package/.agents/README.md

@@ -33,7 +33,7 @@ It then shows a **two-option prompt**:
 
 1. **Configure now** — runs `node .agents/scripts/bootstrap.js`, forwarding any
    passthrough flags unchanged, to wire the project and GitHub side (creates the
-   GitHub repo + Projects board).
+   GitHub repo; board decoration and Issue Forms are opt-in — see below).
 2. **Just the files** — stops after materialization and prints a re-run hint
    (`mandrel init`) so you can configure later.
 
@@ -100,9 +100,13 @@ The bootstrap pipeline, in order:
    `.claude/commands/` tree so every `/<command>` loads), wires the system
    prompt (see below), gitignores derived artefacts, and runs the
    quality-gates installer.
-4. **GitHub-side mutations.** Creates the label taxonomy, Project V2
-   fields, branch protection, and merge-method settings. Skipped with
-   `--skip-github`.
+4. **GitHub-side mutations.** Creates the label taxonomy, branch protection,
+   and merge-method settings. Skipped with `--skip-github`. Two additional
+   mutations are **opt-in** (prompted y/N, defaulting No, or passed as flags):
+   - `--with-project-board` — provision the Projects V2 Status field and
+     custom fields on an existing board.
+   - `--with-issue-forms` — generate `.github/ISSUE_TEMPLATE/story.yml` and
+     `epic.yml` from the ticket-body schema.
 
 The bootstrap is idempotent — safe to re-run; an already-configured
 clone produces zero file mutations.
@@ -184,7 +188,7 @@ Reverses a recorded install using the install ledger
 (`.agents/.install-manifest.json`). Each ledger entry is a
 mutation-manifest record; uninstall walks reversible entries and undoes
 exactly what the install applied, without touching pre-existing operator
-content. GitHub-side state (labels, branch protection, Projects board)
+content. GitHub-side state (labels, branch protection, project board fields)
 requires manual reversal and is surfaced as a follow-up checklist.
 
 ```bash

package/.agents/docs/configuration.md

@@ -358,6 +358,19 @@ Read with `getCommands(config)` — see
 | ------------------ | -------- | ------- | -------------------------------------------------------------------------------------------------- |
 | `docsContextFiles` | No       | `[]`    | Files the context-hydration engine includes when assembling agent prompts. Resolved against `paths.docsRoot`. |
 
+> **Entries are plain filenames, not globs.** Each entry is resolved as a
+> single file under `paths.docsRoot`; the loader does **not** expand glob
+> patterns. This matters for the decisions log: when a project adopts the
+> index + `decisions/` ADR-directory layout (see
+> [`documentation-and-adrs`](../skills/core/documentation-and-adrs/SKILL.md)),
+> the **index** `decisions.md` stays the mandatory-read and the per-ADR bodies
+> under `decisions/` are link-followed on demand — **index-only by default**.
+> Auto-loading every ADR body into each task's context would reintroduce the
+> bloat the directory split exists to remove. A project that genuinely wants
+> the full ADR set in mandatory context must opt in by listing the individual
+> ADR files explicitly (one filename per entry); there is no built-in
+> `decisions/*.md` glob.
+
 ---
 
 ## `github`

package/.agents/instructions.md

@@ -86,11 +86,13 @@ apply by checking the `.agents/rules/` directory (e.g.,
 ### G. Structured Configuration
 
 Refer to `.agentrc.json` to understand your operational limits (e.g., allowed
-auto-run permissions, default personas). Refer to the **Tech Stack** section
-of `docs/architecture.md` for the project's specific technology choices
-(database, ORM, API framework, auth provider, validation library, workspace
-paths). Project-specific technology context is intentionally kept out of
-`.agentrc.json`.
+auto-run permissions, default personas). For the project's specific
+technology choices (database, ORM, API framework, auth provider, validation
+library, workspace paths), refer to the project's Tech Stack inventory: a
+dedicated `docs/tech-stack.md` when present (the single-ownership convention),
+otherwise the **Tech Stack** section of `docs/architecture.md` (a numbered or
+decorated heading such as `## 1. Tech Stack` is fine). Project-specific
+technology context is intentionally kept out of `.agentrc.json`.
 
 ### H. Observability & Friction Telemetry
 
@@ -240,7 +242,13 @@ stops.
      data dictionary, decisions log, patterns, etc.) and replaces any
      hardcoded filename list. Resolve each entry against
      `project.paths.docsRoot` (default `docs/`) and skip silently
-     when an entry's file is absent.
+     when an entry's file is absent. The decisions log (`decisions.md`) may
+     be either a single-file dated-entry log or an **index** into a
+     `decisions/` ADR directory — both are first-class layouts (see
+     [`skills/core/documentation-and-adrs`](skills/core/documentation-and-adrs/SKILL.md)).
+     When it is an index, only the index is the mandatory-read; the
+     per-ADR bodies under `decisions/` are link-followed on demand
+     (index-only by default), not auto-loaded into every task's context.
    - **Conditional Reads**: When the task touches UI copy, layout, or
      routing and the corresponding file is present in the project, also
      read `docs/style-guide.md` and `docs/web-routes.md`. Skip both when

package/.agents/personas/devops-engineer.md

@@ -14,8 +14,10 @@ express it through code or documented configuration files.
 
 1. **Read Context:** Before making any infrastructure changes, analyze the
    existing CI/CD, deployment, and security configurations.
-2. **Follow Protocols:** Adhere strictly to the **Tech Stack** section of
-   `docs/architecture.md` and the `orchestration` block of `.agentrc.json`.
+2. **Follow Protocols:** Adhere strictly to the project's Tech Stack
+   inventory — a dedicated `docs/tech-stack.md` when present, otherwise the
+   **Tech Stack** section of `docs/architecture.md` — and the `orchestration`
+   block of `.agentrc.json`.
 3. **Validate Always:** For every task, determine how the change will be
    monitored and validated (logs, health checks, or test gates).
 

package/.agents/scripts/agents-bootstrap-github.js

@@ -43,7 +43,6 @@ import { Logger } from './lib/Logger.js';
 import {
   LABEL_TAXONOMY,
   PROJECT_FIELD_DEFS,
-  PROJECT_VIEW_DEFS,
   STATUS_FIELD_OPTIONS,
 } from './lib/label-taxonomy.js';
 import { createProvider } from './lib/provider-factory.js';
@@ -154,25 +153,6 @@ async function ensureStatusField(provider, log) {
   }
 }
 
-async function ensureViews(provider, log) {
-  try {
-    const views = await provider.ensureProjectViews(PROJECT_VIEW_DEFS);
-    if (views.unavailable) {
-      log(
-        `[Bootstrap] Projects V2 Views unavailable — skipped ${views.skipped.join(', ')}.${views.error ? ` (${views.error})` : ''} ${PROJECTS_DOC_POINTER}`,
-      );
-    } else {
-      log(
-        `[Bootstrap] Views — created: ${views.created.length}, skipped: ${views.skipped.length}`,
-      );
-    }
-    return views;
-  } catch (err) {
-    log(`[Bootstrap] Views provisioning failed: ${err.message}`);
-    return { created: [], skipped: [], unavailable: false };
-  }
-}
-
 /**
  * Audit the project's built-in workflows and, when explicitly opted-in
  * via `--reap-conflicting-workflows`, delete the ones that race against
@@ -283,10 +263,15 @@ async function ensureProjectFields(provider, project, log) {
  *   github?: object,
  *   baseBranch?: string,
  *   githubAdminApproved?: boolean,
+ *   withProjectBoard?: boolean,
  *   isTTY?: boolean,
  * }} [opts] - `githubAdminApproved` MUST be `true` for any GitHub mutation to
  *   occur; any other value (absent / `false`) is treated as "not approved"
  *   and the run is a verified no-op.
+ *   `withProjectBoard` (default `false`) — opt-in for Projects V2 board,
+ *   Status field, custom fields, and workflow audit. When absent or `false`,
+ *   the board decoration is skipped and only labels + branch protection +
+ *   merge methods are provisioned.
  */
 export async function runBootstrap(config, opts = {}) {
   // Explicit opt-in gate (Story #3526). Default-deny: absent or non-`true`
@@ -316,36 +301,46 @@ export async function runBootstrap(config, opts = {}) {
   log('[Bootstrap] API access verified.');
 
   const labels = await ensureLabels(provider, log);
-  const project = await resolveProject(provider, providerConfig, log);
 
-  const projectReady = !project.skipped && project.projectNumber;
+  // Board decoration (Projects V2 board, Status field, custom fields, workflow
+  // audit) is opt-in and defaults OFF. Minimal install = labels only. Gate is
+  // `opts.withProjectBoard === true`; absent or false skips all board work.
+  // ColumnSync already soft-noops when projectNumber is unset (column-sync.js:19-23).
+  const projectBoard = opts.withProjectBoard === true;
+  let project = { projectNumber: null, created: false, skipped: true };
   let statusField = { status: 'skipped', added: [] };
-  let views = { created: [], skipped: [], unavailable: false };
   let fields = { created: [], skipped: [] };
+  let workflowAudit = {
+    skipped: true,
+    reason: 'board-decoration-not-opted-in',
+  };
 
-  if (projectReady) {
-    statusField = await ensureStatusField(provider, log);
-    views = await ensureViews(provider, log);
-    fields = await ensureProjectFields(provider, project, log);
-  } else {
-    log('[Bootstrap] No active project — skipping legacy project-field setup.');
-  }
-
-  // Story #2845 — audit project workflows for the ones that race against
-  // the orchestrator's ColumnSync writes (notably `Pull request merged`
-  // and `Pull request linked to issue`, which both rewrite Status as a
-  // side-effect of auto-merge). When `--reap-conflicting-workflows` is
-  // set, also delete the offenders via `deleteProjectV2Workflow` (the
-  // only programmatic action GraphQL exposes today — `enabled` is
-  // read-only).
-  const workflowAudit = projectReady
-    ? await auditAndOptionallyReapWorkflows(
+  if (projectBoard) {
+    project = await resolveProject(provider, providerConfig, log);
+    const projectReady = !project.skipped && project.projectNumber;
+    if (projectReady) {
+      statusField = await ensureStatusField(provider, log);
+      fields = await ensureProjectFields(provider, project, log);
+      // Story #2845 — audit project workflows for the ones that race against
+      // the orchestrator's ColumnSync writes (notably `Pull request merged`
+      // and `Pull request linked to issue`, which both rewrite Status as a
+      // side-effect of auto-merge). When `--reap-conflicting-workflows` is
+      // set, also delete the offenders via `deleteProjectV2Workflow` (the
+      // only programmatic action GraphQL exposes today — `enabled` is
+      // read-only).
+      workflowAudit = await auditAndOptionallyReapWorkflows(
         provider,
         project.projectNumber,
         opts.reapConflictingWorkflows === true,
         log,
-      )
-    : { skipped: true, reason: 'no-project' };
+      );
+    } else {
+      log('[Bootstrap] No active project — skipping project-field setup.');
+      workflowAudit = { skipped: true, reason: 'no-project' };
+    }
+  } else {
+    log('[Bootstrap] Project board decoration skipped (opt-in not set).');
+  }
 
   // Consumer-facing bootstrap promotes the framework's CI-gates-only
   // stance: branch protection with enforce_admins + 0-approval-count and
@@ -405,7 +400,6 @@ export async function runBootstrap(config, opts = {}) {
     fields,
     project,
     statusField,
-    views,
     workflowAudit,
     branchProtection,
     mergeMethods,
@@ -490,6 +484,10 @@ async function main() {
   // invocation never silently reconfigures branch protection or merge methods.
   const githubAdminApproved =
     assumeYes || process.argv.includes('--approve-github-admin');
+  // Story #4234 — Board decoration is opt-in (default off). Pass
+  // `--with-project-board` to also provision the Projects V2 board, Status
+  // field, and custom fields.
+  const withProjectBoard = process.argv.includes('--with-project-board');
 
   try {
     const result = await runBootstrap(config, {
@@ -499,6 +497,7 @@ async function main() {
       assumeNo,
       reapConflictingWorkflows,
       githubAdminApproved,
+      withProjectBoard,
     });
     // A non-approved run returns the skip envelope (no full result shape);
     // the skip line is already logged inside runBootstrap, so render the

package/.agents/scripts/bootstrap.js

@@ -37,8 +37,16 @@
  *                             (labels, Projects V2, branch protection, merge
  *                             methods) without accepting every other default.
  *   --skip-github             Skip the GitHub-side bootstrap entirely
- *   --skip-quality            Skip the quality-gates bootstrap
+ *   --with-quality            Opt-in: install local quality gates (pre-commit
+ *                             hook + quality:preview/watch scripts). Off by
+ *                             default — prompted y/N.
  *   --dry-run                 Collect info and print the plan; change nothing
+ *   --with-project-board      Opt-in: provision the Projects V2 Status field
+ *                             and custom fields. Off by default — the project
+ *                             board object is still created when a project
+ *                             name is supplied, but decoration is skipped.
+ *   --with-issue-forms        Opt-in: generate .github/ISSUE_TEMPLATE/story.yml
+ *                             and epic.yml. Off by default.
  *   --reap-conflicting-workflows  Delete Projects V2 built-in workflows that
  *                             race against the orchestrator (destructive)
  *   --help                    Print this help
@@ -97,8 +105,14 @@ Flags:
                             (labels, Projects V2, branch protection, merge
                             methods) without accepting every other default.
   --skip-github             Skip the GitHub-side bootstrap entirely
-  --skip-quality            Skip the quality-gates bootstrap
+  --with-quality            Opt-in: install local quality gates (pre-commit
+                            hook + quality:preview/watch scripts).
+                            (default: off — prompted y/N).
   --dry-run                 Collect info and print the plan; change nothing
+  --with-project-board      Opt-in: provision the Projects V2 Status field
+                            and custom fields (default: off — prompted y/N).
+  --with-issue-forms        Opt-in: generate .github/ISSUE_TEMPLATE/story.yml
+                            and epic.yml (default: off — prompted y/N).
   --reap-conflicting-workflows  Delete Projects V2 built-in workflows that
                             race against the orchestrator (destructive)
   --help                    Print this help
@@ -157,16 +171,24 @@ export function resolveOwnerForPicker(defaults, flags, env = process.env) {
   return null;
 }
 
-/** Ask a yes/no question. Non-interactive runs auto-accept (return true). */
-async function confirmYesNo(message, interactive) {
-  if (!interactive) return true;
+/**
+ * Ask a yes/no question. `defaultAnswer` controls the default when the
+ * operator presses Enter without typing (true = Y/n, false = y/N). In
+ * non-interactive mode the default is returned immediately.
+ */
+async function confirmYesNo(message, interactive, defaultAnswer = true) {
+  if (!interactive) return defaultAnswer;
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout,
   });
   try {
-    const raw = (await rl.question(`${message} [Y/n]: `)).trim().toLowerCase();
-    return raw === '' || raw === 'y' || raw === 'yes';
+    const hint = defaultAnswer ? '[Y/n]' : '[y/N]';
+    const raw = (await rl.question(`${message} ${hint}: `))
+      .trim()
+      .toLowerCase();
+    if (raw === '') return defaultAnswer;
+    return raw === 'y' || raw === 'yes';
   } finally {
     rl.close();
   }
@@ -688,6 +710,9 @@ async function runGithubBootstrap(answers, opts) {
     // interactive operator confirmation, `--assume-yes`, or
     // `--approve-github-admin`. Default-deny at the boundary gate when absent.
     githubAdminApproved: opts.githubAdminApproved === true,
+    // Opt-in: provision Status field + custom fields on the project board.
+    // Default off — prompted y/N during collect/confirm or via --with-project-board.
+    withProjectBoard: opts.withProjectBoard === true,
     // Opt-in: delete the Projects V2 built-in workflows that race against the
     // orchestrator's ColumnSync (e.g. "Pull request merged"). Off by default.
     reapConflictingWorkflows: Boolean(opts.reapConflictingWorkflows),
@@ -1011,7 +1036,48 @@ export async function collectAndConfirm(state) {
         return { ok: false, exit: 1 };
       }
     }
-    return { ok: true, payload: { answers, creation } };
+
+    // Opt-in: board decoration (Status field, custom fields). Default off.
+    // Dry-run halts immediately after this step — resolve without prompting.
+    let withProjectBoard = Boolean(state.flags['with-project-board']);
+    if (!state.flags['dry-run'] && !withProjectBoard) {
+      withProjectBoard = await confirmYesNo(
+        'Set up project board fields (Status, custom)?',
+        state.interactive,
+        false,
+      );
+    }
+
+    // Opt-in: GitHub Issue Form templates. Default off.
+    let withIssueForms = Boolean(state.flags['with-issue-forms']);
+    if (!state.flags['dry-run'] && !withIssueForms) {
+      withIssueForms = await confirmYesNo(
+        'Generate GitHub Issue Form templates?',
+        state.interactive,
+        false,
+      );
+    }
+
+    // Opt-in: local quality gates. Default off.
+    let withQuality = Boolean(state.flags['with-quality']);
+    if (!state.flags['dry-run'] && !withQuality) {
+      withQuality = await confirmYesNo(
+        'Install local quality gates (pre-commit hook + quality:preview/watch scripts)?',
+        state.interactive,
+        false,
+      );
+    }
+
+    return {
+      ok: true,
+      payload: {
+        answers,
+        creation,
+        withProjectBoard,
+        withIssueForms,
+        withQuality,
+      },
+    };
   }
 }
 
@@ -1157,7 +1223,8 @@ export async function executeBootstrap(state) {
     agentRoot: state.agentRoot,
     answers: state.answers,
     approvedGroups,
-    skipQuality: Boolean(state.flags['skip-quality']),
+    withQuality: state.withQuality === true,
+    withIssueForms: state.withIssueForms === true,
   });
   return { ok: true, payload: { report, approvedGroups } };
 }
@@ -1210,6 +1277,7 @@ export async function executeGithubBootstrap(state) {
     state.report.github = await runGithubBootstrap(state.answers, {
       assumeYes: state.assumeYes,
       githubAdminApproved: state.githubAdminApproved === true,
+      withProjectBoard: state.withProjectBoard === true,
       reapConflictingWorkflows: Boolean(
         state.flags['reap-conflicting-workflows'],
       ),
@@ -1232,7 +1300,7 @@ export function recordLedger(state) {
   const manifestCtx = {
     answers: state.answers,
     skipGithub: Boolean(state.flags['skip-github']),
-    skipQuality: Boolean(state.flags['skip-quality']),
+    withQuality: state.withQuality === true,
   };
   const entries = buildMutationManifest(manifestCtx).filter((e) =>
     appliedGroups.has(e.phaseGroup),
@@ -1384,7 +1452,7 @@ export async function main(argv = process.argv.slice(2), deps = {}) {
       `\n[Bootstrap] GitHub bootstrap failed: ${githubError}. ` +
         'Project-side setup (labels are GitHub-side; the local .agentrc.json / ' +
         'quality-gate / workflow files that were applied are recorded in the ' +
-        'install ledger) completed, but the GitHub label/board/views/protection ' +
+        'install ledger) completed, but the GitHub label/board/protection ' +
         'setup did not. Resolve the cause above (commonly `gh auth login` or a ' +
         'missing repo/project scope) and re-run `mandrel bootstrap` — the run is ' +
         'idempotent and will skip what already succeeded.',