felenova-backlog 0.1.0

package/README.md

@@ -0,0 +1,58 @@
+# felenova-backlog
+
+The repo-side half of Felenova's product register. One CLI plus the
+`backlog-execution` plugin for Claude Code.
+
+The register itself is a hosted service: items, their acceptance criteria and the
+lock that protects them live there, not in your repo. This package is the bridge
+between that service and the `conductor/` track you actually work in.
+
+## Install
+
+```bash
+npx felenova-backlog init --url https://your-service --project your-project
+```
+
+`init` is idempotent. It writes `backlog.config.json` (`url`, `project`,
+`conductor_dir` and nothing else), stores your personal access token at
+`~/.config/backlog/token` with mode 600, adds an `.mcp.json` entry that references
+`${BACKLOG_TOKEN}` and never a literal token, scaffolds `conductor/` without
+touching a file that already exists, appends one marked section to `CLAUDE.md`,
+and installs the skills and `/backlog:*` commands. Run it twice and the second run
+changes nothing.
+
+## Commands
+
+| Command | What it does | Role needed |
+|---|---|---|
+| `backlog doctor` | Checks the config, the token's file mode, the MCP entry, the plugin install, and that your token can see the configured project | any |
+| `backlog status` | The register's items grouped by status. Falls back to a cached view, marked `cached`, when the service is unreachable | any |
+| `backlog next` | What is ready to start: locked, unblocked, unpromoted | any |
+| `backlog promote <ID...>` | Opens a conductor track from locked items and writes `spec.md`, `plan.md` and `metadata.json` | Engineer and up |
+| `backlog matrix init <track>` | Scaffolds one QA matrix row per acceptance criterion | Engineer and up |
+| `backlog report <track> <step> <status>` | Records a loop step. The first `EXECUTE` moves the track's items to in-progress | Engineer and up |
+| `backlog sync <track>` | Re-renders `spec.md` from the current locked criteria and clears spec drift | Engineer and up |
+| `backlog ship <track>` | Closes the track with a commit and a production date | Product and up |
+| `backlog export <outDir>` | Writes a markdown snapshot of the register | any |
+
+Every refusal is rendered as one sentence. A role you do not have reads
+`ship_track is Product+; you are engineer on <project>`, not a stack trace.
+
+## The plugin
+
+`init` installs three skills and four commands into `.claude/`. The skills teach an
+agent the register's vocabulary; the commands (`/backlog:next`, `/backlog:promote`,
+`/backlog:report`, `/backlog:ship`) are thin wrappers over this CLI. The `.mcp.json`
+entry points Claude Code at the service's MCP surface, where the register's write
+tools live.
+
+## Your token
+
+Mint a personal access token in the service's web UI, then either export
+`BACKLOG_TOKEN` or let `init` save it to `~/.config/backlog/token`. It is never
+written inside a repository, and `backlog doctor` fails loudly if a token-shaped
+literal appears in a tracked file.
+
+## Licence
+
+UNLICENSED. Published for Felenova's own use; no support is implied.

package/bin/backlog.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/_core/criteria.d.ts

@@ -0,0 +1,13 @@
+import type { Item } from './schema.js';
+export declare const SPEC_FIELDS: readonly ["title", "what", "why", "criteria", "out_of_scope", "dependencies_note", "critique"];
+export type SpecField = (typeof SPEC_FIELDS)[number];
+/** §4.3 / §5.4: draft → reviewed requires documented push-back. */
+export declare function reviewCriteria(item: Item): Item;
+export declare function lockCriteria(item: Item): Item;
+/** §5.4 rule 2–3: the only backward move; reason required; version bumps; drift is the caller's flag to set on the track. */
+export declare function unlockCriteria(item: Item, reason: string): {
+    item: Item;
+    flagDrift: boolean;
+};
+/** §5.4 rule 1: locked spec fields are immutable through every surface. */
+export declare function editSpecFields(item: Item, patch: Partial<Pick<Item, SpecField>>): Item;

package/dist/_core/criteria.js

@@ -0,0 +1,44 @@
+import { LockedError, ReasonRequiredError, TransitionError } from './errors.js';
+export const SPEC_FIELDS = [
+    'title',
+    'what',
+    'why',
+    'criteria',
+    'out_of_scope',
+    'dependencies_note',
+    'critique',
+];
+/** §4.3 / §5.4: draft → reviewed requires documented push-back. */
+export function reviewCriteria(item) {
+    if (item.criteria_status !== 'draft')
+        throw new TransitionError('criteria_status', item.criteria_status, 'reviewed');
+    if (item.critique.trim() === '')
+        throw new Error(`${item.id}: critique is empty — review requires push-back`);
+    return { ...item, criteria_status: 'reviewed' };
+}
+export function lockCriteria(item) {
+    if (item.criteria_status !== 'reviewed')
+        throw new TransitionError('criteria_status', item.criteria_status, 'locked');
+    if (item.criteria.length === 0)
+        throw new Error(`${item.id}: cannot lock without at least one criterion`);
+    return { ...item, criteria_status: 'locked' };
+}
+/** §5.4 rule 2–3: the only backward move; reason required; version bumps; drift is the caller's flag to set on the track. */
+export function unlockCriteria(item, reason) {
+    if (item.criteria_status !== 'locked')
+        throw new TransitionError('criteria_status', item.criteria_status, 'reviewed');
+    if (!reason?.trim())
+        throw new ReasonRequiredError('unlock');
+    const flagDrift = item.status === 'promoted' || item.status === 'in-progress';
+    return {
+        item: { ...item, criteria_status: 'reviewed', criteria_version: item.criteria_version + 1 },
+        flagDrift,
+    };
+}
+/** §5.4 rule 1: locked spec fields are immutable through every surface. */
+export function editSpecFields(item, patch) {
+    if (item.criteria_status === 'locked')
+        throw new LockedError(item.id);
+    return { ...item, ...patch };
+}
+//# sourceMappingURL=criteria.js.map

package/dist/_core/criteria.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"criteria.js","sourceRoot":"","sources":["../src/criteria.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGhF,MAAM,CAAC,MAAM,WAAW,GAAG;IACzB,OAAO;IACP,MAAM;IACN,KAAK;IACL,UAAU;IACV,cAAc;IACd,mBAAmB;IACnB,UAAU;CACF,CAAC;AAGX,mEAAmE;AACnE,MAAM,UAAU,cAAc,CAAC,IAAU;IACvC,IAAI,IAAI,CAAC,eAAe,KAAK,OAAO;QAClC,MAAM,IAAI,eAAe,CAAC,iBAAiB,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;IACjF,IAAI,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE;QAC7B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,iDAAiD,CAAC,CAAC;IAC/E,OAAO,EAAE,GAAG,IAAI,EAAE,eAAe,EAAE,UAAU,EAAE,CAAC;AAClD,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAU;IACrC,IAAI,IAAI,CAAC,eAAe,KAAK,UAAU;QACrC,MAAM,IAAI,eAAe,CAAC,iBAAiB,EAAE,IAAI,CAAC,eAAe,EAAE,QAAQ,CAAC,CAAC;IAC/E,IAAI,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;QAC5B,MAAM,IAAI,KAAK,CAAC,GAAG,IAAI,CAAC,EAAE,8CAA8C,CAAC,CAAC;IAC5E,OAAO,EAAE,GAAG,IAAI,EAAE,eAAe,EAAE,QAAQ,EAAE,CAAC;AAChD,CAAC;AAED,6HAA6H;AAC7H,MAAM,UAAU,cAAc,CAAC,IAAU,EAAE,MAAc;IACvD,IAAI,IAAI,CAAC,eAAe,KAAK,QAAQ;QACnC,MAAM,IAAI,eAAe,CAAC,iBAAiB,EAAE,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,CAAC;IACjF,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE;QAAE,MAAM,IAAI,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC7D,MAAM,SAAS,GAAG,IAAI,CAAC,MAAM,KAAK,UAAU,IAAI,IAAI,CAAC,MAAM,KAAK,aAAa,CAAC;IAC9E,OAAO;QACL,IAAI,EAAE,EAAE,GAAG,IAAI,EAAE,eAAe,EAAE,UAAU,EAAE,gBAAgB,EAAE,IAAI,CAAC,gBAAgB,GAAG,CAAC,EAAE;QAC3F,SAAS;KACV,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,UAAU,cAAc,CAAC,IAAU,EAAE,KAAqC;IAC9E,IAAI,IAAI,CAAC,eAAe,KAAK,QAAQ;QAAE,MAAM,IAAI,WAAW,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IACtE,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,CAAC;AAC/B,CAAC"}

package/dist/_core/errors.d.ts

@@ -0,0 +1,53 @@
+import type { CriteriaStatus, Role, Suggestion } from './schema.js';
+export declare class TransitionError extends Error {
+    readonly kind: 'status' | 'criteria_status' | 'matrix_status' | 'suggestion_status';
+    readonly from: string;
+    readonly to: string;
+    constructor(kind: 'status' | 'criteria_status' | 'matrix_status' | 'suggestion_status', from: string, to: string);
+}
+export declare class PermissionError extends Error {
+    readonly role: Role;
+    readonly action: string;
+    constructor(role: Role, action: string, detail?: string);
+}
+export declare class NotLockedError extends Error {
+    readonly id: string;
+    readonly criteria_status: CriteriaStatus;
+    constructor(id: string, criteria_status: CriteriaStatus);
+}
+export declare class LockedError extends Error {
+    readonly id: string;
+    constructor(id: string);
+}
+export declare class ReasonRequiredError extends Error {
+    readonly action: string;
+    constructor(action: string);
+}
+/**
+ * A suggestion filed against an older `criteria_version`: its quoted text may no longer exist,
+ * so it is closed as `superseded` rather than applied to text it was never about
+ * (`docs/service/review-layer.md`).
+ */
+export declare class SupersededError extends Error {
+    readonly suggestion: Suggestion;
+    readonly filedAgainst: number;
+    readonly current: number;
+    /**
+     * `suggestion` is the row *already marked* `superseded`, not the stale one the caller passed
+     * in: the service has to persist that closure from its catch block, and re-deriving it there
+     * would put the transition rule in two places.
+     */
+    constructor(suggestion: Suggestion, filedAgainst: number, current: number);
+    get suggestionId(): string;
+}
+/**
+ * A value outside a closed set the schema owns (a test type, an enforcement mode). Distinct from
+ * `TransitionError`, which is about a *move* between legal states; this one is about a value that
+ * was never legal. Maps to `invalid_request`.
+ */
+export declare class InvalidValueError extends Error {
+    readonly field: string;
+    readonly value: string;
+    readonly allowed: readonly string[];
+    constructor(field: string, value: string, allowed: readonly string[]);
+}

package/dist/_core/errors.js

@@ -0,0 +1,91 @@
+export class TransitionError extends Error {
+    kind;
+    from;
+    to;
+    constructor(kind, from, to) {
+        super(`${kind}: transition ${from}→${to} is not allowed`);
+        this.kind = kind;
+        this.from = from;
+        this.to = to;
+        this.name = 'TransitionError';
+    }
+}
+export class PermissionError extends Error {
+    role;
+    action;
+    constructor(role, action, detail) {
+        super(`role ${role} may not ${action}${detail ? ` (${detail})` : ''}`);
+        this.role = role;
+        this.action = action;
+        this.name = 'PermissionError';
+    }
+}
+export class NotLockedError extends Error {
+    id;
+    criteria_status;
+    constructor(id, criteria_status) {
+        super(`${id} is not locked (criteria_status: ${criteria_status})`);
+        this.id = id;
+        this.criteria_status = criteria_status;
+        this.name = 'NotLockedError';
+    }
+}
+export class LockedError extends Error {
+    id;
+    constructor(id) {
+        super(`${id} is locked; unlock it (with a reason) before editing spec fields`);
+        this.id = id;
+        this.name = 'LockedError';
+    }
+}
+export class ReasonRequiredError extends Error {
+    action;
+    constructor(action) {
+        super(`${action} requires a non-empty reason`);
+        this.action = action;
+        this.name = 'ReasonRequiredError';
+    }
+}
+/**
+ * A suggestion filed against an older `criteria_version`: its quoted text may no longer exist,
+ * so it is closed as `superseded` rather than applied to text it was never about
+ * (`docs/service/review-layer.md`).
+ */
+export class SupersededError extends Error {
+    suggestion;
+    filedAgainst;
+    current;
+    /**
+     * `suggestion` is the row *already marked* `superseded`, not the stale one the caller passed
+     * in: the service has to persist that closure from its catch block, and re-deriving it there
+     * would put the transition rule in two places.
+     */
+    constructor(suggestion, filedAgainst, current) {
+        super(`suggestion ${suggestion.id} was filed against criteria_version ${filedAgainst}; the item is at ${current} — superseded`);
+        this.suggestion = suggestion;
+        this.filedAgainst = filedAgainst;
+        this.current = current;
+        this.name = 'SupersededError';
+    }
+    get suggestionId() {
+        return this.suggestion.id;
+    }
+}
+/**
+ * A value outside a closed set the schema owns (a test type, an enforcement mode). Distinct from
+ * `TransitionError`, which is about a *move* between legal states; this one is about a value that
+ * was never legal. Maps to `invalid_request`.
+ */
+export class InvalidValueError extends Error {
+    field;
+    value;
+    allowed;
+    constructor(field, value, allowed) {
+        super(`${field}: ${JSON.stringify(value)} is not one of ${allowed.join(', ')}`);
+        this.field = field;
+        this.value = value;
+        this.allowed = allowed;
+        this.name = 'InvalidValueError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/_core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAEA,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE7B;IACA;IACA;IAHX,YACW,IAA0E,EAC1E,IAAY,EACZ,EAAU;QAEnB,KAAK,CAAC,GAAG,IAAI,gBAAgB,IAAI,IAAI,EAAE,iBAAiB,CAAC,CAAC;QAJjD,SAAI,GAAJ,IAAI,CAAsE;QAC1E,SAAI,GAAJ,IAAI,CAAQ;QACZ,OAAE,GAAF,EAAE,CAAQ;QAGnB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAE7B;IACA;IAFX,YACW,IAAU,EACV,MAAc,EACvB,MAAe;QAEf,KAAK,CAAC,QAAQ,IAAI,YAAY,MAAM,GAAG,MAAM,CAAC,CAAC,CAAC,KAAK,MAAM,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;QAJ9D,SAAI,GAAJ,IAAI,CAAM;QACV,WAAM,GAAN,MAAM,CAAQ;QAIvB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF;AAED,MAAM,OAAO,cAAe,SAAQ,KAAK;IAE5B;IACA;IAFX,YACW,EAAU,EACV,eAA+B;QAExC,KAAK,CAAC,GAAG,EAAE,oCAAoC,eAAe,GAAG,CAAC,CAAC;QAH1D,OAAE,GAAF,EAAE,CAAQ;QACV,oBAAe,GAAf,eAAe,CAAgB;QAGxC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,OAAO,WAAY,SAAQ,KAAK;IACf;IAArB,YAAqB,EAAU;QAC7B,KAAK,CAAC,GAAG,EAAE,kEAAkE,CAAC,CAAC;QAD5D,OAAE,GAAF,EAAE,CAAQ;QAE7B,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAED,MAAM,OAAO,mBAAoB,SAAQ,KAAK;IACvB;IAArB,YAAqB,MAAc;QACjC,KAAK,CAAC,GAAG,MAAM,8BAA8B,CAAC,CAAC;QAD5B,WAAM,GAAN,MAAM,CAAQ;QAEjC,IAAI,CAAC,IAAI,GAAG,qBAAqB,CAAC;IACpC,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAO7B;IACA;IACA;IARX;;;;OAIG;IACH,YACW,UAAsB,EACtB,YAAoB,EACpB,OAAe;QAExB,KAAK,CACH,cAAc,UAAU,CAAC,EAAE,uCAAuC,YAAY,oBAAoB,OAAO,eAAe,CACzH,CAAC;QANO,eAAU,GAAV,UAAU,CAAY;QACtB,iBAAY,GAAZ,YAAY,CAAQ;QACpB,YAAO,GAAP,OAAO,CAAQ;QAKxB,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;IAED,IAAI,YAAY;QACd,OAAO,IAAI,CAAC,UAAU,CAAC,EAAE,CAAC;IAC5B,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAE/B;IACA;IACA;IAHX,YACW,KAAa,EACb,KAAa,EACb,OAA0B;QAEnC,KAAK,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,kBAAkB,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;QAJvE,UAAK,GAAL,KAAK,CAAQ;QACb,UAAK,GAAL,KAAK,CAAQ;QACb,YAAO,GAAP,OAAO,CAAmB;QAGnC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;IAClC,CAAC;CACF"}

package/dist/_core/index.d.ts

@@ -0,0 +1,24 @@
+/**
+ * @felenova/backlog-core — the single place the backlog schema, state machines,
+ * permission matrix and audit types live (PRODUCT-SPEC §9). The service, CLI
+ * and UI must import from here and nowhere else.
+ */
+export declare const CORE_VERSION = "0.3.0";
+export declare function packageName(): string;
+export * from './criteria.js';
+export * from './errors.js';
+export * from './loop.js';
+export * from './markdown/items.js';
+export * from './markdown/matrix.js';
+export * from './markdown/track.js';
+export * from './matrix.js';
+export * from './matrix-status.js';
+export * from './permissions.js';
+export * from './promote.js';
+export * from './ready.js';
+export * from './review.js';
+export * from './schema.js';
+export * from './ship.js';
+export * from './spec-diff.js';
+export * from './status.js';
+export * from './util/deep-equal.js';

package/dist/_core/index.js

@@ -0,0 +1,27 @@
+/**
+ * @felenova/backlog-core — the single place the backlog schema, state machines,
+ * permission matrix and audit types live (PRODUCT-SPEC §9). The service, CLI
+ * and UI must import from here and nowhere else.
+ */
+export const CORE_VERSION = '0.3.0';
+export function packageName() {
+    return '@felenova/backlog-core';
+}
+export * from './criteria.js';
+export * from './errors.js';
+export * from './loop.js';
+export * from './markdown/items.js';
+export * from './markdown/matrix.js';
+export * from './markdown/track.js';
+export * from './matrix.js';
+export * from './matrix-status.js';
+export * from './permissions.js';
+export * from './promote.js';
+export * from './ready.js';
+export * from './review.js';
+export * from './schema.js';
+export * from './ship.js';
+export * from './spec-diff.js';
+export * from './status.js';
+export * from './util/deep-equal.js';
+//# sourceMappingURL=index.js.map

package/dist/_core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,OAAO,CAAC;AAEpC,MAAM,UAAU,WAAW;IACzB,OAAO,wBAAwB,CAAC;AAClC,CAAC;AACD,cAAc,eAAe,CAAC;AAC9B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,qBAAqB,CAAC;AACpC,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,cAAc,CAAC;AAC7B,cAAc,YAAY,CAAC;AAC3B,cAAc,aAAa,CAAC;AAC5B,cAAc,aAAa,CAAC;AAC5B,cAAc,WAAW,CAAC;AAC1B,cAAc,gBAAgB,CAAC;AAC/B,cAAc,aAAa,CAAC;AAC5B,cAAc,sBAAsB,CAAC"}

package/dist/_core/loop.d.ts

@@ -0,0 +1,73 @@
+import { z } from 'zod';
+/**
+ * The conductor Evaluate-Loop vocabulary (`conductor/workflow.md` v3), mirrored here because
+ * `report_progress` (§6.2) is the bridge between the two registers and the service must be able
+ * to validate a step without reading the repo.
+ */
+export declare const LOOP_STEPS: readonly ["PLAN", "EVALUATE_PLAN", "EXECUTE", "EVALUATE_EXECUTION", "FIX", "COMPLETE"];
+export declare const LOOP_STATUSES: readonly ["IN_PROGRESS", "PASS", "FAIL", "COMPLETE"];
+export declare const LoopStep: z.ZodEnum<{
+    PLAN: "PLAN";
+    EVALUATE_PLAN: "EVALUATE_PLAN";
+    EXECUTE: "EXECUTE";
+    EVALUATE_EXECUTION: "EVALUATE_EXECUTION";
+    FIX: "FIX";
+    COMPLETE: "COMPLETE";
+}>;
+export declare const LoopStatus: z.ZodEnum<{
+    COMPLETE: "COMPLETE";
+    IN_PROGRESS: "IN_PROGRESS";
+    PASS: "PASS";
+    FAIL: "FAIL";
+}>;
+export type LoopStep = z.infer<typeof LoopStep>;
+export type LoopStatus = z.infer<typeof LoopStatus>;
+export declare const LoopState: z.ZodObject<{
+    step: z.ZodEnum<{
+        PLAN: "PLAN";
+        EVALUATE_PLAN: "EVALUATE_PLAN";
+        EXECUTE: "EXECUTE";
+        EVALUATE_EXECUTION: "EVALUATE_EXECUTION";
+        FIX: "FIX";
+        COMPLETE: "COMPLETE";
+    }>;
+    status: z.ZodEnum<{
+        COMPLETE: "COMPLETE";
+        IN_PROGRESS: "IN_PROGRESS";
+        PASS: "PASS";
+        FAIL: "FAIL";
+    }>;
+}, z.core.$strip>;
+export type LoopState = z.infer<typeof LoopState>;
+export declare const ProgressReport: z.ZodObject<{
+    step: z.ZodEnum<{
+        PLAN: "PLAN";
+        EVALUATE_PLAN: "EVALUATE_PLAN";
+        EXECUTE: "EXECUTE";
+        EVALUATE_EXECUTION: "EVALUATE_EXECUTION";
+        FIX: "FIX";
+        COMPLETE: "COMPLETE";
+    }>;
+    status: z.ZodEnum<{
+        COMPLETE: "COMPLETE";
+        IN_PROGRESS: "IN_PROGRESS";
+        PASS: "PASS";
+        FAIL: "FAIL";
+    }>;
+    note: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    at: z.ZodString;
+}, z.core.$strip>;
+export type ProgressReport = z.infer<typeof ProgressReport>;
+export interface TrackLoopState {
+    loop_step: LoopStep | null;
+    loop_status: LoopStatus | null;
+    last_report_at: string | null;
+}
+/**
+ * §6.2: "the first `EXECUTE` flips items to `in-progress`". `prev` is what the track already has —
+ * its last report, or the whole history when the caller has it (a `FIX → EXECUTE` bounce is then
+ * correctly *not* a first execute).
+ */
+export declare function isFirstExecute(prev: LoopState | readonly LoopState[] | null | undefined, next: LoopState): boolean;
+/** The three `tracks` columns the loop owns, derived from the reports. Latest by `at`, ties last. */
+export declare function reportsToTrackState(reports: readonly ProgressReport[]): TrackLoopState;

package/dist/_core/loop.js

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+/**
+ * The conductor Evaluate-Loop vocabulary (`conductor/workflow.md` v3), mirrored here because
+ * `report_progress` (§6.2) is the bridge between the two registers and the service must be able
+ * to validate a step without reading the repo.
+ */
+export const LOOP_STEPS = [
+    'PLAN',
+    'EVALUATE_PLAN',
+    'EXECUTE',
+    'EVALUATE_EXECUTION',
+    'FIX',
+    'COMPLETE',
+];
+export const LOOP_STATUSES = ['IN_PROGRESS', 'PASS', 'FAIL', 'COMPLETE'];
+export const LoopStep = z.enum(LOOP_STEPS);
+export const LoopStatus = z.enum(LOOP_STATUSES);
+export const LoopState = z.object({ step: LoopStep, status: LoopStatus });
+export const ProgressReport = z.object({
+    step: LoopStep,
+    status: LoopStatus,
+    note: z.string().nullable().default(null),
+    at: z.string().min(1),
+});
+/**
+ * §6.2: "the first `EXECUTE` flips items to `in-progress`". `prev` is what the track already has —
+ * its last report, or the whole history when the caller has it (a `FIX → EXECUTE` bounce is then
+ * correctly *not* a first execute).
+ */
+export function isFirstExecute(prev, next) {
+    if (next.step !== 'EXECUTE')
+        return false;
+    const prior = prev == null ? [] : Array.isArray(prev) ? prev : [prev];
+    return !prior.some((r) => r.step === 'EXECUTE');
+}
+/** The three `tracks` columns the loop owns, derived from the reports. Latest by `at`, ties last. */
+export function reportsToTrackState(reports) {
+    let latest = null;
+    for (const r of reports)
+        if (latest === null || r.at >= latest.at)
+            latest = r;
+    return latest === null
+        ? { loop_step: null, loop_status: null, last_report_at: null }
+        : { loop_step: latest.step, loop_status: latest.status, last_report_at: latest.at };
+}
+//# sourceMappingURL=loop.js.map

package/dist/_core/loop.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loop.js","sourceRoot":"","sources":["../src/loop.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG;IACxB,MAAM;IACN,eAAe;IACf,SAAS;IACT,oBAAoB;IACpB,KAAK;IACL,UAAU;CACF,CAAC;AACX,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,UAAU,CAAU,CAAC;AAElF,MAAM,CAAC,MAAM,QAAQ,GAAG,CAAC,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;AAC3C,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC;AAIhD,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC;AAG1E,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,QAAQ;IACd,MAAM,EAAE,UAAU;IAClB,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC;IACzC,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;CACtB,CAAC,CAAC;AASH;;;;GAIG;AACH,MAAM,UAAU,cAAc,CAC5B,IAAyD,EACzD,IAAe;IAEf,IAAI,IAAI,CAAC,IAAI,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC;IAC1C,MAAM,KAAK,GAAG,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAiB,CAAC,CAAC;IACnF,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC;AAClD,CAAC;AAED,qGAAqG;AACrG,MAAM,UAAU,mBAAmB,CAAC,OAAkC;IACpE,IAAI,MAAM,GAA0B,IAAI,CAAC;IACzC,KAAK,MAAM,CAAC,IAAI,OAAO;QAAE,IAAI,MAAM,KAAK,IAAI,IAAI,CAAC,CAAC,EAAE,IAAI,MAAM,CAAC,EAAE;YAAE,MAAM,GAAG,CAAC,CAAC;IAC9E,OAAO,MAAM,KAAK,IAAI;QACpB,CAAC,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,WAAW,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE;QAC9D,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE,EAAE,CAAC;AACxF,CAAC"}

package/dist/_core/markdown/items.d.ts

@@ -0,0 +1,35 @@
+import { type Criterion, Item } from '../schema.js';
+export interface ItemSource {
+    path: string;
+    frontmatterRaw: string;
+    bodyRaw: string;
+}
+export declare class ItemParseError extends Error {
+    readonly path: string;
+    readonly problems: string[];
+    constructor(path: string, problems: string[]);
+}
+/** §4.1 field order — also the canonical output order. */
+export declare const FRONTMATTER_FIELDS: readonly ["id", "title", "status", "domain", "priority", "origin", "created", "updated", "prerequisites", "blocks", "criteria_status", "revisit_when", "track", "shipped_commit", "production_date"];
+export declare const REQUIRED_SECTIONS: readonly ["What", "Why", "Acceptance criteria", "Critique / risks", "Out of scope", "Dependencies & sequencing"];
+/**
+ * Parse an `## Acceptance criteria` section into its checkboxes and the prose around them.
+ *
+ * Real items wrap a criterion over indented continuation lines and hang sub-bullets or a
+ * numbered precedence list under it (liblib-meet RP-004, RP-032): an indented line that is not
+ * itself a checkbox continues the criterion above it and is folded in with a single space.
+ * Every other non-checkbox line is section prose (liblib-meet AI-001's `*Pending — …*` note,
+ * RP-032's `### ` group headings) and is kept in `notes` so canonical export loses nothing.
+ */
+export declare function parseCriteriaSection(sectionText: string): {
+    criteria: Criterion[];
+    notes: string;
+};
+export declare function parseCriteria(sectionText: string): Criterion[];
+export declare function parseItem(text: string, path: string): {
+    item: Item;
+    source: ItemSource;
+};
+export declare function serializeItemCanonical(item: Item): string;
+export declare function itemMatchesSource(item: Item, source: ItemSource): boolean;
+export declare function serializeItem(item: Item, source?: ItemSource): string;