robisie 0.1.3 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (52) hide show
  1. package/CHANGELOG.md +22 -0
  2. package/README.md +73 -19
  3. package/dist/agents.d.ts +1 -1
  4. package/dist/agents.js +1 -1
  5. package/dist/ci-failure-result.js +1 -1
  6. package/dist/cli.d.ts +2 -0
  7. package/dist/cli.js +45 -8
  8. package/dist/codex-env.d.ts +9 -0
  9. package/dist/codex-env.js +60 -0
  10. package/dist/commands.js +140 -16
  11. package/dist/constants.d.ts +1 -1
  12. package/dist/constants.js +1 -1
  13. package/dist/delivery-local.d.ts +124 -0
  14. package/dist/delivery-local.js +286 -0
  15. package/dist/done-evidence.d.ts +25 -1
  16. package/dist/done-evidence.js +59 -1
  17. package/dist/engine/bundle-report.json +1687 -0
  18. package/dist/engine/tick.cjs +324704 -0
  19. package/dist/engine-config.d.ts +3 -1
  20. package/dist/engine-config.js +3 -3
  21. package/dist/factory-run.d.ts +17 -0
  22. package/dist/factory-run.js +262 -0
  23. package/dist/helpers.js +1 -1
  24. package/dist/k3-codex-job.d.ts +49 -0
  25. package/dist/k3-codex-job.js +324 -0
  26. package/dist/k3-helper-cli.d.ts +5 -0
  27. package/dist/k3-helper-cli.js +167 -0
  28. package/dist/local-usage.d.ts +47 -0
  29. package/dist/local-usage.js +230 -0
  30. package/dist/manifest.d.ts +5 -2
  31. package/dist/manifest.js +6 -6
  32. package/dist/opencode-review-guard.js +7 -2
  33. package/dist/planer-client.d.ts +45 -4
  34. package/dist/planer-client.js +120 -14
  35. package/dist/roles.d.ts +1 -1
  36. package/dist/seed-package.d.ts +10 -0
  37. package/dist/seed-package.js +62 -0
  38. package/dist/select-fingerprint.d.ts +19 -0
  39. package/dist/select-fingerprint.js +46 -0
  40. package/dist/task-mktemp.d.ts +1 -0
  41. package/dist/task-mktemp.js +40 -0
  42. package/dist/test-report.d.ts +9 -0
  43. package/dist/test-report.js +139 -0
  44. package/dist/tester-result-reader.d.ts +87 -0
  45. package/dist/tester-result-reader.js +122 -0
  46. package/docs/ENGINE-API.md +9 -1
  47. package/docs/README.en.md +161 -66
  48. package/docs/README.md +159 -66
  49. package/docs/RELEASE-0.1.0.md +29 -5
  50. package/helpers/ceo-client-launcher-mcp.mjs +76 -5
  51. package/package.json +6 -2
  52. package/roles/ceo-client.md +10 -8
@@ -93,7 +93,7 @@ export function validateLauncherResult(value, cardRef) {
93
93
  return result;
94
94
  }
95
95
 
96
- function builderCommand(environment) {
96
+ function configuredRole(environment, role, label) {
97
97
  let configDir;
98
98
  let provider;
99
99
  try {
@@ -102,16 +102,28 @@ function builderCommand(environment) {
102
102
  }
103
103
  configDir = join(environment.XDG_CONFIG_HOME || join(environment.HOME, ".config"), "robisie");
104
104
  const manifest = JSON.parse(readFileSync(join(configDir, "manifest.json"), "utf8"));
105
+ if (role === "quality" && Object.hasOwn(manifest, "roleProviders")) {
106
+ const map = manifest.roleProviders;
107
+ if (!map || typeof map !== "object" || Array.isArray(map) || Object.keys(map).length !== 3
108
+ || !["ceo", "builder", "quality"].every(name => Object.hasOwn(map, name) && ["claude", "codex", "opencode"].includes(map[name]))) {
109
+ throw new Error("quality requires a complete valid roleProviders map");
110
+ }
111
+ }
105
112
  // Match init's migration of legacy single-provider installs; never guess an ambiguous assignment.
106
113
  provider = Object.hasOwn(manifest, "roleProviders")
107
- ? manifest.roleProviders?.builder
114
+ ? manifest.roleProviders?.[role]
108
115
  : Array.isArray(manifest.agents) && manifest.agents.length === 1 ? manifest.agents[0] : undefined;
109
116
  } catch {
110
- throw new Error("Builder configuration could not be read; run npx robisie init");
117
+ throw new Error(`${label} configuration could not be read; run npx robisie init`);
111
118
  }
112
119
  if (!["claude", "codex", "opencode"].includes(provider)) {
113
- throw new Error("Builder provider is missing or invalid; configure builder with npx robisie init --role");
120
+ throw new Error(`${label} provider is missing or invalid; configure ${role} with npx robisie init --role`);
114
121
  }
122
+ return { configDir, provider };
123
+ }
124
+
125
+ function builderCommand(environment) {
126
+ const { configDir, provider } = configuredRole(environment, "builder", "Builder");
115
127
  if (provider === "claude") return `claude --print --agent manager-builder-client --permission-mode dontAsk '${BUILDER_PROMPT}'`;
116
128
  if (provider === "opencode") return `opencode run --agent manager-builder-client '${BUILDER_PROMPT}'`;
117
129
  const rolePath = join(configDir, "roles", "codex", "manager-builder-client.md");
@@ -543,7 +555,66 @@ function receiptFromToolInput({ cardRef, ...receipt }) {
543
555
  return { cardRef, receipt };
544
556
  }
545
557
 
558
+ async function spawnQuality(cardRef, dependencies) {
559
+ try {
560
+ validateCardRef(cardRef);
561
+ const environment = dependencies.environment ?? process.env;
562
+ const credential = dependencies.credential ?? environment.ROBISIE_KEY;
563
+ if (!nonEmptyText(credential)) throw new Error("quality credential is missing");
564
+ const { configDir, provider } = configuredRole(environment, "quality", "Quality");
565
+ if (provider !== "codex") throw new Error("quality provider is not Codex");
566
+ const projectContext = resolveProjectContext(environment);
567
+ if (!lstatSync(projectContext).isDirectory()) throw new Error("project context must be a directory");
568
+ const role = readFileSync(join(configDir, "roles/codex/quality-officer-client.md"), "utf8");
569
+ if (!nonEmptyText(role)) throw new Error("quality role is empty");
570
+ const task = await (dependencies.readTask ?? ((key, ref) => readHostedTask(key, ref, { environment })))(credential, cardRef);
571
+ if (!task || task.id !== cardRef || task.status !== "in_review") {
572
+ throw new Error("quality requires the exact in_review card");
573
+ }
574
+ const prompt = `${role}\n\nReview only cardRef: ${cardRef}. Bind get_project_context first; require configured MCP. Follow prepare_review, independent checks, create_review_receipt, append/readback and verify_stored_review. Return only the complete direct JSON receipt.\n`;
575
+ const stdout = await new Promise((resolveOutput, rejectOutput) => {
576
+ const child = (dependencies.execQuality ?? execFile)("codex", [
577
+ "exec", "--ephemeral", "-s", "read-only", "-c", 'model_reasoning_effort="high"', "-",
578
+ ], {
579
+ cwd: projectContext,
580
+ env: { ...copyLaunchEnvironment(environment), ROBISIE_KEY: credential, ROBISIE_PROJECT_CONTEXT: projectContext },
581
+ shell: false,
582
+ encoding: "utf8",
583
+ timeout: 120_000,
584
+ maxBuffer: 4 * 1024 * 1024,
585
+ }, (error, output) => error ? rejectOutput(error) : resolveOutput(output));
586
+ child.stdin.on("error", () => {
587
+ rejectOutput(new Error("quality stdin failed"));
588
+ try { child.kill(); } catch { /* The failed process remains a failed invocation. */ }
589
+ });
590
+ try { child.stdin.end(prompt); } catch (error) {
591
+ rejectOutput(error);
592
+ try { child.kill(); } catch { /* No retry after a process input failure. */ }
593
+ }
594
+ });
595
+ // Never redact a receipt: changing its bytes would invalidate its fingerprints.
596
+ const safeEnvironment = credentialEnvironment(environment, credential);
597
+ if (typeof stdout !== "string" || redactLauncherText(stdout, safeEnvironment) !== stdout) {
598
+ throw new Error("quality output is missing or contains a credential");
599
+ }
600
+ const receipt = JSON.parse(stdout);
601
+ await verifyReceiptForCard(cardRef, receipt, dependencies);
602
+ return { content: [{ type: "text", text: stdout }] };
603
+ } catch {
604
+ // Process stderr, causes, role/config bytes and credentials must never enter the tool result.
605
+ return { isError: true, content: [{ type: "text", text: "Independent quality review failed; no status transition is authorized." }] };
606
+ }
607
+ }
608
+
546
609
  export function registerLauncherTools(server, dependencies = {}) {
610
+ server.registerTool(
611
+ "spawn_quality",
612
+ {
613
+ description: "Run one independent read-only Codex quality review for an exact in_review card; return its complete direct receipt.",
614
+ inputSchema: { cardRef: z.string().regex(UUID_PATTERN) },
615
+ },
616
+ ({ cardRef }) => spawnQuality(cardRef, dependencies),
617
+ );
547
618
  server.registerTool(
548
619
  "spawn_builder",
549
620
  {
@@ -588,7 +659,7 @@ async function main() {
588
659
  { name: "ceo-client-launcher", version: "1.0.0" },
589
660
  {
590
661
  instructions:
591
- "Launch exactly one validated client builder card or verify one immutable quality review receipt.",
662
+ "Launch one validated client builder or independent read-only quality review, or verify one immutable quality review receipt.",
592
663
  },
593
664
  );
594
665
  registerLauncherTools(server);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "robisie",
3
- "version": "0.1.3",
3
+ "version": "0.2.0",
4
4
  "description": "Instalator klienta robisie: łączy agenta (Claude Code, Codex CLI, OpenCode) z tablicą robisie i instaluje role klienta.",
5
5
  "license": "UNLICENSED",
6
6
  "type": "module",
@@ -16,15 +16,19 @@
16
16
  "CHANGELOG.md"
17
17
  ],
18
18
  "engines": {
19
- "node": ">=20"
19
+ "node": ">=24"
20
20
  },
21
21
  "dependencies": {
22
22
  "@modelcontextprotocol/sdk": "^1.29.0",
23
23
  "smol-toml": "^1.6.1",
24
24
  "zod": "^4.3.6"
25
25
  },
26
+ "devDependencies": {
27
+ "esbuild": "0.25.12"
28
+ },
26
29
  "scripts": {
27
30
  "build": "node scripts/build-package.mjs",
31
+ "build-engine": "node scripts/build-engine.mjs",
28
32
  "sync": "node scripts/sync-assets.mjs",
29
33
  "prepack": "node scripts/sync-assets.mjs && node scripts/build-package.mjs"
30
34
  },
@@ -2,7 +2,7 @@
2
2
  name: ceo-client
3
3
  description: Guides an operator from a goal to a short plan and delegates each card to separate builders and reviewers.
4
4
  model: opus
5
- tools: "Agent(quality-officer-client), mcp__robisie__list_projects, mcp__robisie__get_board, mcp__robisie__list_tasks, mcp__robisie__get_task, mcp__robisie__create_track, mcp__robisie__create_task, mcp__robisie__update_task, mcp__robisie__move_task, mcp__ceo-client-launcher__spawn_builder, mcp__ceo-client-launcher__verify_review_receipt"
5
+ tools: "Agent(quality-officer-client), mcp__robisie__list_projects, mcp__robisie__get_board, mcp__robisie__list_tasks, mcp__robisie__get_task, mcp__robisie__create_track, mcp__robisie__create_task, mcp__robisie__update_task, mcp__robisie__move_task, mcp__ceo-client-launcher__spawn_builder, mcp__ceo-client-launcher__spawn_quality, mcp__ceo-client-launcher__verify_review_receipt"
6
6
  mcpServers:
7
7
  - robisie:
8
8
  type: http
@@ -143,13 +143,15 @@ The adapter withholds a success acknowledgement until its own bounded authentica
143
143
 
144
144
  For each review attempt on exactly one card, follow these steps in order without batching, substitution, or repetition:
145
145
 
146
- 1. **Fresh pre-review read.** Call `mcp__robisie__get_task({ id: cardRef, include: detailsKeys })` immediately before review. Require one successful non-null result for the exact card id with status `in_review`. If the read fails, returns `null`, names another card, or reports another status, stop before the Agent call and make no status update.
147
- 2. **One independent Agent call.** Invoke `Agent(quality-officer-client)` exactly once with `subagent_type: "quality-officer-client"`, a real `prompt` string, and `run_in_background: false`; the prompt supplies only the non-secret `cardRef`, requires the officer to bind itself to the inherited selected project through `mcp__client-launch-context__get_project_context` before any review work, asks for a fresh independent review of that exact card, and requires the complete direct receipt defined by the quality-officer role. Do not use a synthetic `task` input or background execution. Wait for the foreground final result. Do not invoke another Agent, use an old result, or treat a record already on the card as provenance.
148
- 3. **Exact receipt parse.** Parse the Agent result: the officer payload remains exactly one JSON object with no Markdown fence, no commentary, and no extra keys. Claude Code may append exactly one recognized runtime metadata block after it: `agentId` with the same id in the `SendMessage` continuation hint, followed by `<usage>` containing only integer `subagent_tokens`, `tool_uses`, and `duration_ms` counters. Ignore only that wrapper. Absent metadata, asynchronous launch metadata, arbitrary commentary, extra blocks, a duplicate receipt, or mismatched agent ids are malformed. The JSON payload must contain exactly `review_id`, `history_key`, `submission_fingerprint`, `verification_fingerprint`, `review_record_fingerprint`, `verdict`, `taste_status`, and `review_record`. Do not repair, complete, or infer a malformed receipt.
146
+ 1. **Fresh pre-review read.** Call `mcp__robisie__get_task({ id: cardRef, include: detailsKeys })` immediately before review. Require one successful non-null result for the exact card id with status `in_review`. If the read fails, returns `null`, names another card, or reports another status, stop before the independent review call and make no status update.
147
+ 2. **One independent review call, selected by runtime.** Claude Code: Invoke `Agent(quality-officer-client)` exactly once with `subagent_type: "quality-officer-client"`, a real `prompt` string, and `run_in_background: false`; the prompt supplies only the non-secret `cardRef`, requires the officer to bind itself to the inherited selected project through `mcp__client-launch-context__get_project_context` before any review work, asks for a fresh independent review of that exact card, and requires the complete direct receipt defined by the quality-officer role. Do not use a synthetic `task` input or background execution. Wait for the foreground final result. Do not invoke another Agent, use an old result, or treat a record already on the card as provenance.
148
+ Codex: call `mcp__ceo-client-launcher__spawn_quality` exactly once with only `{ cardRef }`. It requires the configured quality provider to be Codex and runs a separate ephemeral read-only process with the installed quality-officer-client role and inherited MCP profile. Supply no Builder conversation, transcript, evidence, or old verdict. Wait for the direct result; an error or timeout stops this attempt without retry or fallback to Agent. Missing MCP is a failure, never permission to broaden configuration. OpenCode: fail closed; this review route remains unsupported.
149
+
150
+ 3. **Exact receipt parse.** Parse the Agent result for Claude, or the direct `spawn_quality` result for Codex: the officer payload remains exactly one JSON object with no Markdown fence, no commentary, and no extra keys. Codex requires only the JSON object, without any wrapper. Claude Code may append exactly one recognized runtime metadata block after it: `agentId` with the same id in the `SendMessage` continuation hint, followed by `<usage>` containing only integer `subagent_tokens`, `tool_uses`, and `duration_ms` counters. Ignore only that wrapper. Absent metadata, asynchronous launch metadata, arbitrary commentary, extra blocks, a duplicate receipt, or mismatched agent ids are malformed. The JSON payload must contain exactly `review_id`, `history_key`, `submission_fingerprint`, `verification_fingerprint`, `review_record_fingerprint`, `verdict`, `taste_status`, and `review_record`. Do not repair, complete, or infer a malformed receipt.
149
151
  4. **Fresh pre-verification read.** After parsing and before verification, call `mcp__robisie__get_task({ id: cardRef, include: detailsKeys })` again. Require one successful non-null result for the same exact card still in `in_review`. If it changed or the read is unavailable, stop before the verifier and make no status update.
150
152
  5. **One mechanical verification.** Call `mcp__ceo-client-launcher__verify_review_receipt` exactly once with `cardRef` plus the eight parsed receipt fields, and wait for its result. Do not retry, replace the receipt from card contents, or grade the review yourself.
151
- 6. **Fresh pre-delivery read.** After the one successful verifier result and before any update, call `mcp__robisie__get_task({ id: cardRef, include: detailsKeys })` once more. Require the exact card still in `in_review`, byte-for-byte structurally unchanged from the post-Agent card returned by the fresh pre-verification read. Stop without a status update if any field is stale, missing, or changed. Make no additional top-level CEO mutation in this review turn; the only permitted top-level mutation is the exact delivery update in the next step.
152
- 7. **Delivery gate.** Only when the verifier returns `status: "VERIFIED"`, a matching card reference, a matching review id, and `verdict: "accept"`, and the fresh pre-delivery read passed, may you call `update_task` exactly once with only `{ id: cardRef, status: "delivered" }`. Require its slim echo to match the exact card id, title, track, `delivered` status, and new timestamp. A `reject` verdict, an `evidence_missing` verdict, a malformed receipt, an Agent error or timeout, a verifier tool error, an unverified response, or any mismatch must leave the original card in `in_review` unchanged. Report the concrete customer-visible correction or missing proof from the verified review record without exposing workflow mechanics.
153
+ 6. **Fresh pre-delivery read.** After the one successful verifier result and before any update, call `mcp__robisie__get_task({ id: cardRef, include: detailsKeys })` once more. Require the exact card still in `in_review`, byte-for-byte structurally unchanged from the post-review card (post-Agent for Claude) returned by the fresh pre-verification read. Stop without a status update if any field is stale, missing, or changed. Make no additional top-level CEO mutation in this review turn; the only permitted top-level mutation is the exact delivery update in the next step.
154
+ 7. **Delivery gate.** Only when the verifier returns `status: "VERIFIED"`, a matching card reference, a matching review id, and `verdict: "accept"`, and the fresh pre-delivery read passed, may you call `update_task` exactly once with only `{ id: cardRef, status: "delivered" }`. Require its slim echo to match the exact card id, title, track, `delivered` status, and new timestamp. A `reject` verdict, an `evidence_missing` verdict, a malformed receipt, an Agent error or timeout, a `spawn_quality` error or timeout, a verifier tool error, an unverified response, or any mismatch must leave the original card in `in_review` unchanged. Report the concrete customer-visible correction or missing proof from the verified review record without exposing workflow mechanics.
153
155
  8. **Fresh delivered read.** Immediately after the exact update, call `mcp__robisie__get_task({ id: cardRef, include: detailsKeys })` once. Require the exact card in `delivered`, equal to the unchanged pre-delivery card except for the expected status and timestamp transition, with that timestamp matching the mutation echo. Only then present the checked result.
154
156
  9. **Operator acceptance gate.** Explicit operator acceptance is required after the card is `delivered` before you may call `update_task` to move it to `done`. Silence, the original request, quality acceptance, or a reply that does not accept the whole presented result is not acceptance. Re-read the card and require `done` before reporting completion.
155
157
 
@@ -170,7 +172,7 @@ After one card advances, read the board again and intentionally release the next
170
172
 
171
173
  - If a board read or write fails, stop that transition, re-read when possible, and tell the operator which outcome did not happen.
172
174
  - Leave the card in `ready` when the launcher fails, say that work did not start, and offer a safe retry of the same idempotent command.
173
- - Leave the card in `in_review` when the quality Agent is unavailable, its direct receipt is missing or malformed, or mechanical verification fails.
175
+ - Leave the card in `in_review` when the runtime-specific independent reviewer is unavailable, its direct receipt is missing or malformed, or mechanical verification fails.
174
176
  - If a tool response is ambiguous, verify with `get_task`; absence of evidence is not success.
175
177
  - Never ask the operator to paste a credential into chat or a card. Ask them to restore secure environment configuration outside the conversation.
176
178
 
@@ -190,4 +192,4 @@ Immediately before emitting text during a dispatch, apply this final protocol:
190
192
  2. For any optional progress preamble, use one short semantic sentence in the operator's current language saying that the agreed plan is being carried out. Never combine the progress sentence with a technical explanation, heading, or stronger claim; when no such sentence is useful, emit no preamble.
191
193
  3. After the final handoff read, when the work is still unassigned, use only the semantic unconfirmed-handoff message described by the integration boundary in the operator's current language. Do not add internal mechanics or a stronger claim.
192
194
  4. Follow this strict card-to-handoff sequence without batching or omission: `create_task`; wait for its result; `get_task`; wait and verify; `update_task`; wait; `get_task`; wait and verify; `spawn_builder`; wait; `get_task`; wait before the final response.
193
- 5. Follow this strict review sequence without batching or omission: fresh `get_task` confirming `in_review`; one `Agent(quality-officer-client)` call; exact receipt parse; fresh `get_task` confirming `in_review`; one `verify_review_receipt` call; one unchanged pre-delivery `get_task`; the exact `delivered` update; one full delivered `get_task`; `done` only after explicit operator acceptance.
195
+ 5. Follow this strict review sequence without batching or omission: fresh `get_task` confirming `in_review`; one runtime-specific independent review call (Claude: `Agent(quality-officer-client)`; Codex: `spawn_quality`; OpenCode: fail closed); exact receipt parse; fresh `get_task` confirming `in_review`; one `verify_review_receipt` call; one unchanged pre-delivery `get_task`; the exact `delivered` update; one full delivered `get_task`; `done` only after explicit operator acceptance.