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
@@ -0,0 +1,230 @@
1
+ import { spawnSync } from "node:child_process";
2
+ import { createHash, randomUUID } from "node:crypto";
3
+ import { closeSync, fsyncSync, fstatSync, lstatSync, mkdirSync, mkdtempSync, openSync, readSync, realpathSync, renameSync, rmdirSync, unlinkSync, writeFileSync } from "node:fs";
4
+ import path from "node:path";
5
+ import { z } from "zod";
6
+ const text = z.string().trim().min(1), at = z.iso.datetime({ offset: true });
7
+ const eventSchema = z.strictObject({ id: text, at, sha: z.string().regex(/^[a-f0-9]{40}$/), ref: text, operation: text, result: text });
8
+ const digest = (v) => createHash("sha256").update(v).digest("hex");
9
+ const failure = (e) => e instanceof z.ZodError ? "Niepoprawny kontrakt JSON" : String(e);
10
+ export function relative(ref) {
11
+ if (path.isAbsolute(ref) || ref.split(/[\\/]/).some(p => p === ".." || p === "") || ref.includes("\0"))
12
+ throw new Error("Obca ścieżka dowodu");
13
+ }
14
+ export function within(root, ref) {
15
+ relative(ref);
16
+ const base = realpathSync(root), file = realpathSync(path.join(base, ref));
17
+ if (!file.startsWith(base + path.sep))
18
+ throw new Error("Dowód poza zatwierdzonym katalogiem");
19
+ return file;
20
+ }
21
+ /** The transport already bounds model output to 256 KiB; inputs use the same byte bound. */
22
+ export function bounded(file) {
23
+ return new TextDecoder("utf-8", { fatal: true }).decode(boundedBytes(file));
24
+ }
25
+ function boundedBytes(file) {
26
+ const fd = openSync(file, "r"), bytes = Buffer.alloc(256 * 1024 + 1);
27
+ try {
28
+ if (!fstatSync(fd).isFile())
29
+ throw new Error("Dowód nie jest plikiem");
30
+ let length = 0, n;
31
+ while (length < bytes.length && (n = readSync(fd, bytes, length, bytes.length - length, null)) > 0)
32
+ length += n;
33
+ if (length === bytes.length)
34
+ throw new Error("Zbyt duży dowód");
35
+ return bytes.subarray(0, length);
36
+ }
37
+ finally {
38
+ closeSync(fd);
39
+ }
40
+ }
41
+ export function readLocalUsageEvents(root, c) {
42
+ try {
43
+ const landed = c.landed, readAt = c.readAt, after = Date.parse(at.parse(landed.at));
44
+ const until = Math.min(Date.parse(c.deadline), Date.parse(at.parse(readAt)));
45
+ const source = bounded(within(root, c.source));
46
+ if (source && !source.endsWith("\n"))
47
+ throw new Error("Urwany JSONL");
48
+ const ids = new Set(), operations = new Set(), artifacts = new Set(), events = [];
49
+ for (const line of source.split("\n").slice(0, -1)) {
50
+ const e = eventSchema.parse(JSON.parse(line));
51
+ if (e.sha !== landed.sha || Date.parse(e.at) <= after || Date.parse(e.at) > until)
52
+ throw new Error("Obcy SHA/czas użycia");
53
+ const bytes = bounded(within(root, e.ref)), sha256 = digest(bytes);
54
+ if (!bytes.trim())
55
+ throw new Error("Pusty artefakt użycia");
56
+ const duplicate = ids.has(e.id) || operations.has(e.operation) || artifacts.has(sha256);
57
+ ids.add(e.id);
58
+ operations.add(e.operation);
59
+ artifacts.add(sha256);
60
+ if (!duplicate)
61
+ events.push({ ...e, bytes, sha256 });
62
+ }
63
+ if (Buffer.byteLength(JSON.stringify(events)) > 256 * 1024)
64
+ throw new Error("Zbyt duży pakiet dowodów");
65
+ return events;
66
+ }
67
+ catch (cause) {
68
+ throw new Error(`Odmowa dowodów użycia: ${failure(cause)}`);
69
+ }
70
+ }
71
+ function syncDirectory(dir) {
72
+ const fd = openSync(dir, "r");
73
+ try {
74
+ fsyncSync(fd);
75
+ }
76
+ finally {
77
+ closeSync(fd);
78
+ }
79
+ }
80
+ /** Check each existing parent before creating anything; canonicalize aliases for the source lock. */
81
+ function directory(root, ref) {
82
+ if (realpathSync(root) !== root)
83
+ throw new Error("Zmieniony katalog dowodów");
84
+ if (ref === ".")
85
+ return root;
86
+ relative(ref);
87
+ let dir = root;
88
+ for (const part of ref.split(path.sep)) {
89
+ const next = path.join(dir, part);
90
+ if (!lstatSync(next, { throwIfNoEntry: false })) {
91
+ mkdirSync(next, { mode: 0o700 });
92
+ syncDirectory(dir);
93
+ }
94
+ dir = within(root, path.relative(root, next));
95
+ }
96
+ return dir;
97
+ }
98
+ function destination(root, ref) {
99
+ relative(ref);
100
+ const file = path.join(directory(root, path.dirname(ref)), path.basename(ref));
101
+ return lstatSync(file, { throwIfNoEntry: false }) ? within(root, path.relative(root, file)) : file;
102
+ }
103
+ function owned(root, file) {
104
+ if (realpathSync(root) !== root || within(root, path.relative(root, file)) !== file)
105
+ throw new Error("Zmieniona ścieżka przebiegu");
106
+ return file;
107
+ }
108
+ /** One synchronous Node invocation; no shell, card commands, inherited credentials or control env. */
109
+ export function runLocalUsage(input) {
110
+ let stage = "wejście", published = false, lock, pending;
111
+ let root, run, worktree, attempted = false, result;
112
+ const errors = [];
113
+ // Deliberately small environment; no HOME/config, NODE_OPTIONS, GIT_* or Planner credentials from the caller.
114
+ // The host Next.js types require NODE_ENV; this Node-only child intentionally omits it.
115
+ const env = { PATH: "/usr/bin:/bin", LANG: "C.UTF-8" };
116
+ const git = (cwd, args) => {
117
+ const r = spawnSync("git", args, { cwd, env, encoding: "utf8", shell: false });
118
+ if (r.error || r.status !== 0 || r.signal)
119
+ throw new Error(`git ${args[0]}: status=${r.status}, signal=${r.signal}: ${r.stderr ?? ""}`, { cause: r.error });
120
+ return r.stdout.trim();
121
+ };
122
+ try {
123
+ eventSchema.shape.sha.parse(input.landed.sha);
124
+ at.parse(input.landed.at);
125
+ at.parse(input.deadline);
126
+ text.parse(input.operation);
127
+ z.array(z.string()).parse(input.program.args);
128
+ for (const ref of [input.source, input.program.entry, input.program.artifact])
129
+ relative(ref);
130
+ if (Date.parse(input.landed.at) >= Date.now() || Date.parse(input.deadline) < Date.now())
131
+ throw new Error("Obcy czas użycia");
132
+ stage = "katalog dowodów";
133
+ const state = realpathSync(input.stateDir);
134
+ root = directory(state, "evidence");
135
+ const source = destination(root, input.source), sourceRef = path.relative(root, source);
136
+ stage = "blokada";
137
+ const fd = openSync(`${source}.lock`, "wx", 0o600);
138
+ lock = `${source}.lock`;
139
+ closeSync(fd);
140
+ stage = "odczyt źródła";
141
+ let previous = Buffer.alloc(0);
142
+ if (lstatSync(source, { throwIfNoEntry: false })) {
143
+ readLocalUsageEvents(root, { ...input, source: sourceRef, readAt: new Date().toISOString() });
144
+ previous = boundedBytes(source);
145
+ }
146
+ stage = "worktree";
147
+ run = mkdtempSync(path.join(directory(root, ".runs"), "usage-"));
148
+ worktree = path.join(run, "wt");
149
+ attempted = true;
150
+ git(input.repo, ["worktree", "add", "--detach", "--quiet", worktree, input.landed.sha]);
151
+ const verify = () => {
152
+ if (git(worktree, ["rev-parse", "HEAD"]) !== input.landed.sha)
153
+ throw new Error("Obcy SHA użycia");
154
+ if (git(worktree, ["status", "--porcelain", "--untracked-files=no"]))
155
+ throw new Error("Zmieniony śledzony kod użycia");
156
+ };
157
+ stage = "SHA przed wykonaniem";
158
+ verify();
159
+ const entry = within(worktree, input.program.entry);
160
+ git(worktree, ["--literal-pathspecs", "ls-files", "--error-unmatch", "--", input.program.entry, path.relative(worktree, entry)]);
161
+ const artifact = destination(worktree, input.program.artifact);
162
+ if (lstatSync(artifact, { throwIfNoEntry: false }))
163
+ throw new Error("Artefakt istnieje przed użyciem");
164
+ stage = "proces";
165
+ const executed = spawnSync(process.execPath, [entry, ...input.program.args], { cwd: worktree, env, encoding: "utf8", shell: false });
166
+ const finishedAt = new Date().toISOString();
167
+ if (executed.error || executed.status !== 0 || executed.signal)
168
+ throw new Error(`Proces użycia: status=${executed.status}, signal=${executed.signal}; stdout=${executed.stdout ?? ""}; stderr=${executed.stderr ?? ""}`, { cause: executed.error });
169
+ stage = "SHA po wykonaniu";
170
+ verify();
171
+ stage = "artefakt";
172
+ const bytes = boundedBytes(within(worktree, input.program.artifact));
173
+ const id = randomUUID(), ref = `artifacts/${id}/${path.basename(input.program.artifact)}`;
174
+ const saved = destination(root, ref);
175
+ writeFileSync(saved, bytes, { flag: "wx", mode: 0o600, flush: true });
176
+ within(root, ref);
177
+ syncDirectory(path.dirname(saved));
178
+ result = eventSchema.parse({ id, at: finishedAt, sha: git(worktree, ["rev-parse", "HEAD"]), ref,
179
+ operation: input.operation, result: JSON.stringify({ exit: executed.status, stdout: executed.stdout ?? "", stderr: executed.stderr ?? "" }) });
180
+ stage = "walidacja zapisu";
181
+ // Stable key order; validate JSON before serializing so undefined never silently disappears.
182
+ const line = JSON.stringify(z.json().parse(Object.fromEntries(Object.entries(result).sort(([a], [b]) => a.localeCompare(b))))) + "\n";
183
+ const temp = `${source}.${id}.pending`;
184
+ if (destination(root, path.relative(root, temp)) !== temp)
185
+ throw new Error("Zmieniony katalog źródła");
186
+ const out = openSync(temp, "wx", 0o600);
187
+ pending = temp;
188
+ try {
189
+ writeFileSync(out, Buffer.concat([previous, Buffer.from(line)]));
190
+ fsyncSync(out);
191
+ }
192
+ finally {
193
+ closeSync(out);
194
+ }
195
+ readLocalUsageEvents(root, { ...input, source: path.relative(root, temp), readAt: new Date().toISOString() });
196
+ stage = "publikacja";
197
+ // Recheck physical parents immediately before publication, never follow a redirected source.
198
+ if (destination(root, input.source) !== source || within(root, path.relative(root, temp)) !== temp)
199
+ throw new Error("Zmieniony katalog źródła");
200
+ renameSync(temp, source);
201
+ published = true;
202
+ pending = undefined;
203
+ syncDirectory(path.dirname(source));
204
+ }
205
+ catch (cause) {
206
+ errors.push(new Error(`Użycie — ${stage}: ${failure(cause)}`, { cause }));
207
+ }
208
+ finally {
209
+ const cleanup = (label, action) => {
210
+ try {
211
+ action();
212
+ }
213
+ catch (cause) {
214
+ errors.push(new Error(`Użycie — cleanup ${label}: ${String(cause)}`, { cause }));
215
+ }
216
+ };
217
+ if (attempted && worktree)
218
+ cleanup("worktree", () => { git(input.repo, ["worktree", "remove", "--force", owned(root, worktree)]); });
219
+ if (run)
220
+ cleanup("katalog przebiegu", () => rmdirSync(owned(root, run)));
221
+ if (pending)
222
+ cleanup("plik tymczasowy", () => unlinkSync(owned(root, pending)));
223
+ if (lock)
224
+ cleanup("blokada", () => unlinkSync(owned(root, lock)));
225
+ }
226
+ if (errors.length)
227
+ throw new AggregateError(errors, errors.map(e => e.message).join("; ")
228
+ + (published ? "; wpis może już istnieć — sprawdź źródło, nie ponawiaj całego programu" : "; zdarzenie nie zostało opublikowane"));
229
+ return result;
230
+ }
@@ -22,6 +22,7 @@ export declare function clientPaths(dir: string): {
22
22
  dir: string;
23
23
  manifest: string;
24
24
  key: string;
25
+ reviewKey: string;
25
26
  backups: string;
26
27
  roles: string;
27
28
  codexRoles: string;
@@ -37,5 +38,7 @@ export declare function ensurePrivateDir(dir: string): void;
37
38
  export declare function writePrivate(dir: string, path: string, text: string): void;
38
39
  export declare function readManifest(path: string): Manifest | null;
39
40
  export declare function writeManifest(dir: string, manifest: Omit<Manifest, "packageVersion">): void;
40
- export declare function writeKey(dir: string, key: string): void;
41
- export declare function readKey(dir: string): string | null;
41
+ type KeySlot = "key" | "review-key";
42
+ export declare function writeKey(dir: string, key: string, slot?: KeySlot): void;
43
+ export declare function readKey(dir: string, slot?: KeySlot): string | null;
44
+ export {};
package/dist/manifest.js CHANGED
@@ -31,6 +31,7 @@ export function clientPaths(dir) {
31
31
  dir,
32
32
  manifest: join(dir, "manifest.json"),
33
33
  key: join(dir, "key"),
34
+ reviewKey: join(dir, "review-key"),
34
35
  backups: join(dir, "backups"),
35
36
  roles: join(dir, "roles"),
36
37
  codexRoles: join(dir, "roles", "codex"),
@@ -182,12 +183,11 @@ export function writeManifest(dir, manifest) {
182
183
  const paths = clientPaths(dir);
183
184
  writePrivate(paths.dir, paths.manifest, `${JSON.stringify({ packageVersion: PACKAGE_VERSION, ...manifest }, null, 2)}\n`);
184
185
  }
185
- export function writeKey(dir, key) {
186
- const paths = clientPaths(dir);
187
- writePrivate(paths.dir, paths.key, `${key}\n`);
186
+ export function writeKey(dir, key, slot = "key") {
187
+ writePrivate(dir, join(dir, slot), `${key}\n`);
188
188
  }
189
- export function readKey(dir) {
190
- const path = clientPaths(dir).key;
189
+ export function readKey(dir, slot = "key") {
190
+ const path = join(dir, slot);
191
191
  refuseSymlink(dir);
192
192
  refuseSymlink(path);
193
193
  try {
@@ -196,6 +196,6 @@ export function readKey(dir) {
196
196
  catch (error) {
197
197
  if (error.code === "ENOENT")
198
198
  return null;
199
- throw new RobisieError(`Nie mogę odczytać pliku ${path} (błąd IO).`, `Sprawdź prawa odczytu pliku ${path}. Jeśli nie jest zwykłym plikiem, przywróć go z poprawnej kopii tej samej instalacji, zachowując istniejący plik lub katalog i jego zawartość w osobnej kopii. Potem wczytaj ROBISIE_KEY zgodnie z instrukcją instalacji i ponów \`npx robisie doctor\`.`);
199
+ throw new RobisieError(`Nie mogę odczytać pliku ${path} (błąd IO).`, `Sprawdź prawa odczytu pliku ${path}. Jeśli nie jest zwykłym plikiem, przywróć go z poprawnej kopii tej samej instalacji, zachowując istniejący plik lub katalog i jego zawartość w osobnej kopii. Potem wczytaj ${slot === "key" ? "ROBISIE_KEY" : "ROBISIE_REVIEW_KEY"} zgodnie z instrukcją instalacji i ponów \`npx robisie doctor\`.`);
200
200
  }
201
201
  }
@@ -5,12 +5,17 @@ async function robisieReviewGuard() {
5
5
  "tool.execute.before": async (input, output) => {
6
6
  if (typeof input !== "object" || input === null || !("tool" in input))
7
7
  return;
8
- if (input.tool !== "robisie_create_task" && input.tool !== "robisie_update_task")
8
+ if (input.tool !== "robisie_create_task" && input.tool !== "robisie_update_task" && input.tool !== "robisie_create_tasks")
9
9
  return;
10
10
  if (typeof output !== "object" || output === null || !("args" in output))
11
11
  return;
12
12
  const args = output.args;
13
- if (typeof args === "object" && args !== null && "status" in args && args.status === "delivered") {
13
+ if (typeof args !== "object" || args === null)
14
+ return;
15
+ const delivered = input.tool === "robisie_create_tasks"
16
+ ? "tasks" in args && Array.isArray(args.tasks) && args.tasks.some((task) => typeof task === "object" && task !== null && "status" in task && (task.status === "delivered" || task.status === "wdrożone"))
17
+ : "status" in args && (args.status === "delivered" || args.status === "wdrożone");
18
+ if (delivered) {
14
19
  throw new Error("Brak wspieranego protokołu recenzji w OpenCode. Ta próba nie zmieniła karty.");
15
20
  }
16
21
  },
@@ -11,8 +11,8 @@ export type PlanerClientConfig = ({
11
11
  fetch?: typeof fetch;
12
12
  deadlineMs?: number;
13
13
  };
14
- type Operation = "connect" | "close" | "list_projects" | "list_tracks" | "list_tasks" | "get_task" | "reserve_task" | "update_task" | "append_detail" | "close_decision_matter" | "get_review_snapshot" | "accept_review" | "create_track" | "create_task";
15
- type Failure = "INVALID_CONFIG" | "INVALID_ARGUMENT" | "NOT_CONNECTED" | "CLOSED" | "CONTRACT_VERSION" | "INVALID_RESPONSE" | "DETAILS_READ_ERROR" | "TOOL_ERROR" | "UNAUTHORIZED" | "FORBIDDEN" | "RATE_LIMITED" | "HTTP_ERROR" | "RPC_ERROR" | "TRANSPORT_ERROR" | "TIMEOUT";
14
+ type Operation = "connect" | "close" | "list_projects" | "list_tracks" | "list_tasks" | "get_task" | "reserve_task" | "update_task" | "append_detail" | "close_decision_matter" | "get_review_snapshot" | "accept_review" | "create_track" | "create_task" | "move_task" | "write_decision_matter";
15
+ type Failure = "INVALID_CONFIG" | "INVALID_ARGUMENT" | "NOT_CONNECTED" | "CLOSED" | "CONTRACT_VERSION" | "UNSUPPORTED_CONTRACT" | "INVALID_RESPONSE" | "DETAILS_READ_ERROR" | "TOOL_ERROR" | "UNAUTHORIZED" | "FORBIDDEN" | "RATE_LIMITED" | "HTTP_ERROR" | "RPC_ERROR" | "TRANSPORT_ERROR" | "TIMEOUT";
16
16
  /** Fixed reason only. In particular, never attach SDK message, cause, raw body or caller arguments. */
17
17
  export declare class PlanerClientError extends Error {
18
18
  readonly code: Failure;
@@ -24,10 +24,13 @@ export declare class PlanerClientError extends Error {
24
24
  uncertain?: boolean, diagnostic?: {
25
25
  plannerCode?: string;
26
26
  requestId?: string;
27
+ plannerMeta?: Record<string, unknown>;
27
28
  });
28
29
  readonly plannerCode?: string;
29
30
  readonly requestId?: string;
31
+ readonly plannerMeta?: Record<string, unknown>;
30
32
  }
33
+ export declare const PLANNER_DOMAIN_CODES: readonly ["PROJECT_NOT_FOUND", "PROJECT_NAME_TAKEN", "PROJECT_LIMIT_REACHED", "CONCURRENCY_LIMIT_REACHED", "WEBHOOK_SUBSCRIPTION_LIMIT_REACHED", "TRACK_NOT_FOUND", "TRACK_HAS_TASKS", "TRACK_REORDER_MISMATCH", "TASK_DETAILS_MACHINE_FIELD_INVALID", "TASK_DETAILS_TOO_LARGE", "TASK_NOT_FOUND", "TASK_UPDATE_CONFLICT", "SEED_PACKAGE_DENIED", "TASK_DONE_EVIDENCE_REQUIRED", "TASK_CARD_CLASS_IMMUTABLE", "TASK_DONE_EVIDENCE_IMMUTABLE", "TASK_SELF_DEPENDENCY", "DEPENDENCY_NOT_FOUND", "TASK_INSERT_FAILED", "TASK_VANISHED", "TASK_ALREADY_CLAIMED", "TASK_NOT_RESERVABLE", "TASK_RESERVATION_RACED", "NEIGHBOR_NOT_FOUND", "NEIGHBOR_WRONG_TRACK", "NEIGHBOR_ORDER_INVALID"];
31
34
  declare const jsonObject: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
32
35
  declare const projectSchema: z.ZodObject<{
33
36
  id: z.ZodUUID;
@@ -56,6 +59,22 @@ declare const taskSchema: z.ZodObject<{
56
59
  }>;
57
60
  assignee: z.ZodNullable<z.ZodString>;
58
61
  dependsOn: z.ZodArray<z.ZodUUID>;
62
+ specRef: z.ZodNullable<z.ZodString>;
63
+ createdAt: z.ZodISODateTime;
64
+ updatedAt: z.ZodISODateTime;
65
+ position: z.ZodOptional<z.ZodNullable<z.ZodString>>;
66
+ statusEnteredAt: z.ZodOptional<z.ZodNullable<z.ZodISODateTime>>;
67
+ statusEnteredStatus: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
68
+ ready: "ready";
69
+ in_review: "in_review";
70
+ in_progress: "in_progress";
71
+ delivered: "delivered";
72
+ blocked: "blocked";
73
+ done: "done";
74
+ draft: "draft";
75
+ }>>>;
76
+ seedBriefDigest: z.ZodOptional<z.ZodNullable<z.ZodString>>;
77
+ seedPackageDigest: z.ZodOptional<z.ZodNullable<z.ZodString>>;
59
78
  }, z.core.$strip>;
60
79
  declare const echoSchema: z.ZodObject<{
61
80
  id: z.ZodUUID;
@@ -153,8 +172,8 @@ declare const appendSchema: z.ZodObject<{
153
172
  declare const closeSchema: z.ZodObject<{
154
173
  outcome: z.ZodEnum<{
155
174
  CLOSED: "CLOSED";
156
- ALREADY_CLOSED: "ALREADY_CLOSED";
157
175
  CONFLICT: "CONFLICT";
176
+ ALREADY_CLOSED: "ALREADY_CLOSED";
158
177
  NOT_APPLIED: "NOT_APPLIED";
159
178
  }>;
160
179
  cardId: z.ZodUUID;
@@ -182,6 +201,17 @@ export type AppendDetailResult = {
182
201
  export type CloseDecisionResult = Omit<z.infer<typeof closeSchema>, "matter"> & {
183
202
  isError: boolean;
184
203
  };
204
+ /** applied:false = server refused the guarded append (structured CONFLICT); nothing was written. */
205
+ export type AppendDetailIfResult = {
206
+ applied: true;
207
+ write: z.infer<typeof appendSchema>;
208
+ } | {
209
+ applied: false;
210
+ };
211
+ export type DecisionMatter = z.infer<typeof jsonObject>;
212
+ /** Minimum server contract for update_task expected.details/detailsPatch, guarded append_detail and
213
+ * write_decision_matter. Older 1.x servers silently strip these unknown fields, so the client refuses locally. */
214
+ export declare const PARITY_CONTRACT_MINOR = 1;
185
215
  /** Existing MCP operations only. No auto-connect, retry, CAS emulation or runtime cutover. */
186
216
  export declare class PlanerClient {
187
217
  #private;
@@ -204,10 +234,21 @@ export declare class PlanerClient {
204
234
  * Local validation fails with INVALID_ARGUMENT/uncertain=false; failures after sending are uncertain.
205
235
  * After an uncertain write, caller must explicitly getTask({id, include:['review_receipt']}) and decide. */
206
236
  acceptReview(args: unknown): Promise<z.infer<typeof echoSchema>>;
207
- /** For draft promotion, pass {status:'ready', expected:{status:'draft'}}. Server owns CAS/permissions. */
237
+ /** For draft promotion, pass {status:'ready', expected:{status:'draft'}}. Server owns CAS/permissions.
238
+ * expected.details (snapshot CAS) and detailsPatch (shallow merge) need contract >= 1.1.0 and are
239
+ * applied by the server in the same atomic write; details and detailsPatch are mutually exclusive. */
208
240
  updateTask(args: unknown): Promise<z.infer<typeof echoSchema>>;
209
241
  /** Flat server merge; null is literal. No deep merge, chunking, append guard or implicit retry. */
210
242
  appendDetail(args: unknown): Promise<AppendDetailResult>;
243
+ /** Guarded append (q.appendDetailIf/appendDetail guard): one CAS write on the server, no readback,
244
+ * no retry. Requires contract >= 1.1.0. applied:false only for a structured CONFLICT of this card. */
245
+ appendDetailIf(args: unknown): Promise<AppendDetailIfResult>;
246
+ /** q.writeDecisionMatter: open/update one decision matter; expected = exact current matter (CAS).
247
+ * Returns the persisted matter (also when the server refused the write) or null; caller compares.
248
+ * Requires contract >= 1.1.0. Server owns roles, size limits and closed-matter rules. */
249
+ writeDecisionMatter(args: unknown): Promise<DecisionMatter | null>;
250
+ /** Change track and/or order. Server computes the position; no retry. */
251
+ moveTask(args: unknown): Promise<z.infer<typeof echoSchema>>;
211
252
  /** full/owner_validator authority stays on the server. Non-CLOSED outcomes retain isError. */
212
253
  closeDecisionMatter(args: unknown): Promise<CloseDecisionResult>;
213
254
  }