robisie 0.1.0 → 0.1.1

package/dist/dispatch-scope.d.ts

@@ -0,0 +1,18 @@
+export type CardLike = {
+    id: string;
+    title: string;
+    details?: Record<string, unknown> | null;
+};
+export declare const SCOPE_DETAILS_KEYS: readonly ["scope"];
+/** Ścieżka przed opisem i numerem linii; porównujemy całe segmenty katalogu. */
+export declare function scopePaths(card: CardLike): string[];
+export declare function scopesOverlap(a: readonly string[], b: readonly string[]): boolean;
+/** Only promotion/dispatch collisions ignore tests; write permissions and land diffs stay complete. */
+export declare function collisionScope(scope: readonly string[]): string[];
+/** Dispatch only, normalized paths. ownerChanges: omitted = candidate, array = owner delta, null = unknown IO. */
+export declare function dispatchScope(paths: readonly string[], confirmedTestDirectories: readonly string[], ownerChanges?: readonly string[] | null): string[];
+export declare function pickDispatchable<T extends CardLike>(candidatesByTrack: ReadonlyMap<string, readonly T[]>, activeScopes: readonly string[][], slots: number, projectScope?: (card: T) => readonly string[]): {
+    picked: T[];
+    waitingScope: T[];
+    waitingWip: T[];
+};

package/dist/dispatch-scope.js

@@ -0,0 +1,46 @@
+import { posix } from "node:path";
+export const SCOPE_DETAILS_KEYS = ["scope"];
+/** Ścieżka przed opisem i numerem linii; porównujemy całe segmenty katalogu. */
+export function scopePaths(card) {
+    const details = card.details ?? {};
+    const raw = details.scope;
+    return Array.isArray(raw) ? raw.filter((p) => typeof p === "string")
+        .map(p => p.trim().split(/\s+/, 1)[0].replace(/`/g, "").replace(/:\d+(?:[-:]\d+)*$/, ""))
+        .filter(Boolean).map(p => posix.normalize(p).replace(/\/$/, "")) : [];
+}
+export function scopesOverlap(a, b) {
+    return a.some(x => b.some(y => x === "." || y === "." || x === y || x.startsWith(`${y}/`) || y.startsWith(`${x}/`)));
+}
+/** Only promotion/dispatch collisions ignore tests; write permissions and land diffs stay complete. */
+export function collisionScope(scope) {
+    return scope.filter(file => !/(^|\/)(?:__tests__|tests)(?:\/|$)|\.(?:test|spec)\.[^/]+$/.test(file));
+}
+/** Dispatch only, normalized paths. ownerChanges: omitted = candidate, array = owner delta, null = unknown IO. */
+export function dispatchScope(paths, confirmedTestDirectories, ownerChanges) {
+    // Unknown owner evidence keeps the broad reservation; an unknown scope blocks all paths.
+    if (ownerChanges !== undefined && !paths.length)
+        return ["."];
+    if (ownerChanges === null)
+        return [...paths];
+    const directories = new Set(confirmedTestDirectories);
+    const reserved = paths.filter(p => !directories.has(p)
+        || !(p === "tests" || p.startsWith("tests/") || p.split("/").includes("__tests__")));
+    return [...new Set([...reserved, ...(ownerChanges ?? [])])];
+}
+export function pickDispatchable(candidatesByTrack, activeScopes, slots, projectScope) {
+    const picked = [], waitingScope = [], waitingWip = [];
+    const occupied = activeScopes.map(collisionScope);
+    for (const queue of candidatesByTrack.values())
+        for (const card of queue) {
+            const scope = collisionScope(projectScope ? projectScope(card) : scopePaths(card));
+            if (occupied.some(active => scopesOverlap(scope, active)))
+                waitingScope.push(card);
+            else if (picked.length >= slots)
+                waitingWip.push(card);
+            else {
+                picked.push(card);
+                occupied.push(scope);
+            }
+        }
+    return { picked, waitingScope, waitingWip };
+}

package/dist/done-evidence.d.ts

@@ -0,0 +1,31 @@
+type Details = Record<string, unknown> | null | undefined;
+type RequiredDoneEvidenceKey = (typeof REQUIRED_DONE_EVIDENCE_KEYS)[number];
+declare const REQUIRED_DONE_EVIDENCE_KEYS: readonly ["enabled_evidence", "real_use_evidence"];
+export declare function acceptorRole(by: string): string;
+/** Exact landed evidence only; carry/rebase/attempts are not receipts. */
+export declare function machineProcessTraces(details: Details): {
+    ok: boolean;
+    missing: ("test" | "review" | "ci")[];
+};
+/** Only source fields belong to this tuple; missing/invalid text has one representation. */
+export declare function doneRetrySnapshot(details: Record<string, unknown>): (string | (string | null)[] | null)[];
+export declare function doneEvidenceFingerprint(details: Record<string, unknown>): string;
+/** CR supplies the receipt; a role or model name is never provider evidence. */
+export declare function acceptanceIndependenceValid(details: Details): boolean;
+/** Factory cards with a canonical criterion list need a separate per-criterion acceptance. */
+export declare function doneAcceptanceProblems(persistedDetails: Details, effectiveDetails: Details): string[];
+export declare function declaredCardClassChanged(persistedDetails: Details, effectiveDetails: Details): boolean;
+/**
+ * Factory-only rollout: an absent/explicitly non-executable class stays on the legacy path. For an
+ * executable card, both proofs must be structured objects with non-empty what/when/ref fields.
+ */
+export declare function missingExecutableDoneEvidence(persistedDetails: Details, effectiveDetails: Details): RequiredDoneEvidenceKey[];
+/** True when a patch needs a locked read before merging a done-gate control field. */
+export declare function touchesDoneInvariant(patch: Record<string, unknown>): boolean;
+/**
+ * Compare the required proof payload, not object identity or unrelated details. This lets callers
+ * update other metadata while an executable card remains done, but changing/removing what/when/ref
+ * requires a deliberate reopen to delivered first.
+ */
+export declare function executableDoneEvidenceChanged(persistedDetails: Details, effectiveDetails: Details): boolean;
+export {};

package/dist/done-evidence.js

@@ -0,0 +1,216 @@
+import { createHash } from "node:crypto";
+const REQUIRED_DONE_EVIDENCE_KEYS = [
+    "enabled_evidence",
+    "real_use_evidence",
+];
+const DONE_EVIDENCE_FIELDS = ["what", "when", "ref"];
+const DONE_INVARIANT_DETAIL_KEYS = new Set([
+    "card_class",
+    "acceptance",
+    "done_when",
+    ...REQUIRED_DONE_EVIDENCE_KEYS,
+]);
+function objectDetails(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : undefined;
+}
+function nonEmptyText(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function legacyAcceptorRole(by) {
+    return by.trim().split(/[\s(]/, 1)[0].toLowerCase().replace(/-\d+$/, "");
+}
+export function acceptorRole(by) {
+    const embedded = by.match(/\b([A-Za-z][A-Za-z0-9]*(?:-[A-Za-z][A-Za-z0-9]*)*)-\d+\b/);
+    if (embedded)
+        return embedded[1].toLowerCase();
+    return legacyAcceptorRole(by);
+}
+function recordOrEmpty(value) { return objectDetails(value) ?? {}; }
+/** Exact landed evidence only; carry/rebase/attempts are not receipts. */
+export function machineProcessTraces(details) {
+    const sha = recordOrEmpty(details?.landed).sha, ci = recordOrEmpty(details?.ci_receipt);
+    const valid = nonEmptyText(sha) && /^[a-f0-9]{7,40}$/i.test(sha);
+    const missing = [];
+    for (const key of ["test", "review"]) {
+        const trace = recordOrEmpty(details?.[key]);
+        if (!valid || trace.sha !== sha || trace.verdict !== "PASS")
+            missing.push(key);
+    }
+    if (!valid || ci.sha !== sha || ci.conclusion !== "success" || ci.check !== "Verify (lint + build:check)"
+        || !["push-main", "pr-head"].includes(String(ci.source)) || !nonEmptyText(ci.head_sha) || !/^[a-f0-9]{7,40}$/i.test(ci.head_sha)
+        || typeof ci.check_run_url !== "string" || !/^https:\/\/api\.github\.com\/repos\/chuppa12\/robisie-app\/check-runs\/[1-9]\d*$/.test(ci.check_run_url)
+        || ci.source === "push-main" && ci.head_sha !== sha
+        || ci.source === "pr-head" && (ci.merge_commit_sha !== sha || ci.base_ref !== "main" || !Number.isSafeInteger(ci.pr_number) || Number(ci.pr_number) <= 0
+            || typeof ci.merged_at !== "string" || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(ci.merged_at) || !Number.isFinite(Date.parse(ci.merged_at)))
+        || typeof ci.checked_at !== "string"
+        || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(?:\.\d+)?(?:Z|[+-]\d{2}:\d{2})$/.test(ci.checked_at) || !Number.isFinite(Date.parse(ci.checked_at))
+        || typeof ci.run_url !== "string" || !/^https:\/\/github\.com\/chuppa12\/robisie-app\/actions\/runs\/[1-9]\d*$/.test(ci.run_url))
+        missing.push("ci");
+    return { ok: !missing.length, missing };
+}
+/** Only source fields belong to this tuple; missing/invalid text has one representation. */
+export function doneRetrySnapshot(details) {
+    const text = (v) => nonEmptyText(v) ? v : null;
+    const proof = (v) => ["what", "when", "ref"].map(k => text(recordOrEmpty(v)[k]));
+    const authors = recordOrEmpty(details.seed_provenance);
+    return [text(recordOrEmpty(details.landed).sha), proof(details.enabled_evidence), proof(details.real_use_evidence),
+        Array.isArray(details.done_when) ? details.done_when.map(text) : null,
+        ["by", "proposal_by", "packager_by"].map(k => text(authors[k]))];
+}
+export function doneEvidenceFingerprint(details) {
+    return createHash("sha256").update(JSON.stringify(doneRetrySnapshot(details))).digest("hex");
+}
+/** CR supplies the receipt; a role or model name is never provider evidence. */
+export function acceptanceIndependenceValid(details) {
+    const a = recordOrEmpty(details?.acceptance), i = recordOrEmpty(a.independence);
+    const authors = recordOrEmpty(i.authoring_providers), sha = recordOrEmpty(details?.landed).sha;
+    return nonEmptyText(sha) && /^[a-f0-9]{7,40}$/i.test(sha) && a.sha === sha && i.sha === sha
+        && nonEmptyText(i.ref) && nonEmptyText(i.receiver_provider)
+        && a.evidence_fingerprint === doneEvidenceFingerprint(details ?? {})
+        && ["by", "proposal_by", "packager_by", "worker"].every(k => nonEmptyText(authors[k])
+            && String(authors[k]).trim().toLowerCase() !== String(i.receiver_provider).trim().toLowerCase());
+}
+/** Factory cards with a canonical criterion list need a separate per-criterion acceptance. */
+export function doneAcceptanceProblems(persistedDetails, effectiveDetails) {
+    const isExecutable = declaredCardClass(persistedDetails) === "executable" ||
+        declaredCardClass(effectiveDetails) === "executable";
+    const isCohort = persistedDetails?.["origin"] === "reksio/propozycja" ||
+        effectiveDetails?.["origin"] === "reksio/propozycja";
+    const doneWhen = effectiveDetails?.["done_when"];
+    if (!isExecutable)
+        return [];
+    if (!Array.isArray(doneWhen) ||
+        doneWhen.length === 0 ||
+        !doneWhen.every(nonEmptyText))
+        return isCohort
+            ? ["done_when puste lub niepoprawne — kohorta reksio/propozycja wymaga mierzalnych kryteriów przy done"]
+            : [];
+    const problems = [];
+    const persistedSeedProvenance = objectDetails(persistedDetails?.["seed_provenance"]);
+    const effectiveSeedProvenance = objectDetails(effectiveDetails?.["seed_provenance"]);
+    const seedField = (key) => {
+        const persisted = persistedSeedProvenance?.[key];
+        return nonEmptyText(persisted) ? persisted : effectiveSeedProvenance?.[key];
+    };
+    // updateTask replaces details wholesale; authors must come from the value being saved.
+    const proposalBy = effectiveSeedProvenance?.["proposal_by"];
+    const packagerBy = effectiveSeedProvenance?.["packager_by"];
+    const independent = acceptanceIndependenceValid(effectiveDetails);
+    if (isCohort && !independent) {
+        if (!nonEmptyText(effectiveSeedProvenance?.by))
+            problems.push("brak details.seed_provenance.by");
+        if (!nonEmptyText(proposalBy))
+            problems.push("brak details.seed_provenance.proposal_by");
+        if (!nonEmptyText(packagerBy))
+            problems.push("brak details.seed_provenance.packager_by");
+    }
+    const acceptance = objectDetails(effectiveDetails?.["acceptance"]);
+    if (!acceptance) {
+        problems.push("brak details.acceptance");
+        return problems;
+    }
+    if (acceptance.independence !== undefined && !independent)
+        problems.push("acceptance.independence: brak niezależnego receiptu bieżącego SHA/fingerprintu");
+    const by = acceptance["by"];
+    if (!nonEmptyText(by))
+        problems.push("acceptance.by pusty");
+    if (!nonEmptyText(acceptance["at"]))
+        problems.push("acceptance.at pusty");
+    const criteria = acceptance["criteria"];
+    if (!Array.isArray(criteria) ||
+        criteria.length !== doneWhen.length ||
+        !criteria.every((criterion, i) => criterion === doneWhen[i]))
+        problems.push("kryteria zmienione po odbiorze (acceptance.criteria ≠ done_when)");
+    const results = acceptance["results"];
+    if (!Array.isArray(results) || results.length !== doneWhen.length) {
+        const resultCount = Array.isArray(results) ? results.length : 0;
+        problems.push(`acceptance.results: ${Array.isArray(results) ? resultCount : "brak"} zamiast ${doneWhen.length}`);
+        problems.push(resultCount < doneWhen.length
+            ? `kryterium ${resultCount + 1}: brak wyniku`
+            : `kryterium ${doneWhen.length + 1}: wynik nadmiarowy`);
+    }
+    if (Array.isArray(results)) {
+        for (let i = 0; i < results.length; i += 1) {
+            const result = objectDetails(results[i]);
+            if (result?.basis === "machine-process") {
+                for (const key of machineProcessTraces(effectiveDetails).missing) {
+                    if (!problems.includes(`brak śladu: ${key}`))
+                        problems.push(`brak śladu: ${key}`);
+                }
+                if (result.ref !== `machine-process:${recordOrEmpty(effectiveDetails?.ci_receipt).run_url}`)
+                    problems.push(`kryterium ${i + 1}: obcy ref machine-process`);
+            }
+            const verdict = result?.["verdict"];
+            if (verdict !== "PASS")
+                problems.push(`kryterium ${i + 1}: werdykt ${verdict ?? "brak"}`);
+            if (!nonEmptyText(result?.["ref"]))
+                problems.push(`kryterium ${i + 1}: pusty ref`);
+        }
+    }
+    const seederBy = seedField("by");
+    const seederRole = isCohort ? acceptorRole : legacyAcceptorRole;
+    if (nonEmptyText(by) && nonEmptyText(seederBy) && seederRole(by) === seederRole(seederBy)) {
+        problems.push(`odbierający = siewca (rola ${seederRole(by)})`);
+    }
+    if (isCohort && nonEmptyText(by)) {
+        if ([proposalBy, seedField("proposal_by")].some(v => nonEmptyText(v) && acceptorRole(by) === acceptorRole(v))) {
+            problems.push(`odbierający = proponujący (rola ${acceptorRole(by)})`);
+        }
+        if ([packagerBy, seedField("packager_by")].some(v => nonEmptyText(v) && acceptorRole(by) === acceptorRole(v))) {
+            problems.push(`odbierający = opracowujący (rola ${acceptorRole(by)})`);
+        }
+    }
+    return problems;
+}
+function declaredCardClass(details) {
+    const value = details?.["card_class"];
+    return value === "executable" || value === "non_executable" ? value : undefined;
+}
+function hasCompleteDoneEvidence(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const evidence = value;
+    return DONE_EVIDENCE_FIELDS.every((key) => typeof evidence[key] === "string" && evidence[key].trim().length > 0);
+}
+function evidenceField(value, key) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    return value[key];
+}
+export function declaredCardClassChanged(persistedDetails, effectiveDetails) {
+    const persistedClass = declaredCardClass(persistedDetails);
+    return persistedClass !== undefined && declaredCardClass(effectiveDetails) !== persistedClass;
+}
+/**
+ * Factory-only rollout: an absent/explicitly non-executable class stays on the legacy path. For an
+ * executable card, both proofs must be structured objects with non-empty what/when/ref fields.
+ */
+export function missingExecutableDoneEvidence(persistedDetails, effectiveDetails) {
+    const isExecutable = declaredCardClass(persistedDetails) === "executable" ||
+        declaredCardClass(effectiveDetails) === "executable";
+    if (!isExecutable)
+        return [];
+    return REQUIRED_DONE_EVIDENCE_KEYS.filter((key) => !hasCompleteDoneEvidence(effectiveDetails?.[key]));
+}
+/** True when a patch needs a locked read before merging a done-gate control field. */
+export function touchesDoneInvariant(patch) {
+    return Object.keys(patch).some((key) => DONE_INVARIANT_DETAIL_KEYS.has(key));
+}
+/**
+ * Compare the required proof payload, not object identity or unrelated details. This lets callers
+ * update other metadata while an executable card remains done, but changing/removing what/when/ref
+ * requires a deliberate reopen to delivered first.
+ */
+export function executableDoneEvidenceChanged(persistedDetails, effectiveDetails) {
+    if (declaredCardClass(persistedDetails) !== "executable")
+        return false;
+    if (objectDetails(persistedDetails?.["acceptance"])) {
+        if (JSON.stringify(persistedDetails?.["acceptance"]) !== JSON.stringify(effectiveDetails?.["acceptance"]) ||
+            JSON.stringify(persistedDetails?.["done_when"]) !== JSON.stringify(effectiveDetails?.["done_when"]))
+            return true;
+    }
+    return REQUIRED_DONE_EVIDENCE_KEYS.some((evidenceKey) => DONE_EVIDENCE_FIELDS.some((field) => evidenceField(persistedDetails?.[evidenceKey], field) !==
+        evidenceField(effectiveDetails?.[evidenceKey], field)));
+}

package/dist/engine-config.d.ts

@@ -0,0 +1,65 @@
+export interface TrackConfig {
+    id: string;
+    name: string;
+}
+/** Rola instancji: nazwa wyświetlana i dokładne formy słowa (odmiana), po których reguły rozpoznają ją w tekście. */
+export interface RoleConfig {
+    name: string;
+    /** Dosłowne formy (z wielkością liter), np. „Control Room”, „CR”. Dopasowanie całych słów, bez ignorowania wielkości. */
+    forms: string[];
+}
+export interface RolesConfig {
+    /** Koordynator zasiewu (w oryginale Control Room): właściciel karty (`card_owner`) i odbiorca zobowiązania zasiewu. */
+    coordinator: RoleConfig & {
+        id: string;
+    };
+    /** Właściciel decyzji (człowiek); `genitive` trafia do markera „Efekt dla <genitive>”. */
+    owner: RoleConfig & {
+        genitive: string;
+    };
+    /** Planista: ustala intencję, zakres, design i kryteria. */
+    planner: RoleConfig;
+    /** Doradca: doradza, nie planuje i nie wykonuje. */
+    advisor: RoleConfig;
+}
+/** Domyślne role produktu — neutralne, bez nazw ról konkretnej instalacji. */
+export declare const DEFAULT_ROLES: RolesConfig;
+/** Formy wszystkich ról innych niż Worker — wejście reguły done_when (src/done-when-roles.ts). */
+export declare function nonWorkerRoleForms(roles: RolesConfig): string[];
+export interface InstanceConfig {
+    /** UUID projektu w Planerze, do którego trafia szkic. */
+    project: string;
+    /** Zweryfikowane tory projektu: kompilator przyjmuje dokładny UUID albo dokładną nazwę. */
+    tracks: TrackConfig[];
+    /** Katalog stanu instancji (bezwzględny); domyślne miejsce zapisu payloadu. */
+    stateDir: string;
+    /** Role instancji (domyślnie DEFAULT_ROLES). */
+    roles: RolesConfig;
+    /** Opcjonalny UUID projektu oczekiwań, w którym `termin` musi być datą maszynową (machineFieldProblem). */
+    expectationProject?: string;
+    /** Plik konfiguracji, z którego wczytano ustawienia (bezwzględny). */
+    configPath: string;
+}
+/** K2: dane silnika w tym samym pliku co K4; parsowanie niczego nie uruchamia. */
+export interface EngineConfig extends InstanceConfig {
+    engine: {
+        /** Repo docelowe (bezwzględne); ścieżka wejściowa względem pliku konfiguracji. */
+        repo: string;
+        /** Główna gałąź repo docelowego. */
+        branch: string;
+        /** Każda komenda to niepuste argv: program, potem argumenty; bez interpretacji powłoki. */
+        commands: {
+            test: string[];
+            lint: string[];
+            build: string[];
+        };
+        requiredChecks: string[];
+        delivery: 'delivered' | 'pr';
+    };
+}
+export declare const CONFIG_FILE = "robisie.config.json";
+export declare function parseConfig(raw: unknown, configPath: string): InstanceConfig;
+export declare function parseRoles(raw: unknown, label: string): RolesConfig;
+export declare function loadConfig(path: string): InstanceConfig;
+export declare function parseEngineConfig(raw: unknown, configPath: string): EngineConfig;
+export declare function loadEngineConfig(path: string): EngineConfig;

package/dist/engine-config.js

@@ -0,0 +1,139 @@
+// robisie.config.json — minimalna konfiguracja instancji dla kompilatora intencji (K4).
+// Zastępuje wbite w oryginał UUID projektu i torów oraz katalog zapisu (`tools/`).
+import { readFileSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, resolve } from 'node:path';
+/** Wszystkie warianty „Control Room” z oryginału (`[Cc]ontrol[ -][Rr]oom`) i skrót „CR” (tylko wielkimi). */
+const CONTROL_ROOM_FORMS = ['C', 'c'].flatMap(c => [' ', '-'].flatMap(s => ['R', 'r'].map(r => `${c}ontrol${s}${r}oom`))).concat('CR');
+const both = (...words) => words.flatMap(word => [word, word.charAt(0).toUpperCase() + word.slice(1)]);
+/** Domyślne role produktu — neutralne, bez nazw ról konkretnej instalacji. */
+export const DEFAULT_ROLES = {
+    coordinator: { id: 'control-room', name: 'Control Room', forms: CONTROL_ROOM_FORMS },
+    owner: { name: 'Właściciel', genitive: 'właściciela', forms: both('właściciel', 'właściciela', 'właścicielowi', 'właścicielem', 'właścicielu') },
+    planner: { name: 'Planista', forms: both('planista', 'planisty', 'planiście', 'planistą', 'planisto') },
+    advisor: { name: 'Doradca', forms: both('doradca', 'doradcy', 'doradcę', 'doradcą', 'doradco') },
+};
+/** Formy wszystkich ról innych niż Worker — wejście reguły done_when (src/done-when-roles.ts). */
+export function nonWorkerRoleForms(roles) {
+    return [...new Set([roles.coordinator, roles.owner, roles.planner, roles.advisor].flatMap(role => role.forms))];
+}
+export const CONFIG_FILE = 'robisie.config.json';
+function fail(path, message) {
+    throw new Error(`${path}: ${message}`);
+}
+export function parseConfig(raw, configPath) {
+    const label = configPath;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        fail(label, 'wymagany obiekt JSON');
+    const value = raw;
+    if (typeof value.project !== 'string' || !value.project.trim())
+        fail(label, 'project: wymagany niepusty UUID projektu');
+    if (!Array.isArray(value.tracks) || !value.tracks.length)
+        fail(label, 'tracks: wymagana niepusta tablica {id, name}');
+    const tracks = value.tracks.map((track, index) => {
+        if (!track || typeof track !== 'object' || Array.isArray(track))
+            fail(label, `tracks[${index}]: wymagany obiekt {id, name}`);
+        const { id, name } = track;
+        if (typeof id !== 'string' || !id.trim())
+            fail(label, `tracks[${index}].id: wymagany niepusty UUID toru`);
+        if (typeof name !== 'string' || !name.trim())
+            fail(label, `tracks[${index}].name: wymagana niepusta nazwa toru`);
+        return { id, name };
+    });
+    if (typeof value.stateDir !== 'string' || !value.stateDir.trim())
+        fail(label, 'stateDir: wymagana ścieżka katalogu stanu instancji');
+    const stateDir = isAbsolute(value.stateDir) ? value.stateDir : resolve(dirname(configPath), value.stateDir);
+    if (value.expectationProject !== undefined && (typeof value.expectationProject !== 'string' || !value.expectationProject.trim()))
+        fail(label, 'expectationProject: gdy podane — niepusty UUID projektu');
+    return {
+        project: value.project, tracks, stateDir, roles: parseRoles(value.roles, label), configPath,
+        ...(typeof value.expectationProject === 'string' ? { expectationProject: value.expectationProject } : {}),
+    };
+}
+function text(value, path, label) {
+    if (typeof value !== 'string' || !value.trim())
+        fail(label, `${path}: wymagany niepusty tekst`);
+    return value;
+}
+function role(raw, key, label) {
+    const fallback = DEFAULT_ROLES[key];
+    if (raw === undefined)
+        return fallback;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        fail(label, `roles.${key}: wymagany obiekt {name, forms}`);
+    const value = raw;
+    const name = value.name === undefined ? fallback.name : text(value.name, `roles.${key}.name`, label);
+    let forms = fallback.forms;
+    if (value.forms !== undefined) {
+        if (!Array.isArray(value.forms) || !value.forms.length)
+            fail(label, `roles.${key}.forms: wymagana niepusta tablica form słowa`);
+        forms = value.forms.map((form, index) => text(form, `roles.${key}.forms[${index}]`, label));
+    }
+    else if (value.name !== undefined)
+        forms = [name];
+    return { name, forms };
+}
+export function parseRoles(raw, label) {
+    if (raw === undefined)
+        return DEFAULT_ROLES;
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        fail(label, 'roles: wymagany obiekt {coordinator, owner, planner, advisor}');
+    const value = raw;
+    for (const key of Object.keys(value))
+        if (!(key in DEFAULT_ROLES))
+            fail(label, `roles: nieznana rola (dozwolone: ${Object.keys(DEFAULT_ROLES).join(', ')})`);
+    const coordinator = value.coordinator;
+    const owner = value.owner;
+    return {
+        coordinator: { ...role(coordinator, 'coordinator', label),
+            id: coordinator?.id === undefined ? DEFAULT_ROLES.coordinator.id : text(coordinator.id, 'roles.coordinator.id', label) },
+        owner: { ...role(owner, 'owner', label),
+            genitive: owner?.genitive !== undefined ? text(owner.genitive, 'roles.owner.genitive', label)
+                : owner?.name !== undefined ? text(owner.name, 'roles.owner.name', label) : DEFAULT_ROLES.owner.genitive },
+        planner: role(value.planner, 'planner', label),
+        advisor: role(value.advisor, 'advisor', label),
+    };
+}
+function readConfig(path) {
+    const configPath = realpathSync(resolve(path));
+    let raw;
+    try {
+        raw = JSON.parse(readFileSync(configPath, 'utf8').replace(/^\uFEFF/, ''));
+    }
+    catch (error) {
+        throw new Error(error instanceof SyntaxError ? `${configPath}: niepoprawny JSON` : `${configPath}: niepoprawny JSON: ${error.message}`);
+    }
+    return { raw, configPath };
+}
+export function loadConfig(path) {
+    const { raw, configPath } = readConfig(path);
+    return parseConfig(raw, configPath);
+}
+function textList(value, path, label) {
+    if (!Array.isArray(value) || !value.length)
+        fail(label, `${path}: wymagana niepusta tablica tekstów`);
+    return value.map((item, index) => text(item, `${path}[${index}]`, label));
+}
+export function parseEngineConfig(raw, configPath) {
+    const config = parseConfig(raw, resolve(configPath));
+    const label = config.configPath;
+    const engine = raw.engine;
+    if (!engine || typeof engine !== 'object' || Array.isArray(engine))
+        fail(label, 'engine: wymagany obiekt');
+    const value = engine;
+    const repo = resolve(dirname(label), text(value.repo, 'engine.repo', label));
+    const branch = text(value.branch, 'engine.branch', label);
+    if (!value.commands || typeof value.commands !== 'object' || Array.isArray(value.commands))
+        fail(label, 'engine.commands: wymagany obiekt {test, lint, build}');
+    const commands = value.commands;
+    const test = textList(commands.test, 'engine.commands.test', label);
+    const lint = textList(commands.lint, 'engine.commands.lint', label);
+    const build = textList(commands.build, 'engine.commands.build', label);
+    const requiredChecks = textList(value.requiredChecks, 'engine.requiredChecks', label);
+    if (value.delivery !== 'delivered' && value.delivery !== 'pr')
+        fail(label, 'engine.delivery: wymagane delivered|pr');
+    return { ...config, engine: { repo, branch, commands: { test, lint, build }, requiredChecks, delivery: value.delivery } };
+}
+export function loadEngineConfig(path) {
+    const { raw, configPath } = readConfig(path);
+    return parseEngineConfig(raw, configPath);
+}

package/dist/fsops.d.ts

@@ -0,0 +1,87 @@
+/** Role files can be restored; shared configurations lose robisie entries. Backups are permanent. */
+export type CommentStyle = "hash" | "html";
+export type Op = {
+    kind: "file";
+    path: string;
+    content: string;
+} | {
+    kind: "block";
+    path: string;
+    comment: CommentStyle;
+    body: string;
+    /** Remove conflicting server definitions before adding the managed block. */
+    clean?: (text: string) => string;
+} | {
+    kind: "json";
+    path: string;
+    keyPath: readonly string[];
+    value: unknown;
+    private: boolean;
+};
+export type Entry = {
+    kind: "file";
+    path: string;
+    backup: string | null;
+    /** Digest of the role text init wrote: uninstall removes the file only while it still holds exactly this. */
+    fingerprint?: string;
+    mode: number | null;
+} | {
+    kind: "block";
+    path: string;
+    comment: CommentStyle;
+    created: boolean;
+    backup: string | null;
+} | {
+    kind: "json";
+    path: string;
+    keyPath: string[];
+    created: boolean;
+    backup: string | null;
+    /** Digest of what init wrote (doctor). */
+    fingerprint: string;
+    mode: number | null;
+};
+export interface Store {
+    backupDir: string;
+}
+/**
+ * Name for the copy the hint tells the user to make: the first `<path>.kopia[-N]` that nothing occupies, so
+ * `cp` can never overwrite the user's own earlier copy or write through a symlink standing at that name.
+ */
+export declare function freeCopyPath(path: string): string;
+/**
+ * A private op carries the literal key (`~/.claude.json`): never written through a symlink, because its
+ * target is typically a tracked dotfile (`~/dotfiles/claude.json`) and the key would land in git history.
+ */
+export declare function refusePrivateSymlink(op: Op): void;
+/** Stable digest of a JSON value — the manifest's proof that a key still holds what init wrote (no secret stored). */
+export declare function fingerprint(value: unknown): string;
+export declare function renderBlock(comment: CommentStyle, body: string): string;
+/** Remove every complete marker block without trimming neighbouring user text. */
+export declare function stripBlock(text: string, comment: CommentStyle): string;
+export declare function hasBlock(text: string, comment: CommentStyle): boolean;
+/** Parser checks the effect independently of the byte-preserving cleaner. Never include config values in errors. */
+export declare function assertCodexChange(before: string, after: string, body?: string): void;
+/** Shared by command preflight and the actual write; validate before creating a backup. */
+export declare function prepareBlock(current: string | null, comment: CommentStyle, clean?: (text: string) => string, body?: string): string;
+/** What a path (at its write target) held before an op touched it — enough to put it back exactly. */
+export interface Captured {
+    path: string;
+    bytes: Buffer | null;
+    mode: number | null;
+}
+export declare function capture(path: string): Captured;
+/** Put a captured path back (bytes and mode), or remove it when it did not exist. A symlink is kept. */
+export declare function restore(captured: Captured): void;
+/** Apply one op. `prior` is this path's entry from an earlier init (idempotence: no second backup). */
+export declare function applyOp(op: Op, prior: Entry | undefined, store: Store): {
+    entry: Entry;
+    changed: boolean;
+};
+export declare function preserveFileStep(path: string): string;
+/** Read-only preflight for advice: do not send init into a predictable refusal. */
+export declare function checkRecovery(op: Op, prior: Entry | undefined): void;
+/** Whether what init wrote is still in place (doctor). */
+export declare function entryPresent(entry: Entry): boolean;
+/** Revert one entry. A file robisie no longer recognises is left untouched, with a warning. */
+export declare function undoEntry(entry: Entry, clean?: (text: string) => string): string | null;