portable-agent-layer 0.115.0 → 0.116.0-canary.1

package/assets/plugins/dark-factory/README.md

@@ -25,7 +25,7 @@ The PO checks for these before it takes a request, and every build checks again
 
 ## Use
 
-Run `/dark-factory:po` and say what you want. The PO writes a spec with acceptance criteria, shows it to you, and starts the build once you say go. You hear back when the pull request is ready, or when the factory needs an answer only you can give.
+Run `/dark-factory:po` and say what you want. The PO reads the code first and asks you, in one batch with a recommended answer for each, only what the code and what it knows about you cannot settle. It writes a spec with acceptance criteria and starts the build: your request is the go, the factory goes as far as an open pull request, and merging stays with you. Ask to see the spec first if you want to. You hear back when the pull request is ready, or, rarely, when the factory needs an answer only you can give.
 
 The build is a plain Node program, `scripts/build.mjs`, that the PO starts in the background. It runs the whole pipeline in one process and makes no call to an agent other than `claude`.
 
@@ -46,7 +46,7 @@ Inside Claude Code the plugin folder is `${CLAUDE_PLUGIN_ROOT}`.
 
 | Role | Model | Job |
 | --- | --- | --- |
-| PO | Opus | Writes the spec, answers the other roles, asks you only what changes the product |
+| PO | Opus | Settles every decision before the build, writes the spec, answers the other roles, asks you only what changes the product and nothing settles |
 | Architect | Opus | Designs large changes |
 | Planner | Opus | Writes a plan detailed enough for a small model |
 | Test writer | Sonnet | Writes failing tests for every acceptance criterion |
@@ -136,11 +136,13 @@ The repo's `CLAUDE.md` is read from your checkout when the task starts, so a rol
 - `"repoInstructions": false` in `.dark-factory.json` leaves out the repo's `CLAUDE.md`.
 - `"userInstructions": false` in `$DARK_FACTORY_HOME/config.json` (`~/.dark-factory/config.json`, optional; a missing file means both parts are on) leaves out your `~/.claude/CLAUDE.md`.
 
-Hooks never run in a role, and neither do your settings or MCP servers.
+Your own hooks never run in a role, and neither do MCP servers. The repo's hooks do run, so a repo `Stop` hook that fails its checks keeps the role working until they pass; the gate stays as the check for repos without hooks.
+
+A role loads the repo's `.claude/settings.json` and `.claude/settings.local.json` from its worktree as Claude Code does, permissions included. Your `~/.claude/settings.json` (or `CLAUDE_CONFIG_DIR`) is passed in `--settings` without `hooks`, `permissions`, `enabledPlugins` and `extraKnownMarketplaces`, so commit attribution and your other preferences apply. Each role call records which of your keys it passed and dropped as a `role_settings` event, without their values.
 
 ## Permissions
 
-- Roles run isolated: `--setting-sources ""`, the plugin from `--plugin-dir`, and their own tool policy from `roles.mjs`, so user hooks and settings don't reach them; only the CLAUDE.md instructions above do.
+- Roles run with `--setting-sources project,local`, the plugin from `--plugin-dir`, and their own tool policy from `roles.mjs`. Your user settings come only through the filtered `--settings` file, so your hooks don't reach them. A repo's `permissions.allow` can widen a role's tools; the role's denies still win.
 - The PO session only needs `"Bash(node *dark-factory*/scripts/*)"`, for example in `.claude/settings.json`:
 
 ```json

package/assets/plugins/dark-factory/agents/po.md

@@ -4,12 +4,11 @@ description: Product owner of a dark-factory task. Answers questions from the ot
 model: claude-opus-5-5
 ---
 
-You are the product owner for one dark-factory task. The user talks only to you; every other role talks to you instead of the user.
+You are the product owner for one dark-factory task, answering a question from another role during the build. The chain of command is the user, then the session that owns this task, then you, then the roles. A question you pass up stops the build, so pass up as little as possible.
 
-When a role asks a question:
+1. Answer from the spec when it settles the question. Quote the section or criterion you used.
+2. Otherwise answer from the repository: its code, tests, conventions and `CLAUDE.md`. Name the file you used.
+3. Otherwise, when the choice does not change what the user gets, make the call yourself and give its reason in one sentence. Prefer what the codebase already does, and an existing helper over a new one.
+4. Return `userQuestion` only when the answer changes scope, product behaviour or an acceptance criterion and none of the above settles it, or when the spec contradicts itself or the code. Write it so it can be answered in one line: the options, and the one you recommend with its reason.
 
-1. Answer it from the spec, the acceptance criteria and the repository whenever they settle it. Most questions are settled there.
-2. Make the call yourself when it is a technical choice that does not change what the user gets.
-3. Return it as a question for the user only when it changes scope, product behaviour, or an acceptance criterion, or when the spec contradicts itself. Ask it so it can be answered in one line.
-
-Never widen the scope beyond the spec. Never answer by guessing what the user would want when the answer changes what they get.
+Never widen the scope beyond the spec, and never drop part of it. Never guess what the user would want when the answer changes what they get.

package/assets/plugins/dark-factory/scripts/role.mjs

@@ -13,6 +13,7 @@ import {
   userHome,
 } from "./lib.mjs";
 import { policyFor, schemaFor } from "./roles.mjs";
+import { writeRoleSettings } from "./settings.mjs";
 
 export const DEFAULT_TIMEOUT_MS = 30 * 60 * 1000;
 export const ONE_COMMAND_PER_CALL =
@@ -298,6 +299,7 @@ export function claudeInvocation(
     resumeSessionId,
     pluginDir = PLUGIN_ROOT,
     instructionsFile,
+    settingsFile,
   } = {}
 ) {
   const policy = policyFor(role);
@@ -312,7 +314,8 @@ export function claudeInvocation(
       "--output-format",
       "json",
       "--setting-sources",
-      "",
+      "project,local",
+      ...optionalFlag("--settings", settingsFile),
       "--plugin-dir",
       pluginDir,
       ...optionalFlag("--append-system-prompt-file", instructionsFile),
@@ -353,6 +356,7 @@ function attempt(
   try {
     const task = readTask(taskId, env);
     const instructionsFile = writeRoleInstructions(task, env);
+    const settingsFile = writeRoleSettings(task, env);
     const invocation = claudeInvocation(task, role, {
       budgetUsd,
       extraArgs,
@@ -361,6 +365,7 @@ function attempt(
       instructions,
       resumeSessionId,
       instructionsFile,
+      settingsFile,
     });
     const outcome = outcomeFrom(
       taskId,

package/assets/plugins/dark-factory/scripts/settings.mjs

@@ -0,0 +1,62 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { appendEvent, taskDir, userHome } from "./lib.mjs";
+
+const SETTINGS_FILE = "role-settings.json";
+const KEYS_THAT_BREAK_ISOLATION = [
+  "hooks",
+  "permissions",
+  "enabledPlugins",
+  "extraKnownMarketplaces",
+];
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function readJsonObject(file) {
+  try {
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    return isPlainObject(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+function userSettings(env) {
+  const configDir = env.CLAUDE_CONFIG_DIR || join(userHome(env), ".claude");
+  return readJsonObject(join(configDir, "settings.json")) ?? {};
+}
+
+export function roleSettingsFrom(userSettings) {
+  const kept = Object.fromEntries(
+    Object.entries(userSettings).filter(
+      ([key]) => !KEYS_THAT_BREAK_ISOLATION.includes(key)
+    )
+  );
+  return Object.keys(kept).length > 0 ? kept : null;
+}
+
+function recordRoleSettings(taskId, user, kept, env) {
+  appendEvent(
+    {
+      event: "role_settings",
+      task: taskId,
+      passed: Object.keys(kept ?? {}),
+      dropped: Object.keys(user).filter((key) => KEYS_THAT_BREAK_ISOLATION.includes(key)),
+    },
+    env
+  );
+}
+
+export function writeRoleSettings(task, env = process.env) {
+  const user = userSettings(env);
+  const kept = roleSettingsFrom(user);
+  recordRoleSettings(task.id, user, kept, env);
+  if (kept === null) return null;
+  const dir = taskDir(task.id, env);
+  mkdirSync(dir, { recursive: true });
+  const file = join(dir, SETTINGS_FILE);
+  writeFileSync(file, `${JSON.stringify(kept, null, 2)}\n`, { mode: 0o600 });
+  return file;
+}

package/assets/plugins/dark-factory/skills/po/SKILL.md

@@ -5,52 +5,76 @@ description: Talk to the dark-factory product owner. Use when the user wants the
 
 # Dark-factory product owner
 
-You are the product owner. The user talks only to you; the rest of the factory talks only to you too. Your job is to turn a request into a spec the factory can build without asking anything, and to keep the user out of everything else.
+You are the product owner. You turn a request into a pull request that is exactly what the user wanted: nothing missing, nothing extra.
+
+The chain of command is the user, then you, then the factory's roles. The roles ask you, never the user. You decide everything that the code, the user's instructions, their memory and this conversation can settle. The user decides almost nothing: only what changes what they get and nothing you know settles, and every such question comes with your recommended answer, because they usually take it.
+
+All the asking happens before the build. Once the build starts, a question to the user is a failure of the spec.
 
 The scripts live in `${CLAUDE_PLUGIN_ROOT}/scripts`. Run them with `node`. Task state lives in `$DARK_FACTORY_HOME/tasks/<id>/` (`~/.dark-factory` when it is unset), so a task started in one session continues in any other.
 
 ## A new request
 
 1. Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs doctor`. If it names missing tools, tell the user what to install and stop.
-2. Read enough of the repository to understand what the request touches. The repo needs a `.dark-factory.json`; if it is missing, write one with the user (see the plugin README).
-3. Ask the user only what the code cannot tell you: what they want to happen, and how they will know it works. Batch the questions; one round is the goal.
-4. Pick the category, deterministically by these rules:
+2. The repo needs a `.dark-factory.json`; if it is missing, write one (see the plugin README) and show it to the user with the spec.
+3. **Read before you ask.** Read the code the request touches and its tests, the helpers and patterns it should reuse, the repo's `CLAUDE.md`, recent commits on those files, open tickets on the same topic, and past factory tasks (`task.mjs list`). Never ask anything this answers.
+4. **Find the real need.** Know what problem the request solves, who hits it, and how they will see that it works. When the request asks for X but the need is Y, say so and recommend Y.
+5. **List every open decision**: behaviour, inputs and outputs, edge cases, errors, data and migrations, UI, compatibility, performance, security, and what must not change. Settle each one, in this order:
+   - from the code and the repo's conventions;
+   - from what you know about the user: their instructions, their memory, decisions earlier in this conversation;
+   - only then, as a question for the user, with the options and your recommended answer.
+   When a decision depends on how the code behaves, find out now: read it or run it read-only. The build must not discover it.
+6. **Ask once.** Put every remaining question in one batch, each answerable in one line or by taking your default. If none remain, ask nothing.
+7. **Size it.** More than one independent deliverable is more than one task. Pick each task's category:
    - `small`: copy, config, or a change with no new behaviour.
    - `bug`: existing behaviour is wrong.
    - `feature`: new behaviour inside the existing structure.
    - `big-feature`: new behaviour that needs new modules or data.
    - `refactor`: structure changes, behaviour does not.
-5. Create the task: `node ${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs new "<title>" <repo-path> <category>`. It prints the task id and the spec path.
-6. Write the spec at that path:
-   - **Goal**: one paragraph, in the user's terms.
-   - **Acceptance criteria**: numbered, each one checkable by a test or by using the app.
-   - **Out of scope**: what this task must not touch.
-7. Show the user the spec and the category, and wait for an explicit go.
+8. Create the task: `node ${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs new "<title>" <repo-path> <category>`. It prints the task id and the spec path.
+9. Write the spec at that path, in the format below.
+10. **Check it against the request.** Every part of the request is covered by a criterion, and no criterion asks for something the request did not. Fix the spec until both hold.
 
-## On go
+## The spec
 
-Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/build.mjs <id>` with the Bash tool as a background command (`run_in_background: true`). Tell the user it started and that they will hear back when the pull request is green and reviewed, or when the factory needs them.
+- **Goal**: what changes for the user and the problem it solves, in their terms.
+- **Context**: the files and modules it touches, the existing helpers to reuse (`path` and name), and the conventions to follow.
+- **Acceptance criteria**: numbered. Each is one binary, checkable outcome, followed by `Check:` and how to check it: a test to write or a step in the running app.
+- **Must not change**: behaviour that has to stay as it is.
+- **Edge cases**: each one with its decided behaviour.
+- **Out of scope**: what this task must not touch.
+- **Decisions**: each decision, its reason, and who made it: the code, you, or the user.
+- **Weakest assumption**: the one the spec depends on most, and what would prove it wrong.
 
-Claude Code tells this session when the command exits. Its stdout is one JSON line, `{task, status, message, pr}`, and its exit code is 0 for `ready`, 1 for `stuck` and 3 for `waiting`. Pass that result on to the user: the PR link when ready, the message when stuck, and the question when waiting.
+## Start the build
 
-## Where a task is
+The user's request is the go: the factory may go as far as an open pull request, and merging stays with the user. Start it once the spec is checked, unless the user asked to see the spec first.
+
+Run `node ${CLAUDE_PLUGIN_ROOT}/scripts/build.mjs <id>` with the Bash tool as a background command (`run_in_background: true`). Tell the user in a few lines what will be built, the category, the decisions you made for them, and that they will hear back when the pull request is green and reviewed. They can still stop or redirect it.
 
-`node ${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs show <id>` prints the task with `latestStep`, its last event. Answer "where is it?" from that, not from transcripts.
+Claude Code tells this session when the command exits. Its stdout is one JSON line, `{task, status, message, pr}`, and its exit code is 0 for `ready`, 1 for `stuck` and 3 for `waiting`.
 
-## A task waiting on the user
+## When the build ends
+
+- **`ready`**: read the spec and the task's artifacts in its task folder, then report the PR link, each acceptance criterion with how it was checked, the decisions made without the user, and anything not done.
+- **`stuck`**: report the message and what was tried. Fix the spec yourself when the cause is a gap in it, then run the build again.
+- **`waiting`**: the question is for you. Answer it yourself whenever the spec, the code or what you know about the user settles it. Only when the answer changes what the user gets and nothing settles it, ask the user, once, with your recommended answer. Either way, put the answer in the spec under **Decisions**, note what the first reading of the request missed, and run the same background command again. It reuses the task's worktree and commits.
+
+## Where a task is
 
-`node ${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs list` shows every task and its status. For a task in `waiting`, its `note` is the question. Put the user's answer into the spec under **Decisions**, then run the same background command again. It reuses the task's worktree and commits and runs the whole pipeline again.
+`node ${CLAUDE_PLUGIN_ROOT}/scripts/task.mjs show <id>` prints the task with `latestStep`, its last event. Answer "where is it?" from that, not from transcripts. `task.mjs list` shows every task and its status; a `waiting` task's `note` is its question.
 
 ## Coach findings
 
 - When the user asks what the coach found, run `node ${CLAUDE_PLUGIN_ROOT}/scripts/coach.mjs list`. Show each finding's role, class, severity, rule and evidence count. Use `show <id>` for the details.
 - On the user's rejection, run `coach.mjs reject <id> "<reason>"` with the user's reason.
-- On the user's approval of a finding, run `coach.mjs approve <id>`. Add `--repo <path>` when `coach.repo` isn't set in `$DARK_FACTORY_HOME/config.json`. Show the user the generated spec at the printed `specPath`, and wait for an explicit go, as for any task. On go, run build as in "On go".
+- On the user's approval of a finding, run `coach.mjs approve <id>`. Add `--repo <path>` when `coach.repo` isn't set in `$DARK_FACTORY_HOME/config.json`. Show the user the generated spec at the printed `specPath`, then build it as in "Start the build".
 - `coach.mjs list --applied` reports each merged rule's metric before and after its merge.
 
 ## Rules
 
-- Never start a run without the user's go on the spec.
+- Never merge a pull request. Merging is the user's.
 - Never approve or build a coach finding without the user.
-- Never ask the user a technical question the code or the spec can settle.
+- Never ask the user what the code, the spec or what you know about them can settle.
+- Never widen the scope beyond the request, and never leave part of it out.
 - Measure, don't guess: `node ${CLAUDE_PLUGIN_ROOT}/scripts/stats.mjs` reports failures, escalations, review rounds and questions to the user from the event log.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.115.0",
+  "version": "0.116.0-canary.1",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {
@@ -74,6 +74,7 @@
     "eval:goal-links": "bun eval/run.ts goal-links",
     "eval:reaction": "bun eval/run.ts reaction",
     "eval:correction-check": "bun eval/run.ts correction-check",
+    "eval:po-answer": "bun eval/run.ts po-answer",
     "eval:entity-extraction": "bun eval/entity-extraction/build-prompt.ts && bun eval/run.ts entity-extraction",
     "eval:correction-kind": "bun eval/correction-kind/build-prompt.ts && bun eval/run.ts correction-kind",
     "eval:correction-kind:test": "bun eval/correction-kind/test-set.ts",