Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions .modonome/config.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -67,11 +67,13 @@ roles:
self-govern:
runner: container
model: claude-haiku-4-5-20251001
# Researcher agent: a capability profile example (ADR-039). It is NOT on the active
# role_sequence (maker -> checker), so it does not run in the loop yet; it is defined
# here so its skills, tools, and prioritized model fallback are configurable ahead of
# loop wiring. models is a priority list: the paid frontier choice first, falling back
# to the free/local one when no daily budget is set.
# Researcher agent (ADR-039, wired into the loop by WI-042). It is NOT on the
# active role_sequence (maker -> checker), so a plain run-cycle invocation still
# runs just the pair; run it on its own schedule with
# `node scripts/agent/run-cycle.mjs --roles researcher --execute`, or add it to
# role_sequence to run every cycle alongside maker/checker. models is a priority
# list: the paid frontier choice first, falling back to the free/local one when
# no daily budget is set.
researcher:
runner: container
models: [claude-opus-4-8, local-default]
Expand Down
2 changes: 1 addition & 1 deletion .modonome/snapshot/badge.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"color":"blue","label":"snapshot","message":"889 files, 118404 tok","schemaVersion":1}
{"color":"blue","label":"snapshot","message":"891 files, 118554 tok","schemaVersion":1}
2 changes: 1 addition & 1 deletion .modonome/snapshot/map.json

Large diffs are not rendered by default.

147 changes: 76 additions & 71 deletions .modonome/snapshot/map.md

Large diffs are not rendered by default.

2 changes: 1 addition & 1 deletion .modonome/snapshot/signature.json
Original file line number Diff line number Diff line change
@@ -1 +1 @@
{"commands":{"build":"","lint":"","test":"npm test"},"entrypoints":["bin/modonome.mjs"],"generated_at":"2026-07-07T02:40:29.394Z","generated_for":"modonome","governance":{"armed":false,"autonomy_enabled":false,"dry_run":true},"instructions":["AGENTS.md","CODEX.md","CONTRIBUTING.md","README.md"],"language_mix":{"(none)":11,"css":50,"diff":15,"html":9,"js":19,"json":127,"jsonl":7,"md":122,"mjs":271,"patch":37,"png":5,"py":4,"sh":1,"svg":1,"tf":4,"toml":2,"ts":60,"tsx":98,"txt":7,"webmanifest":1,"webp":1,"woff2":9,"xml":1,"yaml":7,"yml":20},"merkle_root":"sha256:4cea131917d0dd424ed64ccaeb7d97411fcd964fcfdc66f436ef7e1304cf1f14","preamble":"Modonome snapshot. Read this before reading the repo. Tier 0 (signature.json) is the fingerprint: if merkle_root matches your last read, nothing changed. Tier 1 (map.json / map.md) lists modules, public API signatures, import edges, and attention ranking. Cite anchors (F: for files, S: for symbols); each resolves to a path and line so you can act without re-reading the whole repo.","protected_paths":[".github",".github/CODEOWNERS","package-lock.json"],"schema_version":1,"size":{"bytes":3367444,"files":889},"snapshot_version":5,"stack":{"name":"Node or TypeScript","pm":"npm"},"tier_hashes":{"map":"sha256:223eabbda69dbcaa25c3007597453f5d462a5c470afc1e6fec91f94b034b1075","map_md":"sha256:ec944f27b5c94082f150322541c201fd078bcefc7c1e6e1a27934b5fd8a0dd51"}}
{"commands":{"build":"","lint":"","test":"npm test"},"entrypoints":["bin/modonome.mjs"],"generated_at":"2026-07-07T05:33:41.205Z","generated_for":"modonome","governance":{"armed":false,"autonomy_enabled":false,"dry_run":true},"instructions":["AGENTS.md","CODEX.md","CONTRIBUTING.md","README.md"],"language_mix":{"(none)":11,"css":50,"diff":15,"html":9,"js":19,"json":127,"jsonl":7,"md":122,"mjs":272,"patch":37,"png":5,"py":4,"sh":1,"svg":1,"tf":4,"toml":2,"ts":60,"tsx":98,"txt":8,"webmanifest":1,"webp":1,"woff2":9,"xml":1,"yaml":7,"yml":20},"merkle_root":"sha256:bb3b608f5429ce8add3caaa04e9b8302585050ba35794937e69aea16329d4727","preamble":"Modonome snapshot. Read this before reading the repo. Tier 0 (signature.json) is the fingerprint: if merkle_root matches your last read, nothing changed. Tier 1 (map.json / map.md) lists modules, public API signatures, import edges, and attention ranking. Cite anchors (F: for files, S: for symbols); each resolves to a path and line so you can act without re-reading the whole repo.","protected_paths":[".github",".github/CODEOWNERS","package-lock.json"],"schema_version":1,"size":{"bytes":3378178,"files":891},"snapshot_version":8,"stack":{"name":"Node or TypeScript","pm":"npm"},"tier_hashes":{"map":"sha256:5d07b766af976b1d3e2416ae7376f0c80d007cb71990c3c21c661e7fa69021f5","map_md":"sha256:182a9fe8483759cd4432905ca7a506cc5f10f9d9363dd86007cd71803128e082"}}
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
{
"schema_version": 1,
"id": "WI-042-researcher-agent-loop-integration",
"state": "queued",
"state": "done",
"type": "develop-feature",
"assigned_role": "researcher",
"attempts": 0,
Expand Down
18 changes: 12 additions & 6 deletions ARCHITECTURE.md
Original file line number Diff line number Diff line change
Expand Up @@ -365,12 +365,18 @@ flowchart LR
class gate floor
```

Market and standards scans are planned for a dedicated market-researcher role (roadmap,
not shipped). When implemented and enabled, sourced findings would flow to the steward
role, which scores and routes proposals, and would default off. Net-new claims would need
owner approval before any roadmap change. The
proposal priority score (`safety + user_value + repo_fit + reuse + evidence - effort -
blast_radius - uncertainty`) surfaces the highest-value, lowest-risk improvements first.
The researcher role (ADR-039) is wired into the loop (WI-042): `prompts/roles/researcher.txt`
has it read the repo's own state, draft one proposal, run it past the independent check at
Checkpoint 1 (`review-proposals.mjs`, ADR-040), and, only on approval, author a schema-valid
work item itself. It is not on the default `role_sequence`, so a plain cycle still runs just
maker and checker; run it on its own schedule with `run-cycle.mjs --roles researcher
--execute`, or add it to `role_sequence` to run every cycle. `planCycle` fails closed during
planning, before any execution, when a configured role has no prompt file. Real external
market and standards scans (the `web-search` tool a researcher can declare, ADR-039) are
still descriptive only pending gated tool execution (WI-043); until then the researcher's
findings come from the repo's own durable state, not the outside world. The proposal
priority score (`safety + user_value + repo_fit + reuse + evidence - effort - blast_radius -
uncertainty`) surfaces the highest-value, lowest-risk improvements first.

## Trust boundaries and security invariants

Expand Down
15 changes: 15 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,21 @@ or CVE identifier where one exists.

## Unreleased

### Wire the researcher role into the agent loop (WI-042)

- Added `prompts/roles/researcher.txt`: reads the repo's own durable state, drafts one
proposal, runs it past the independent check at Checkpoint 1
(`scripts/agent/review-proposals.mjs`, ADR-040), and, only on approval, authors and
self-validates a schema-valid work item. It never claims, makes, or checks the item itself.
- Added a `--roles a,b,c` CLI override to `scripts/agent/run-cycle.mjs` (`resolveRoleSequence`
now takes an `opts` argument), so a single invocation can run just the researcher, or any
other subset, on its own schedule, without editing `role_sequence` in config. Absent the
override, behavior is unchanged: `cfg.role_sequence`, then the maker/checker default.
- `planCycle` now fails closed when a role in the executed sequence has no prompt file at
`prompts/roles/<role>.txt`, caught during planning and dry-run rather than surfacing only
as an `ENOENT` deep inside a real `--execute` run.
- No schema or config-lever change.

### Runtime model fallback for a role's prioritized model chain (WI-041)

- `scripts/agent/run-cycle.mjs` now walks a role's prioritized `models` chain (ADR-039) at
Expand Down
4 changes: 2 additions & 2 deletions RELEASE-EVIDENCE.md
Original file line number Diff line number Diff line change
Expand Up @@ -29,8 +29,8 @@ be added here once the owner arms the loop on this repo.

## Work queue

- done: 38
- queued: 5
- done: 39
- queued: 4

## Sample-app captures

Expand Down
23 changes: 23 additions & 0 deletions prompts/roles/researcher.txt
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
You are the RESEARCHER in a modonome cycle. Follow AGENTS.md exactly. You are '${RESEARCHER_ID}' (model '${RESEARCHER_MODEL}').
1. Read .modonome/STATUS.md and .modonome/DECISIONS.md, and the work items under
.modonome/work-items/, so you do not propose what is already queued or done.
2. Identify ONE well-scoped candidate for the backlog: a gap, a follow-up, a codebase
or market observation worth acting on. Pick one work-item type (fix-issue,
develop-feature, create-article, create-plan, update-docs, chore). If nothing new
is worth proposing this cycle, print 'No new proposal this cycle.' and exit 0.
3. Draft the proposal as a short, concrete sentence: what to do and why. Run
`node scripts/agent/review-proposals.mjs --proposal "<your proposal>" --execute`.
This is an INDEPENDENT check; you did not write the checker's verdict and cannot
influence it beyond the proposal text itself.
4. If it prints 'APPROVE: no', print the rationale and stop. Do not write a work item.
5. If it prints 'APPROVE: yes', author one schema-valid work item JSON under
.modonome/work-items/ with a fresh WI-<n>-<slug> id, state 'queued', assigned_role
'maker', your chosen type, a plausible allowed_edit_set and gates, and queued_at
today's date. Validate it with `node scripts/validate-work-item.mjs <file>` before
finishing; fix and re-validate on any error rather than leaving an invalid item.
6. Never claim, make, or check the item yourself. A researcher proposes; it does not
build. Print a one-sentence summary of what you proposed and why, or why you
proposed nothing this cycle.

Institutional memory -- do not repeat these mistakes:
${PROMOTED_LEARNINGS}
24 changes: 18 additions & 6 deletions scripts/agent/run-cycle.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -41,11 +41,16 @@ const HARD_TURN_CAP = 80;
// invocations that do not participate in the maker/checker distinctness pairing.
const CORE_ROLE_SEQUENCE = ["maker", "checker"];

// Derive the ordered list of roles the cycle executes. An explicit cfg.role_sequence
// (a non-empty array of role names) is honored so a crew role added in config runs
// with no code change; otherwise it defaults to the maker/checker pair, preserving
// current behavior exactly. Pure: reads config, returns a fresh array.
export function resolveRoleSequence(cfg) {
// Derive the ordered list of roles the cycle executes. An explicit --roles CLI
// override (opts.roles) takes precedence, so a single invocation can run just the
// researcher (or any other subset) without editing config, matching the scheduled
// operating model (ADR-040): research, make, and check can run on independent
// schedules against the same config. Absent that, an explicit cfg.role_sequence (a
// non-empty array of role names) is honored so a crew role added in config runs with
// no code change; otherwise it defaults to the maker/checker pair, preserving current
// behavior exactly. Pure: reads config and opts, returns a fresh array.
export function resolveRoleSequence(cfg, opts = {}) {
if (Array.isArray(opts.roles) && opts.roles.length > 0) return [...opts.roles];
const seq = cfg?.role_sequence;
if (Array.isArray(seq) && seq.length > 0) return [...seq];
return [...CORE_ROLE_SEQUENCE];
Expand Down Expand Up @@ -104,6 +109,7 @@ export function parseArgs(argv) {
else if (a === "--dry-run") opts.execute = false;
else if (a === "--enqueue") opts.enqueue = true;
else if (a === "--worker-env") opts.workerEnv = argv[++i];
else if (a === "--roles") opts.roles = argv[++i].split(",").map((s) => s.trim()).filter(Boolean);
}
return opts;
}
Expand Down Expand Up @@ -177,7 +183,7 @@ export function planCycle(opts, cfg, runId) {
runId,
maker: { ...maker, id: `maker:${appName}:${runId}:${maker.model}`, route: makerRoute, execMode: resolveExecMode(cfg, maker.model) },
checker: { ...checker, id: `checker:${appName}:${runId}:${checker.model}`, route: checkerRoute, execMode: resolveExecMode(cfg, checker.model) },
roleSequence: resolveRoleSequence(cfg),
roleSequence: resolveRoleSequence(cfg, opts),
maxTurns,
transcriptDir: join(opts.target, "runs", runId),
budget,
Expand All @@ -192,6 +198,12 @@ export function planCycle(opts, cfg, runId) {
// crew role's model is still budget-classified and route-resolved (fail-closed).
for (const role of plan.roleSequence) {
if (role === "maker" || role === "checker" || plan[role]) continue;
// Every transport renders prompts/roles/<role>.txt (buildRolePrompt), so a role
// added to role_sequence with no prompt file is caught here, during planning and
// dry-run, rather than surfacing as an ENOENT deep inside a real --execute run.
if (!existsSync(join(root, "prompts", "roles", `${role}.txt`))) {
throw new Error(`role "${role}" is in role_sequence but has no prompt at prompts/roles/${role}.txt.`);
}
const crew = resolveRole(cfg, role);
if (opts.runner) crew.runner = opts.runner;
if (known.size > 0 && !known.has(crew.model)) {
Expand Down
2 changes: 1 addition & 1 deletion site/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -795,7 +795,7 @@ <h2 style="font-family:'Space Grotesk',sans-serif;font-weight:600;font-size:clam
netGeo: null, netActive: -1, netPhase: 'idle', netSeq: 0, netShared: 128, activeSection: 'top',
live: null, syncStatus: 'cached', relIndex: 0 };
this.repoBase = { tests: 248, coverage: '81%', deps: 3, debt: 12 };
this.engineBase = { lessons: 3, rules: 0, gates: 7, queue: 5, version: 'v0.1.0-alpha', armed: false };
this.engineBase = { lessons: 3, rules: 0, gates: 8, queue: 4, version: 'v0.1.0-alpha', armed: false };
this.STAGES = [
{title:'Maker', sub:'builds one small change', scope:'AGENT', live:'The maker is writing one small, scoped change and pinning it with a test.'},
{title:'Checker', sub:'reviews it independently', scope:'AGENT', live:'A separate checker reviews the diff. The maker never approves its own work.'},
Expand Down
126 changes: 126 additions & 0 deletions tests/researcher-role.test.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,126 @@
// WI-042 (ADR-039/ADR-040 follow-up): the researcher actually running in the loop.
// planCycle already resolved a generic crew role (WI-040); the two gaps this closes
// are (1) a role in role_sequence with no prompt file failed only deep inside a real
// --execute run (ENOENT), not during planning/dry-run, and (2) there was no way to
// run a single role (the researcher alone) for a schedule independent of maker/checker
// without editing config. Fully offline: no model call, no network.
import { test } from "node:test";
import assert from "node:assert/strict";
import { readFileSync } from "node:fs";
import { dirname, join } from "node:path";
import { fileURLToPath } from "node:url";
import { planCycle, parseArgs, resolveRoleSequence } from "../scripts/agent/run-cycle.mjs";
import { renderPrompt } from "../scripts/agent/render-prompt.mjs";

const here = dirname(fileURLToPath(import.meta.url));
const root = join(here, "..");

function baseCfg(extra = {}) {
return {
schema_version: 1,
remote_model_budget_usd_per_day: 0,
roles: {
maker: { runner: "container", model: "claude-sonnet-4-6" },
checker: { runner: "container", model: "claude-opus-4-8" },
researcher: { runner: "container", model: "claude-opus-4-8" },
},
runners: { container: { labels: ["ubuntu-latest"], cli_path: "claude" } },
models: {
"claude-sonnet-4-6": { provider: "anthropic" },
"claude-opus-4-8": { provider: "anthropic" },
},
...extra,
};
}

// ---------------------------------------------------------------------------
// prompts/roles/researcher.txt exists and renders.
// ---------------------------------------------------------------------------

test("prompts/roles/researcher.txt exists and renders with the substitutions buildRolePrompt supplies", () => {
const text = renderPrompt("researcher", {
RESEARCHER_ID: "researcher:demo:run1:claude-opus-4-8",
RESEARCHER_MODEL: "claude-opus-4-8",
RUN_BRANCH: "modonome/run-test",
PROMOTED_LEARNINGS: "(none yet)",
});
assert.match(text, /RESEARCHER/);
assert.match(text, /review-proposals\.mjs --proposal/);
assert.match(text, /validate-work-item\.mjs/);
assert.match(text, /Never claim, make, or check the item yourself/);
});

test("the researcher prompt is a real file under source control, not generated", () => {
const path = join(root, "prompts", "roles", "researcher.txt");
assert.doesNotThrow(() => readFileSync(path, "utf8"));
});

// ---------------------------------------------------------------------------
// --roles CLI override
// ---------------------------------------------------------------------------

test("parseArgs parses --roles into a trimmed, non-empty array", () => {
assert.deepEqual(parseArgs(["--target", "x", "--roles", "researcher"]).roles, ["researcher"]);
assert.deepEqual(parseArgs(["--roles", "maker, checker , researcher"]).roles, ["maker", "checker", "researcher"]);
});

test("resolveRoleSequence: an opts.roles override takes precedence over cfg.role_sequence and the default", () => {
assert.deepEqual(resolveRoleSequence({ role_sequence: ["maker", "checker"] }, { roles: ["researcher"] }), ["researcher"]);
assert.deepEqual(resolveRoleSequence({}, { roles: ["researcher"] }), ["researcher"]);
// No override: falls through to cfg.role_sequence, then the default, exactly as before.
assert.deepEqual(resolveRoleSequence({ role_sequence: ["maker", "checker", "researcher"] }, {}), ["maker", "checker", "researcher"]);
assert.deepEqual(resolveRoleSequence({}, {}), ["maker", "checker"]);
// An empty override array is not an override (matches the empty-role_sequence rule).
assert.deepEqual(resolveRoleSequence({}, { roles: [] }), ["maker", "checker"]);
});

// ---------------------------------------------------------------------------
// planCycle: a scheduled loop can run the researcher alone.
// ---------------------------------------------------------------------------

test("planCycle with --roles researcher runs only the researcher, on the same config used for maker/checker", () => {
const cfg = baseCfg();
const plan = planCycle({ target: "examples/demo-app", roles: ["researcher"] }, cfg, "research-only");
assert.deepEqual(plan.roleSequence, ["researcher"]);
assert.equal(plan.researcher.model, "claude-opus-4-8");
assert.equal(plan.researcher.id, "researcher:demo-app:research-only:claude-opus-4-8");
assert.ok(plan.researcher.route, "the researcher still gets a resolved execution route");
});

test("planCycle with --roles maker,checker,researcher runs the full extended sequence", () => {
const cfg = baseCfg();
const plan = planCycle({ target: "examples/demo-app", roles: ["maker", "checker", "researcher"] }, cfg, "extended");
assert.deepEqual(plan.roleSequence, ["maker", "checker", "researcher"]);
assert.equal(plan.maker.model, "claude-sonnet-4-6");
assert.equal(plan.checker.model, "claude-opus-4-8");
assert.equal(plan.researcher.model, "claude-opus-4-8");
});

// ---------------------------------------------------------------------------
// Fail closed at planning time when a role has no prompt file, not at --execute.
// ---------------------------------------------------------------------------

test("planCycle throws when a role_sequence entry has no prompt file, caught during dry-run", () => {
const cfg = baseCfg({
role_sequence: ["maker", "checker", "no-such-role"],
roles: {
maker: { runner: "container", model: "claude-sonnet-4-6" },
checker: { runner: "container", model: "claude-opus-4-8" },
"no-such-role": { runner: "container", model: "claude-opus-4-8" },
},
});
assert.throws(
() => planCycle({ target: "examples/demo-app" }, cfg, "missing-prompt"),
/role "no-such-role" is in role_sequence but has no prompt at prompts\/roles\/no-such-role\.txt/,
);
});

test("a dry-run (no --execute) catches the missing prompt too, planCycle is dry-run's own core", () => {
const cfg = baseCfg({ role_sequence: ["researcher", "envisioner"] });
// "envisioner" has a built-in resolveRole fallback (WI-040) but no prompt file: it must
// still fail during planning, since planCycle is dry-run's own core.
assert.throws(
() => planCycle({ target: "examples/demo-app" }, cfg, "dry-missing"),
/envisioner.*no prompt at prompts\/roles\/envisioner\.txt/,
);
});
Loading