robisie 0.1.4 → 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 (47) hide show
  1. package/CHANGELOG.md +13 -0
  2. package/README.md +39 -11
  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/planer-client.d.ts +45 -4
  33. package/dist/planer-client.js +120 -14
  34. package/dist/roles.d.ts +1 -1
  35. package/dist/select-fingerprint.d.ts +19 -0
  36. package/dist/select-fingerprint.js +46 -0
  37. package/dist/test-report.d.ts +9 -0
  38. package/dist/test-report.js +139 -0
  39. package/dist/tester-result-reader.d.ts +87 -0
  40. package/dist/tester-result-reader.js +122 -0
  41. package/docs/ENGINE-API.md +9 -1
  42. package/docs/README.en.md +55 -16
  43. package/docs/README.md +53 -16
  44. package/docs/RELEASE-0.1.0.md +27 -5
  45. package/helpers/ceo-client-launcher-mcp.mjs +76 -5
  46. package/package.json +6 -2
  47. package/roles/ceo-client.md +10 -8
@@ -0,0 +1,19 @@
1
+ export declare function selectFingerprint(model: string, prompt: string): string;
2
+ export declare function readSelectFingerprint(file: string): string | null;
3
+ export declare function writeSelectFingerprint(file: string, fingerprint: string): void;
4
+ export declare function askUnlessUnchanged<T>(opts: {
5
+ model: string;
6
+ prompt: string;
7
+ file: string;
8
+ force: boolean;
9
+ ask: (prompt: string) => Promise<T>;
10
+ log: (line: string) => void;
11
+ }): Promise<{
12
+ skipped: true;
13
+ fingerprint: string;
14
+ } | {
15
+ skipped: false;
16
+ fingerprint: string;
17
+ value: T;
18
+ commit: () => void;
19
+ }>;
@@ -0,0 +1,46 @@
1
+ import { createHash } from "node:crypto";
2
+ import { readFileSync, renameSync, unlinkSync, writeFileSync } from "node:fs";
3
+ export function selectFingerprint(model, prompt) {
4
+ return createHash("sha256").update(`${model}\n${prompt}`).digest("hex");
5
+ }
6
+ export function readSelectFingerprint(file) {
7
+ try {
8
+ return readFileSync(file, "utf8").trim();
9
+ }
10
+ catch (error) {
11
+ if (error.code === "ENOENT")
12
+ return null;
13
+ throw error;
14
+ }
15
+ }
16
+ export function writeSelectFingerprint(file, fingerprint) {
17
+ const temporary = `${file}.${process.pid}.tmp`;
18
+ try {
19
+ writeFileSync(temporary, fingerprint);
20
+ renameSync(temporary, file);
21
+ }
22
+ catch (error) {
23
+ try {
24
+ unlinkSync(temporary);
25
+ }
26
+ catch (cleanupError) {
27
+ if (cleanupError.code !== "ENOENT")
28
+ throw cleanupError;
29
+ }
30
+ throw error;
31
+ }
32
+ }
33
+ export async function askUnlessUnchanged(opts) {
34
+ const fingerprint = selectFingerprint(opts.model, opts.prompt);
35
+ if (!opts.force && readSelectFingerprint(opts.file) === fingerprint) {
36
+ opts.log(`selector: skip — input unchanged (fingerprint ${fingerprint})`);
37
+ return { skipped: true, fingerprint };
38
+ }
39
+ const value = await opts.ask(opts.prompt);
40
+ return {
41
+ skipped: false,
42
+ fingerprint,
43
+ value,
44
+ commit: () => writeSelectFingerprint(opts.file, fingerprint),
45
+ };
46
+ }
@@ -0,0 +1,9 @@
1
+ export declare function passedVitestReport(value: unknown, evidence?: {
2
+ root: string;
3
+ paths: string[];
4
+ skipped: string[];
5
+ reason: string;
6
+ testNamePattern?: RegExp;
7
+ }): boolean;
8
+ export declare function vitestReportPath(name: unknown, root: string): string | null;
9
+ export declare function timeoutVitestFiles(value: unknown, root: string): string[] | null;
@@ -0,0 +1,139 @@
1
+ import { posix } from "node:path";
2
+ import path from "node:path";
3
+ export function passedVitestReport(value, evidence) {
4
+ const r = asRecord(value);
5
+ if (r.success !== true || !positiveInteger(r.numTotalTestSuites) || !positiveInteger(r.numTotalTests) || r.numFailedTests !== 0 || !Number.isSafeInteger(r.numPendingTests) || Number(r.numPendingTests) < 0
6
+ || r.numTodoTests !== 0 || r.numFailedTestSuites !== 0 || r.numPendingTestSuites !== 0
7
+ || !Number.isSafeInteger(r.numPassedTests) || Number(r.numPassedTests) < 0 || Number(r.numPassedTests) + Number(r.numPendingTests) !== r.numTotalTests || r.numPassedTestSuites !== r.numTotalTestSuites
8
+ || !Array.isArray(r.testResults) || !r.testResults.length)
9
+ return false;
10
+ let count = 0, filtered = 0;
11
+ const skipped = [];
12
+ const valid = r.testResults.every(v => {
13
+ const f = asRecord(v);
14
+ if (!nonempty(f.name) || f.status !== "passed" || f.message !== "" || !Array.isArray(f.assertionResults))
15
+ return false;
16
+ const name = f.name;
17
+ return f.assertionResults.every(v => {
18
+ const t = asRecord(v);
19
+ count++;
20
+ if (!Array.isArray(t.failureMessages) || t.failureMessages.length)
21
+ return false;
22
+ if (t.status === "passed")
23
+ return true;
24
+ if (t.status !== "skipped" || !nonempty(t.fullName) || !evidence?.paths.length)
25
+ return false;
26
+ const rel = posix.relative(evidence.root, path.resolve(evidence.root, name));
27
+ if (!rel || rel.startsWith("../"))
28
+ return false;
29
+ // Vitest's JSON reporter omits the final separator for an empty test title.
30
+ const fullName = t.title === "" ? `${t.fullName} ` : t.fullName;
31
+ if (evidence.testNamePattern && !evidence.testNamePattern.test(fullName)) {
32
+ filtered++;
33
+ return true;
34
+ }
35
+ const identity = JSON.stringify([rel, t.fullName]);
36
+ if (scopesOverlap([rel], evidence.paths)) {
37
+ evidence.reason = `Pominięcie w zakresie karty: ${identity}`;
38
+ return false;
39
+ }
40
+ skipped.push(identity);
41
+ return true;
42
+ });
43
+ }) && count === r.numTotalTests && skipped.length + filtered === r.numPendingTests;
44
+ if (valid && filtered > 0 && r.numPassedTests === 0 && evidence) {
45
+ evidence.reason = "Filtr nazwy nie wybrał żadnego testu";
46
+ return false;
47
+ }
48
+ if (valid)
49
+ evidence?.skipped.push(...skipped);
50
+ return valid;
51
+ }
52
+ export function vitestReportPath(name, root) {
53
+ if (!nonempty(name) || /[\r\n\0\\]/.test(name) || name.split("/").includes(".."))
54
+ return null;
55
+ const rel = path.relative(root, path.resolve(root, name));
56
+ return rel && !rel.startsWith("-") && !rel.startsWith("../") && !path.isAbsolute(rel) ? rel : null;
57
+ }
58
+ export function timeoutVitestFiles(value, root) {
59
+ const report = asRecord(value);
60
+ const counts = ["numTotalTests", "numPassedTests", "numFailedTests", "numPendingTests", "numTodoTests",
61
+ "numTotalTestSuites", "numPassedTestSuites", "numFailedTestSuites", "numPendingTestSuites"];
62
+ if (!counts.every(k => Number.isSafeInteger(report[k]) && Number(report[k]) >= 0)
63
+ || !positiveInteger(report.numTotalTests) || !positiveInteger(report.numFailedTestSuites)
64
+ || report.success !== false || report.numPendingTestSuites !== 0
65
+ || Number(report.numTotalTests) !== Number(report.numPassedTests) + Number(report.numFailedTests) + Number(report.numPendingTests) + Number(report.numTodoTests)
66
+ || Number(report.numTotalTestSuites) !== Number(report.numPassedTestSuites) + Number(report.numFailedTestSuites)
67
+ || !Array.isArray(report.testResults) || !report.testResults.length)
68
+ return null;
69
+ const timeout = (message, duration) => typeof message === "string" && (/^(?:Error: )?(?:Test|Hook) timed out in \d+ms\.(?:\s|$)/.test(message)
70
+ || message.split(/\r?\n/, 1)[0] === "Error: STACK_TRACE_ERROR"
71
+ && typeof duration === "number" && Number.isFinite(duration) && duration >= 30_000);
72
+ if (report.numRuntimeErrorTestSuites != null && report.numRuntimeErrorTestSuites !== 0
73
+ || report.unhandledErrors != null && (!Array.isArray(report.unhandledErrors) || report.unhandledErrors.length))
74
+ return null;
75
+ const paths = [];
76
+ const seen = new Set();
77
+ let failed = 0, passed = 0, pending = 0, todo = 0, total = 0, failedFiles = 0;
78
+ for (const entry of report.testResults) {
79
+ const file = asRecord(entry);
80
+ if (!nonempty(file.name) || !Array.isArray(file.assertionResults) || !["passed", "failed"].includes(String(file.status)))
81
+ return null;
82
+ const rel = vitestReportPath(file.name, root);
83
+ if (!rel || seen.has(rel) || !file.assertionResults.length)
84
+ return null;
85
+ seen.add(rel);
86
+ let red = false;
87
+ if (file.message !== "") {
88
+ if (!timeout(file.message, file.duration))
89
+ return null;
90
+ red = true;
91
+ }
92
+ for (const item of file.assertionResults) {
93
+ const test = asRecord(item);
94
+ total++;
95
+ if (!["passed", "failed", "skipped", "pending", "todo"].includes(String(test.status)))
96
+ return null;
97
+ if (test.status === "failed") {
98
+ failed++;
99
+ red = true;
100
+ if (!Array.isArray(test.failureMessages) || !test.failureMessages.length || !test.failureMessages.every(message => timeout(message, test.duration)))
101
+ return null;
102
+ }
103
+ else {
104
+ if (!Array.isArray(test.failureMessages) || test.failureMessages.length)
105
+ return null;
106
+ if (test.status === "passed")
107
+ passed++;
108
+ else if (test.status === "todo")
109
+ todo++;
110
+ else
111
+ pending++;
112
+ }
113
+ }
114
+ if ((file.status === "failed") !== red)
115
+ return null;
116
+ if (red) {
117
+ failedFiles++;
118
+ paths.push(rel);
119
+ }
120
+ }
121
+ return paths.length && total === report.numTotalTests && failed === report.numFailedTests
122
+ && passed === report.numPassedTests && pending === report.numPendingTests && todo === report.numTodoTests
123
+ && Number(report.numFailedTestSuites) >= failedFiles && Number(report.numPassedTestSuites) >= seen.size - failedFiles ? paths : null;
124
+ }
125
+ function scopesOverlap(a, b) {
126
+ return a.some(x => b.some(y => x === "." || y === "." || x === y || x.startsWith(`${y}/`) || y.startsWith(`${x}/`)));
127
+ }
128
+ function record(value) {
129
+ return value !== null && typeof value === "object" && !Array.isArray(value);
130
+ }
131
+ function asRecord(value) {
132
+ return record(value) ? value : {};
133
+ }
134
+ function positiveInteger(value) {
135
+ return typeof value === "number" && Number.isSafeInteger(value) && value > 0;
136
+ }
137
+ function nonempty(value) {
138
+ return typeof value === "string" && value.trim().length > 0;
139
+ }
@@ -0,0 +1,87 @@
1
+ export type CardLike = {
2
+ id: string;
3
+ title: string;
4
+ status?: string | null;
5
+ details?: Record<string, unknown> | null;
6
+ };
7
+ export type TesterExecution = {
8
+ sha: string;
9
+ at: string;
10
+ commands: string[];
11
+ reversible: boolean;
12
+ notLanded: boolean;
13
+ base: string | null;
14
+ failed: {
15
+ command: string;
16
+ output: string;
17
+ } | null;
18
+ testedHead: string;
19
+ incomplete: boolean;
20
+ timeoutPaths: string[];
21
+ skippedTests: string[];
22
+ transcript: string;
23
+ retest?: TesterRetestGrant | null;
24
+ baselineFailures?: {
25
+ command: string;
26
+ sha: string;
27
+ tests: string[];
28
+ ref: string;
29
+ }[];
30
+ };
31
+ export declare function validTestSha(value: unknown): value is string;
32
+ export declare function landedSha(card: CardLike): string | null;
33
+ export declare const AUTOMATIC_TESTER_RETEST_DECISION = "automat TESTER-RETEST-POZA-ZAKRESEM (DL S-TESTER-RETEST)";
34
+ export declare function isRecord(value: unknown): value is Record<string, unknown>;
35
+ export type TesterRetestGrant = {
36
+ sha: string;
37
+ at: string;
38
+ reason: string;
39
+ decision: string;
40
+ };
41
+ export type TesterHistoricalRecovery = {
42
+ recovery: "missing-report" | "missing-json" | "legacy-times" | "legacy-base" | "foreign-report";
43
+ };
44
+ export type TesterQualification = TesterRetestGrant | TesterHistoricalRecovery | null;
45
+ export type TesterQualifications = {
46
+ qualifications: TesterQualification[];
47
+ };
48
+ export type TesterJobInput = {
49
+ card: CardLike;
50
+ runtime: string;
51
+ qualify?: CardLike[];
52
+ };
53
+ export type Packet = {
54
+ version: 1;
55
+ id: string;
56
+ input: TesterJobInput;
57
+ };
58
+ export type TesterCompletion = Packet & {
59
+ result?: TesterExecution;
60
+ qualifications?: TesterQualification[];
61
+ error?: string;
62
+ };
63
+ export type Poll = {
64
+ kind: "idle";
65
+ } | {
66
+ kind: "running";
67
+ pid: number;
68
+ } | {
69
+ kind: "complete";
70
+ completion: TesterCompletion;
71
+ } | {
72
+ kind: "failed";
73
+ id: string;
74
+ error: string;
75
+ };
76
+ export declare const files: (dir: string) => {
77
+ lock: string;
78
+ input: string;
79
+ result: string;
80
+ };
81
+ export declare const record: (value: unknown) => Record<string, unknown>;
82
+ export declare function readJson(file: string): unknown;
83
+ export declare function packet(value: unknown): Packet;
84
+ export declare function retestGrant(value: unknown, card: CardLike): TesterRetestGrant | null;
85
+ export declare function qualifications(value: unknown, input: TesterJobInput): TesterQualification[];
86
+ export declare function execution(value: unknown, input: TesterJobInput): TesterExecution;
87
+ export declare function readTesterJob(dir: string): Poll;
@@ -0,0 +1,122 @@
1
+ import { readFileSync, existsSync } from "node:fs";
2
+ import { isDeepStrictEqual } from "node:util";
3
+ import path from "node:path";
4
+ export function validTestSha(value) {
5
+ return typeof value === "string" && /^[a-f0-9]{7,40}$/i.test(value);
6
+ }
7
+ export function landedSha(card) {
8
+ const landed = card.details?.landed;
9
+ return isRecord(landed) && validTestSha(landed.sha) ? landed.sha : null;
10
+ }
11
+ export const AUTOMATIC_TESTER_RETEST_DECISION = "automat TESTER-RETEST-POZA-ZAKRESEM (DL S-TESTER-RETEST)";
12
+ export function isRecord(value) {
13
+ return value !== null && typeof value === "object" && !Array.isArray(value);
14
+ }
15
+ export const files = (dir) => ({ lock: path.join(dir, ".tester-job.lock"), input: path.join(dir, ".tester-job.input.json"), result: path.join(dir, ".tester-job.result.json") });
16
+ export const record = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
17
+ export function readJson(file) {
18
+ try {
19
+ if (!existsSync(file))
20
+ return undefined;
21
+ return JSON.parse(readFileSync(file, "utf8"));
22
+ }
23
+ catch (error) {
24
+ if (error.code === "ENOENT")
25
+ return undefined;
26
+ throw error;
27
+ }
28
+ }
29
+ export function packet(value) {
30
+ const p = record(value), input = record(p.input), card = record(input.card);
31
+ if (p.version !== 1 || typeof p.id !== "string" || !p.id || typeof input.runtime !== "string"
32
+ || typeof card.id !== "string" || !card.id || !["delivered", "blocked"].includes(String(card.status))
33
+ || !validTestSha(landedSha(card)))
34
+ throw new Error("Niepoprawna tożsamość joba testera");
35
+ if (input.qualify !== undefined && (!Array.isArray(input.qualify) || !input.qualify.length
36
+ || !isDeepStrictEqual(input.qualify[0], input.card)
37
+ || new Set(input.qualify.map(c => record(c).id)).size !== input.qualify.length
38
+ || input.qualify.some(c => {
39
+ const row = record(c), details = record(row.details), test = record(details.test);
40
+ return typeof row.id !== "string" || !row.id || row.status !== "blocked" || details.retest != null
41
+ || !validTestSha(landedSha(row)) || test.verdict !== "FAIL" || test.sha !== landedSha(row);
42
+ })))
43
+ throw new Error("Niepoprawne snapshoty kwalifikacji testera");
44
+ return value;
45
+ }
46
+ export function retestGrant(value, card) {
47
+ if (value === null)
48
+ return null;
49
+ const grant = record(value), test = record(card.details?.test);
50
+ if (grant.sha !== landedSha(card) || grant.decision !== AUTOMATIC_TESTER_RETEST_DECISION
51
+ || typeof grant.reason !== "string" || !grant.reason.trim() || typeof grant.at !== "string"
52
+ || !Number.isFinite(Date.parse(grant.at)) || !Number.isFinite(Date.parse(String(test.at)))
53
+ || Date.parse(grant.at) <= Date.parse(String(test.at)))
54
+ throw new Error("Niepoprawny grant testera");
55
+ return value;
56
+ }
57
+ export function qualifications(value, input) {
58
+ if (!input.qualify || !Array.isArray(value) || value.length !== input.qualify.length)
59
+ throw new Error("Niepełny wynik kwalifikacji testera");
60
+ return value.map((grant, index) => {
61
+ if (record(grant).recovery !== undefined) {
62
+ const recovery = record(grant).recovery;
63
+ if (Object.keys(record(grant)).length === 1)
64
+ switch (recovery) {
65
+ case "missing-report":
66
+ case "missing-json":
67
+ case "legacy-times":
68
+ case "legacy-base":
69
+ case "foreign-report": return { recovery };
70
+ }
71
+ throw new Error("Niepoprawna kwalifikacja historycznej próby testera");
72
+ }
73
+ return retestGrant(grant, input.qualify[index]);
74
+ });
75
+ }
76
+ export function execution(value, input) {
77
+ const r = record(value), strings = (v) => Array.isArray(v) && v.every(x => typeof x === "string");
78
+ const failed = record(r.failed);
79
+ if (r.sha !== landedSha(input.card) || typeof r.at !== "string" || !Number.isFinite(Date.parse(r.at))
80
+ || !strings(r.commands) || !strings(r.timeoutPaths) || !strings(r.skippedTests)
81
+ || typeof r.transcript !== "string" || typeof r.reversible !== "boolean" || typeof r.notLanded !== "boolean" || typeof r.incomplete !== "boolean"
82
+ || !(r.base === null || validTestSha(r.base)) || !(r.testedHead === "UNKNOWN" || validTestSha(r.testedHead))
83
+ || !(r.failed === null || (typeof failed.command === "string" && typeof failed.output === "string")))
84
+ throw new Error("Niepoprawny wynik joba testera");
85
+ if (r.retest !== undefined)
86
+ retestGrant(r.retest, { ...input.card, details: { ...input.card.details, test: { at: r.at } } });
87
+ return value;
88
+ }
89
+ export function readTesterJob(dir) {
90
+ const f = files(dir), raw = readJson(f.lock);
91
+ if (raw === undefined) {
92
+ if (readJson(f.result) !== undefined || readJson(f.input) !== undefined)
93
+ throw new Error("Osierocony wynik testera bez locka — HOLD");
94
+ return { kind: "idle" };
95
+ }
96
+ const lock = record(raw);
97
+ if (typeof lock.id !== "string" || !Number.isSafeInteger(lock.pid) || Number(lock.pid) <= 0
98
+ || typeof lock.starting !== "boolean" || typeof lock.createdAt !== "number")
99
+ throw new Error("Nieczytelny lock testera — HOLD");
100
+ const result = readJson(f.result);
101
+ if (result !== undefined) {
102
+ const completed = packet(result), original = packet(readJson(f.input));
103
+ if (completed.id !== lock.id || !isDeepStrictEqual(original, { version: completed.version, id: completed.id, input: completed.input }))
104
+ throw new Error("Obcy wynik testera — HOLD");
105
+ const error = record(result).error;
106
+ if (typeof error === "string" && error)
107
+ return { kind: "complete", completion: { ...completed, error } };
108
+ if (completed.input.qualify)
109
+ return { kind: "complete", completion: { ...completed, qualifications: qualifications(record(result).qualifications, completed.input) } };
110
+ return { kind: "complete", completion: { ...completed, result: execution(record(result).result, completed.input) } };
111
+ }
112
+ try {
113
+ process.kill(Number(lock.pid), 0);
114
+ }
115
+ catch (error) {
116
+ if (error.code !== "ESRCH")
117
+ return { kind: "running", pid: Number(lock.pid) }; // EPERM is not proof of death.
118
+ if (!lock.starting || Date.now() - lock.createdAt > 30_000)
119
+ return { kind: "failed", id: lock.id, error: "Tester zakończył się bez pliku wyniku" };
120
+ }
121
+ return { kind: "running", pid: Number(lock.pid) };
122
+ }
@@ -85,4 +85,12 @@ Serwer stosuje **płytki merge**: patch zastępuje całą wartość pod wskazany
85
85
 
86
86
  Osobna operacja `updateTask({ id, status: 'ready', expected: { status: 'draft' } })` przekazuje warunek oczekiwanego statusu. Warunek, przejście statusu i uprawnienia rozstrzyga serwer; SDK nie implementuje własnego CAS. Powyższe przykłady nie wykonują update.
87
87
 
88
- SDK nie tworzy projektu ani karty, nie nadaje uprawnień, nie dowodzi odbioru `done` i nie uruchamia silnika. Potwierdzenie append nie jest dowodem wykonania zadania ani niezależnej recenzji. Role, odbiór i uruchomienie pracy wymagają ich własnych kontraktów.
88
+ ## Operacje silnika
89
+
90
+ Te operacje działają już na kontrakcie `1.0.0`: karta z `getTask`/`listTasks` zawiera też `updatedAt`, `createdAt` i `specRef`; `moveTask({ id, trackId })` przenosi kartę (podaj co najmniej jedno z `trackId`, `afterId`, `beforeId`); `createTrack` i `createTask` tworzą tor i kartę na jawne polecenie callera.
91
+
92
+ ### Wymagają kontraktu serwera ≥ 1.1.0
93
+
94
+ Tylko trzy operacje wymagają serwera z kontraktem co najmniej `1.1.0`: `updateTask` z `expected.details` lub `detailsPatch`, `appendDetailIf({ id, patch, expected: { key, value?, status?, details? } })` oraz `writeDecisionMatter({ id, matterId, patch, expected? })`. Starszy serwer po cichu pominąłby nieznane pola i zapisałby bez warunku, dlatego SDK odmawia lokalnie, przed wysłaniem, błędem `UNSUPPORTED_CONTRACT` (`uncertain === false`). `appendDetailIf` zwraca `{ applied: false }` tylko przy jawnym konflikcie tej karty; brak `value` oznacza „klucza nie ma”, a `value: null` literalne `null`. `writeDecisionMatter` zwraca zapisany stan sprawy (także gdy serwer odmówił zmiany) albo `null`; caller sam go porównuje. Żadna z tych operacji nie ponawia zapisu.
95
+
96
+ SDK nie tworzy projektu; tor i kartę tworzy wyłącznie jawne wywołanie `createTrack`/`createTask` przez callera. SDK nie nadaje uprawnień, nie dowodzi odbioru `done` i nie uruchamia silnika. Potwierdzenie append nie jest dowodem wykonania zadania ani niezależnej recenzji. Role, odbiór i uruchomienie pracy wymagają ich własnych kontraktów.
package/docs/README.en.md CHANGED
@@ -1,4 +1,4 @@
1
- # robisie — from account to accepted card (package 0.1.4)
1
+ # robisie — from account to accepted card (package 0.2.0)
2
2
 
3
3
  Polski: [README.md](README.md).
4
4
 
@@ -15,7 +15,7 @@ If the registry README is empty, use the guides shipped locally at `node_modules
15
15
  <a id="wymagania"></a>
16
16
  ## Requirements
17
17
 
18
- The human prepares Node.js 20+, npm, internet for dependencies and robisie, and one provider program: Claude Code, Codex CLI or OpenCode with their own AI access. Check `node --version`, `npm --version` and the chosen program's version (`claude --version`, `codex --version` or `opencode --version`). If absent from PATH, install it following its provider's instructions and check again; a configuration directory alone is insufficient. Windows/WSL are unverified; examples below use POSIX paths.
18
+ The human prepares Node.js 24+ (release used for checks: 24.3.0), npm, internet for dependencies and robisie, and one provider program: Claude Code, Codex CLI or OpenCode with their own AI access. An older Node, such as 22, is refused before `init`, `doctor` and `factory run`. The engine bundled in the package (`dist/engine/tick.cjs`) requires Linux and is started by `npx robisie factory run`; the engine configuration is described in [ENGINE-CONFIG](ENGINE-CONFIG.md). Check `node --version`, `npm --version` and the chosen program's version (`claude --version`, `codex --version` or `opencode --version`). If absent from PATH, install it following its provider's instructions and check again; a configuration directory alone is insufficient. Windows/WSL are unverified; examples below use POSIX paths.
19
19
 
20
20
  Prepare an empty directory on disk. You do not need a website or your own `package.json`; the Node.js step below creates it before installation. This is the agents' working directory, separate from the dashboard project.
21
21
 
@@ -43,7 +43,15 @@ At https://robisie.app/dashboard/connect the human selects `worker` and a recogn
43
43
 
44
44
  `worker` is the minimal path: read, create/update projects, tracks and cards, reserve work; no setting `done` through create/update. `observer` only reads. Explicitly choose `worker` each time: later keys default to `observer` (the first-key screen may preselect worker); do not infer permissions from that default. `full` adds deletion and closing decision matters; `owner_validator` has the same access level as full. `seeder` has narrow access to `get_task` and valid seeding through `append_detail`, without `list_projects`/board reads, so it cannot follow this guide.
45
45
 
46
- The package stores **one key for CEO, Builder and Quality Officer** as `ROBISIE_KEY`. Role names do not change permissions. Do not use full to bypass acceptance of `done`: the owner accepts in the dashboard without broadening the agent's key.
46
+ The package stores **one worker key for CEO, Builder and Quality Officer** as `ROBISIE_KEY`. Role names do not change permissions. Do not use full to bypass acceptance of `done`: the owner accepts in the dashboard without broadening the agent's key.
47
+
48
+ Two distinct keys are required: A (`ROBISIE_KEY`, worker) and B (`ROBISIE_REVIEW_KEY`, owner_validator). At https://robisie.app/dashboard/connect generate a NEW B key, select `owner_validator` and use a label different from A: reusing A's label rotates A. A label does not restrict a key to one project. Supply B outside chat through init's separate hidden prompt or securely prepared ENV; `--key-stdin` reads only A. B ENV takes priority over the saved `review-key` and the prompt; surrounding spaces are invalid. Reinstall reuses saved B when ENV is empty. A nonempty invalid B must be repaired, without falling back to another source.
49
+
50
+ A and B are stored separately in `${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key` and `review-key` (0600 files, 0700 directory). B never enters agent/model configuration, the manifest, arguments, claims or output. Load both environment variables, including with `--no-shell`. Run ordinary `npx robisie doctor` before the first task: `--engine-config` does not check keys. If A is missing or malformed, doctor diagnoses A; B checks begin only when A is present and has a valid format. Missing B, B=A, invalid format or failed B reads produce exit 1. B uses only `initialize` + `list_projects`, with no business-data mutations; auth counters may increase. Successful reads do not confirm role, a shared A/B account or project policy.
51
+
52
+ Every doctor result includes `! Polityka enforced: NIE SPRAWDZONO — klient nie ma API jej odczytu.`: enforced policy: NOT CHECKED — the client has no API to read it. Project-context refusal happens before doctor and has its own advice. Green doctor does not activate enforced. For a B failure check Connect access and issuance as owner_validator; a network failure does not prove revocation. Retry init with correct B ENV, then doctor. Policy changes require a separate authorized operator action.
53
+
54
+ Polish CLI messages: `Brak klucza odbioru ROBISIE_REVIEW_KEY.` — Missing acceptance key ROBISIE_REVIEW_KEY.; `Klucz odbioru B jest tym samym tokenem co klucz A.` — Acceptance key B is the same token as key A.; `ROBISIE_REVIEW_KEY ma niepoprawny format.` — ROBISIE_REVIEW_KEY has an invalid format.; `Nie potwierdzono dostępu B do tablicy.` — Board access with key B could not be confirmed.; `Klucz B uwierzytelnia odczyt projektów.` — Key B authenticates project reads.
47
55
 
48
56
  <!-- sekcja: instalacja -->
49
57
  <a id="instalacja"></a>
@@ -66,17 +74,22 @@ node -e 'try {
66
74
  {
67
75
  set +x
68
76
  npm i robisie &&
69
- unset ROBISIE_KEY &&
77
+ unset ROBISIE_KEY ROBISIE_REVIEW_KEY &&
70
78
  npx robisie init --agent claude &&
71
79
  {
72
80
  if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
73
81
  [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
74
82
  [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
83
+ [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" ] &&
84
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" ] &&
85
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" ] &&
86
+ ROBISIE_REVIEW_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" 2>/dev/null)" &&
87
+ [ -n "$ROBISIE_REVIEW_KEY" ] &&
75
88
  ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
76
89
  [ -n "$ROBISIE_KEY" ]; then
77
- export ROBISIE_KEY
90
+ export ROBISIE_KEY ROBISIE_REVIEW_KEY
78
91
  else
79
- printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
92
+ printf '%s\n' 'Cannot load both nonempty regular readable robisie key files (key, review-key).' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If B is missing or rejected, supply a fresh owner_validator key via ROBISIE_REVIEW_KEY to init; --key-stdin replaces only A. Never paste the key into chat.' >&2
80
93
  false
81
94
  fi
82
95
  } &&
@@ -95,11 +108,16 @@ set +x
95
108
  if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
96
109
  [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
97
110
  [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
111
+ [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" ] &&
112
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" ] &&
113
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" ] &&
114
+ ROBISIE_REVIEW_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" 2>/dev/null)" &&
115
+ [ -n "$ROBISIE_REVIEW_KEY" ] &&
98
116
  ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
99
117
  [ -n "$ROBISIE_KEY" ]; then
100
- export ROBISIE_KEY
118
+ export ROBISIE_KEY ROBISIE_REVIEW_KEY
101
119
  else
102
- printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
120
+ printf '%s\n' 'Cannot load both nonempty regular readable robisie key files (key, review-key).' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If B is missing or rejected, supply a fresh owner_validator key via ROBISIE_REVIEW_KEY to init; --key-stdin replaces only A. Never paste the key into chat.' >&2
103
121
  false
104
122
  fi
105
123
  } &&
@@ -153,11 +171,16 @@ set +x
153
171
  if [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
154
172
  [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
155
173
  [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" ] &&
174
+ [ ! -L "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" ] &&
175
+ [ -f "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" ] &&
176
+ [ -r "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" ] &&
177
+ ROBISIE_REVIEW_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/review-key" 2>/dev/null)" &&
178
+ [ -n "$ROBISIE_REVIEW_KEY" ] &&
156
179
  ROBISIE_KEY="$(cat "${XDG_CONFIG_HOME:-$HOME/.config}/robisie/key" 2>/dev/null)" &&
157
180
  [ -n "$ROBISIE_KEY" ]; then
158
- export ROBISIE_KEY
181
+ export ROBISIE_KEY ROBISIE_REVIEW_KEY
159
182
  else
160
- printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
183
+ printf '%s\n' 'Cannot load both nonempty regular readable robisie key files (key, review-key).' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If B is missing or rejected, supply a fresh owner_validator key via ROBISIE_REVIEW_KEY to init; --key-stdin replaces only A. Never paste the key into chat.' >&2
161
184
  false
162
185
  fi
163
186
  }
@@ -282,6 +305,7 @@ cp -p -- "$PWD/package.json" "$backup/project/package.json"
282
305
  cp -p -- "$PWD/package-lock.json" "$backup/project/package-lock.json"
283
306
  cp -p -- "$PWD/robisie.config.json" "$backup/project/robisie.config.json"
284
307
  cp -p -- "$config_home/robisie/key" "$backup/robisie/key"
308
+ cp -p -- "$config_home/robisie/review-key" "$backup/robisie/review-key"
285
309
  cp -p -- "$config_home/robisie/manifest.json" "$backup/robisie/manifest.json"
286
310
  cp -Rp -- "$config_home/robisie/backups/." "$backup/robisie/backups/"
287
311
  cp -Rp -- "$config_home/robisie/roles/codex/." "$backup/robisie/roles/codex/"
@@ -307,6 +331,7 @@ cp -p -- "$backup/project/package.json" "$PWD/package.json"
307
331
  cp -p -- "$backup/project/package-lock.json" "$PWD/package-lock.json"
308
332
  cp -p -- "$backup/project/robisie.config.json" "$PWD/robisie.config.json"
309
333
  cp -p -- "$backup/robisie/key" "$config_home/robisie/key"
334
+ cp -p -- "$backup/robisie/review-key" "$config_home/robisie/review-key"
310
335
  cp -p -- "$backup/robisie/manifest.json" "$config_home/robisie/manifest.json"
311
336
  cp -Rp -- "$backup/robisie/backups/." "$config_home/robisie/backups/"
312
337
  cp -Rp -- "$backup/robisie/roles/codex/." "$config_home/robisie/roles/codex/"
@@ -325,7 +350,7 @@ cp -p -- "$backup/profile/selected" "$profile"
325
350
  cp -p -- "$backup/entries/$entry_id" "$entry_path"
326
351
  ```
327
352
 
328
- Once the tgz and selected copies are ready, update. Init does not read the key file automatically: ROBISIE_KEY takes priority, then the hidden terminal prompt, then explicit `--key-stdin` (for example automation without a terminal). A key file alone is insufficient. Load the old key BEFORE init/doctor using the same XDG_CONFIG_HOME; separate assignment before export and `&&` retain read failures without printing the key:
353
+ Once the tgz and selected copies are ready, update. Init reuses saved A and B for an existing installation; ENV takes priority. Explicit `--key-stdin` replaces only A. Doctor and the launcher still require both environment variables. Load the old key BEFORE init/doctor using the same XDG_CONFIG_HOME; separate assignment before export and `&&` retain read failures without printing the key:
329
354
 
330
355
  <!-- update:start -->
331
356
  ```sh
@@ -336,11 +361,16 @@ export XDG_CONFIG_HOME &&
336
361
  if [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
337
362
  [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
338
363
  [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
364
+ [ ! -L "$XDG_CONFIG_HOME/robisie/review-key" ] &&
365
+ [ -f "$XDG_CONFIG_HOME/robisie/review-key" ] &&
366
+ [ -r "$XDG_CONFIG_HOME/robisie/review-key" ] &&
367
+ ROBISIE_REVIEW_KEY="$(cat "$XDG_CONFIG_HOME/robisie/review-key" 2>/dev/null)" &&
368
+ [ -n "$ROBISIE_REVIEW_KEY" ] &&
339
369
  ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key" 2>/dev/null)" &&
340
370
  [ -n "$ROBISIE_KEY" ]; then
341
- export ROBISIE_KEY
371
+ export ROBISIE_KEY ROBISIE_REVIEW_KEY
342
372
  else
343
- printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
373
+ printf '%s\n' 'Cannot load both nonempty regular readable robisie key files (key, review-key).' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If B is missing or rejected, supply a fresh owner_validator key via ROBISIE_REVIEW_KEY to init; --key-stdin replaces only A. Never paste the key into chat.' >&2
344
374
  false
345
375
  fi
346
376
  } &&
@@ -367,11 +397,16 @@ export XDG_CONFIG_HOME &&
367
397
  if [ ! -L "$XDG_CONFIG_HOME/robisie/key" ] &&
368
398
  [ -f "$XDG_CONFIG_HOME/robisie/key" ] &&
369
399
  [ -r "$XDG_CONFIG_HOME/robisie/key" ] &&
400
+ [ ! -L "$XDG_CONFIG_HOME/robisie/review-key" ] &&
401
+ [ -f "$XDG_CONFIG_HOME/robisie/review-key" ] &&
402
+ [ -r "$XDG_CONFIG_HOME/robisie/review-key" ] &&
403
+ ROBISIE_REVIEW_KEY="$(cat "$XDG_CONFIG_HOME/robisie/review-key" 2>/dev/null)" &&
404
+ [ -n "$ROBISIE_REVIEW_KEY" ] &&
370
405
  ROBISIE_KEY="$(cat "$XDG_CONFIG_HOME/robisie/key" 2>/dev/null)" &&
371
406
  [ -n "$ROBISIE_KEY" ]; then
372
- export ROBISIE_KEY
407
+ export ROBISIE_KEY ROBISIE_REVIEW_KEY
373
408
  else
374
- printf '%s\n' 'Cannot load a nonempty regular readable robisie key file.' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If the key is missing or revoked, use Connect and init with the hidden prompt. Never paste the key into chat.' >&2
409
+ printf '%s\n' 'Cannot load both nonempty regular readable robisie key files (key, review-key).' 'Next step: check the key file and its permissions locally; resolve links/directories without overwriting data. If B is missing or rejected, supply a fresh owner_validator key via ROBISIE_REVIEW_KEY to init; --key-stdin replaces only A. Never paste the key into chat.' >&2
375
410
  false
376
411
  fi
377
412
  } &&
@@ -395,6 +430,8 @@ npm uninstall robisie
395
430
 
396
431
  The first command removes robisie entries and blocks from files recorded in the installation manifest and undoes role installation. It does not restore old robisie entries. User-edited roles remain with a warning; backups remain and may contain an old key. Without an installation record the command changes nothing and **does not delete the key file**. A refusal during the Codex configuration check occurs **before key deletion**; after that check the key file is removed even if a later undo fails. A nonzero exit requires preserving your edits and resolving the reported problem before retrying. Open a new terminal. Uninstall does not revoke the key on the server: revoke it separately in Connect. The second command removes the package from the project and may change `package.json`, `package-lock.json` and `node_modules`; the npm cache may remain. Do not mass-delete those files or the cache. A later npx call may download the package again.
397
432
 
433
+ Backup and restore must include both key and review-key, with the same private permissions; load both restored keys before init/doctor. Uninstall reports each local key file separately and removes both under the same ledger/configuration safeguards. It does not revoke either server key.
434
+
398
435
  Retained backups, including private update copies, may still contain the key after uninstall. Keep them private according to your retention needs; uninstall does not erase or revoke those copies. This guide does not delete them automatically.
399
436
 
400
437
  <!-- sekcja: diagnoza -->
@@ -410,7 +447,7 @@ CLI messages remain in Polish. Match the message, then follow the English explan
410
447
  Generate a new worker key; in zsh/bash run `unset ROBISIE_KEY`, then init with the hidden prompt.
411
448
  - **brak-odczytu** — `Ten klucz nie ma uprawnień do odczytu tablicy (np. rola seeder).`
412
449
  Select worker in Connect; `unset ROBISIE_KEY`, then init with the hidden prompt.
413
- - **major** — `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.1.4 (obsługuje 1.x).`
450
+ - **major** — `Wersja kontraktu serwera (2.0.0) nie pasuje do paczki robisie 0.2.0 (obsługuje 1.x).`
414
451
  Example of a MAJOR mismatch: install a release compatible with the server contract.
415
452
  - **brak-env** — `Zmienna ROBISIE_KEY nie jest ustawiona — role i agenci jej potrzebują.`
416
453
  Check profile support; with --no-shell/another shell load the key file into the session environment as shown in init, then doctor.
@@ -431,3 +468,5 @@ After repair with an existing record, load the saved key as shown in Update befo
431
468
  The installer does not start background services or the Builder on its own; after operator approval, the CEO can start the Builder through `spawn_builder`. Helpers run during agent sessions using the project directory (or `ROBISIE_PROJECT_CONTEXT`) as context. The installer contacts robisie to check the contract and key; the package file does not provide an account or AI provider access. One shared key identity does not provide three different permission levels. Acceptance requires independent review, evidence and the operator's approval.
432
469
 
433
470
  Windows/WSL are unverified. Offline validation checks configuration structure, not project UUID, repo existence, model availability or provider execution.
471
+
472
+ The package engine (`dist/engine/tick.cjs`) is separate from the installer: it is started by `npx robisie factory run --engine-config ./robisie.config.json` and only on Linux; on any other system the command refuses with code 2 and a message. The `--once` option runs one tick without a pause and excludes an explicit `--interval`. Every nonzero tick result stops the supervisor („Fabryka zatrzymana: …”) with one diagnostic line on stderr; code 2 means an escalation (e.g. missing B key after receiver PASS, tester refusal, acceptance STOP) that must be resolved before retrying, and code 78 points to configuration repair. Real customer use on Linux will be proven in the D9 acceptance; on other systems there is no native proof of the engine running. Automatic FJ plans for customers are announced (“soon”) but are not in this release; the selector returns the true result.