felenova-backlog 0.1.0

package/dist/_core/matrix-status.js

@@ -0,0 +1,31 @@
+import { ReasonRequiredError, TransitionError } from './errors.js';
+/** §5.6: one-way, one step at a time; ⏭️ from any state with a reason. */
+export const MATRIX_FORWARD = ['☐', '🟡', '✅', '🔬', '🚀'];
+export function canTransitionMatrix(from, to) {
+    const f = from ?? '☐';
+    if (to === '⏭️')
+        return f !== '⏭️';
+    const i = MATRIX_FORWARD.indexOf(f);
+    const j = MATRIX_FORWARD.indexOf(to);
+    return i >= 0 && j === i + 1;
+}
+export function transitionMatrixRow(row, to, opts = {}) {
+    if (!canTransitionMatrix(row.status, to))
+        throw new TransitionError('matrix_status', row.status ?? '☐', to);
+    if (to === '⏭️') {
+        if (!opts.reason?.trim())
+            throw new ReasonRequiredError('skip');
+        const tag = `⏭️ ${opts.reason.trim()}`;
+        return { ...row, status: to, notes: row.notes ? `${row.notes} — ${tag}` : tag };
+    }
+    return { ...row, status: to };
+}
+/** Which §3.1 action a target status needs — Engineers implement, QA verifies, Product+ skips. */
+export function matrixActionFor(to) {
+    if (to === '⏭️')
+        return 'matrix_skip';
+    if (to === '🔬' || to === '🚀')
+        return 'matrix_verify';
+    return 'matrix_mark_implemented';
+}
+//# sourceMappingURL=matrix-status.js.map

package/dist/_core/matrix-status.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix-status.js","sourceRoot":"","sources":["../src/matrix-status.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAGnE,0EAA0E;AAC1E,MAAM,CAAC,MAAM,cAAc,GAA4B,CAAC,GAAG,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,EAAE,IAAI,CAAC,CAAC;AAEpF,MAAM,UAAU,mBAAmB,CAAC,IAAyB,EAAE,EAAgB;IAC7E,MAAM,CAAC,GAAG,IAAI,IAAI,GAAG,CAAC;IACtB,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,CAAC,KAAK,IAAI,CAAC;IACnC,MAAM,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC;IACpC,MAAM,CAAC,GAAG,cAAc,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IACrC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;AAC/B,CAAC;AAED,MAAM,UAAU,mBAAmB,CACjC,GAAc,EACd,EAAgB,EAChB,OAA4B,EAAE;IAE9B,IAAI,CAAC,mBAAmB,CAAC,GAAG,CAAC,MAAM,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,eAAe,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,IAAI,GAAG,EAAE,EAAE,CAAC,CAAC;IACpE,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC;QAChB,IAAI,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,EAAE;YAAE,MAAM,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAC;QAChE,MAAM,GAAG,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC;QACvC,OAAO,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,KAAK,MAAM,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,EAAE,CAAC;IAClF,CAAC;IACD,OAAO,EAAE,GAAG,GAAG,EAAE,MAAM,EAAE,EAAE,EAAE,CAAC;AAChC,CAAC;AAED,kGAAkG;AAClG,MAAM,UAAU,eAAe,CAC7B,EAAgB;IAEhB,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,aAAa,CAAC;IACtC,IAAI,EAAE,KAAK,IAAI,IAAI,EAAE,KAAK,IAAI;QAAE,OAAO,eAAe,CAAC;IACvD,OAAO,yBAAyB,CAAC;AACnC,CAAC"}

package/dist/_core/matrix.d.ts

@@ -0,0 +1,46 @@
+import { type Item, type MatrixRowRecord, type MatrixRowRef, type NewMatrixRow, type QaQueue, type TestType } from './schema.js';
+/**
+ * Scaffold `☐` rows for every criterion that has no live row. Any status but `⏭️` is live
+ * outright; a `⏭️` row is live for exactly the text it was skipped against — a deliberate
+ * "we will not verify this" is a decision about *that* wording, so it keeps covering its
+ * criterion while the wording stands and stops the moment the criterion is rewritten (a
+ * superseded row is handed over with a text that no longer matches, and so covers nothing).
+ * `M` is 1 + the highest ever seen for the `(item, ac)`, superseded rows included — ids are
+ * never reused, so a re-scaffold after supersession yields `.M2`.
+ */
+export declare function scaffoldMatrix(items: readonly Item[], existing: readonly MatrixRowRef[]): NewMatrixRow[];
+/**
+ * DECISION-018: what `sync_track` does when criteria moved underneath a matrix. A row is superseded
+ * when its item has advanced past the version the row quotes **and** the criterion it quotes is
+ * gone or now reads differently. Both halves matter: a version bump that did not touch this
+ * criterion leaves the row valid, and identical text under a newer version is not drift.
+ *
+ * A `🚀` row is never superseded — it was verified in production, and that fact does not expire —
+ * and a `⏭️` row is already closed. `add` is the scaffold over whatever is left uncovered once the
+ * supersessions are applied.
+ */
+export declare function supersedeMatrix(items: readonly Item[], rows: readonly MatrixRowRecord[]): {
+    supersede: MatrixRowRecord[];
+    add: NewMatrixRow[];
+};
+/**
+ * §5.6 ship gate: a row that has not reached `🔬` (or been skipped) is unverified work. `strict`
+ * refuses the ship, `permissive` reports it and lets it through.
+ *
+ * An empty matrix is the finding only under `strict`, where there is nothing to have verified.
+ * Under `permissive` a track that never ran `matrix_init` passes **silently**: it has no
+ * unverified rows, and warning on every such ship would teach callers to ignore `warnings`.
+ */
+export declare function matrixGate(rows: readonly MatrixRowRecord[], enforcement: 'strict' | 'permissive'): {
+    ok: boolean;
+    blocking: string[];
+    warnings: string[];
+};
+/**
+ * DECISION-020: "what is waiting on QA", grouped `track → environment → rows`. `✅` is implemented
+ * and waiting for staging verification, `🔬` is verified on staging and waiting for production.
+ * Every other status is somebody else's queue.
+ */
+export declare function qaQueue(rows: readonly MatrixRowRecord[]): QaQueue;
+/** Test types are a closed set and case-sensitive — `'unit'` is a typo, not a synonym. */
+export declare function assertTestType(value: string): TestType;

package/dist/_core/matrix.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"matrix.js","sourceRoot":"","sources":["../src/matrix.ts"],"names":[],"mappings":"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"}

package/dist/_core/permissions.d.ts

@@ -0,0 +1,14 @@
+import type { CriteriaStatus, Role } from './schema.js';
+/** The rows of PRODUCT-SPEC §3.1. `edit_spec` is the context-dependent composite (draft vs reviewed). */
+export declare const ACTIONS: readonly ["read", "create_item", "edit_spec_draft", "review_criteria", "edit_spec_reviewed", "lock_criteria", "unlock_criteria", "schedule_item", "set_priority", "reject_item", "promote_items", "report_progress", "add_follow_up", "suggest_change", "resolve_suggestion", "withdraw_own_suggestion", "matrix_edit_rows", "matrix_mark_implemented", "matrix_verify", "matrix_skip", "matrix_set_enforcement", "ship_track", "add_comment", "manage_org", "manage_own_tokens"];
+export type Action = (typeof ACTIONS)[number] | 'edit_spec';
+type Row = Record<Role, boolean>;
+export declare const PERMISSIONS: Record<(typeof ACTIONS)[number], Row>;
+export declare const MUTATING_ACTIONS: ReadonlySet<Action>;
+export interface PermissionContext {
+    criteria_status?: CriteriaStatus;
+    token_scope?: 'full' | 'read_only';
+}
+export declare function can(role: Role, action: Action, ctx?: PermissionContext): boolean;
+export declare function assertCan(role: Role, action: Action, ctx?: PermissionContext): void;
+export {};

package/dist/_core/permissions.js

@@ -0,0 +1,87 @@
+import { PermissionError } from './errors.js';
+/** The rows of PRODUCT-SPEC §3.1. `edit_spec` is the context-dependent composite (draft vs reviewed). */
+export const ACTIONS = [
+    'read',
+    'create_item',
+    'edit_spec_draft',
+    'review_criteria',
+    'edit_spec_reviewed',
+    'lock_criteria',
+    'unlock_criteria',
+    'schedule_item',
+    'set_priority',
+    'reject_item',
+    'promote_items',
+    'report_progress',
+    'add_follow_up',
+    'suggest_change',
+    'resolve_suggestion',
+    'withdraw_own_suggestion',
+    'matrix_edit_rows',
+    'matrix_mark_implemented',
+    'matrix_verify',
+    'matrix_skip',
+    'matrix_set_enforcement',
+    'ship_track',
+    'add_comment',
+    'manage_org',
+    'manage_own_tokens',
+];
+const r = (owner, product, engineer, qa, viewer) => ({ owner, product, engineer, qa, viewer });
+export const PERMISSIONS = {
+    read: r(true, true, true, true, true),
+    create_item: r(true, true, true, true, false),
+    edit_spec_draft: r(true, true, true, true, false),
+    review_criteria: r(true, true, true, true, false),
+    edit_spec_reviewed: r(true, true, false, false, false),
+    lock_criteria: r(true, true, false, false, false),
+    unlock_criteria: r(true, true, false, false, false),
+    schedule_item: r(true, true, false, false, false),
+    set_priority: r(true, true, false, false, false),
+    reject_item: r(true, true, false, false, false),
+    promote_items: r(true, true, true, false, false),
+    report_progress: r(true, true, true, false, false),
+    add_follow_up: r(true, true, true, true, false),
+    suggest_change: r(true, true, true, true, false),
+    // Author scoping ("own") is an identity check the matrix has no vocabulary for; `review.ts`
+    // adds it on top of this row (docs/service/review-layer.md).
+    resolve_suggestion: r(true, true, false, false, false),
+    withdraw_own_suggestion: r(true, true, true, true, false),
+    matrix_edit_rows: r(true, true, true, true, false),
+    matrix_mark_implemented: r(true, true, true, false, false),
+    matrix_verify: r(true, true, false, true, false),
+    matrix_skip: r(true, true, false, false, false),
+    matrix_set_enforcement: r(true, true, false, false, false),
+    ship_track: r(true, true, false, false, false),
+    add_comment: r(true, true, true, true, false),
+    manage_org: r(true, false, false, false, false),
+    manage_own_tokens: r(true, true, true, true, true),
+};
+// `manage_own_tokens` is deliberately in here: a `read_only` token must not mint or revoke tokens.
+export const MUTATING_ACTIONS = new Set([
+    ...ACTIONS.filter((a) => a !== 'read'),
+    'edit_spec',
+]);
+export function can(role, action, ctx = {}) {
+    if (ctx.token_scope === 'read_only' && MUTATING_ACTIONS.has(action))
+        return false;
+    if (action === 'edit_spec') {
+        switch (ctx.criteria_status) {
+            case 'draft':
+                return PERMISSIONS.edit_spec_draft[role];
+            case 'reviewed':
+                return PERMISSIONS.edit_spec_reviewed[role];
+            case 'locked':
+                return false; // §5.4 rule 1 — nobody edits a locked spec; unlock first
+            default:
+                return false; // caller must say which tier the item is in
+        }
+    }
+    return PERMISSIONS[action][role];
+}
+export function assertCan(role, action, ctx = {}) {
+    if (!can(role, action, ctx)) {
+        throw new PermissionError(role, action, ctx.criteria_status ? `criteria_status: ${ctx.criteria_status}` : undefined);
+    }
+}
+//# sourceMappingURL=permissions.js.map

package/dist/_core/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"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"}

package/dist/_core/promote.d.ts

@@ -0,0 +1,20 @@
+import type { Criterion, Item, Track } from './schema.js';
+export interface PromotePayload {
+    track: Track;
+    items: Item[];
+    spec: Array<{
+        id: string;
+        title: string;
+        criteria: Criterion[];
+        out_of_scope: string;
+        criteria_version: number;
+    }>;
+}
+/** §5.4 rule 5 + §6.2 promote_items: refuses unless every item is locked; no --force exists. */
+export declare function promoteItems(items: Item[], opts: {
+    slug: string;
+    type: string;
+}): PromotePayload;
+/** Ported from liblib-meet scripts/backlog/lib/items.ts — same output for the same input. */
+export declare function slugify(title: string): string;
+export declare function buildTrackSlug(primaryTitle: string, date: string): string;

package/dist/_core/promote.js

@@ -0,0 +1,47 @@
+import { NotLockedError } from './errors.js';
+import { transitionStatus } from './status.js';
+/** §5.4 rule 5 + §6.2 promote_items: refuses unless every item is locked; no --force exists. */
+export function promoteItems(items, opts) {
+    for (const it of items)
+        if (it.criteria_status !== 'locked')
+            throw new NotLockedError(it.id, it.criteria_status);
+    const promoted = items.map((it) => {
+        const staged = it.status === 'backlog' ? transitionStatus(it, 'scheduled') : it;
+        return { ...transitionStatus(staged, 'promoted'), track: opts.slug };
+    });
+    const track = {
+        slug: opts.slug,
+        type: opts.type,
+        backlog_ids: promoted.map((i) => i.id),
+        follow_up_backlog: [],
+        qa_doc: null,
+        qa_enforcement: 'permissive',
+        spec_drift: false,
+        shipment: null,
+    };
+    return {
+        track,
+        items: promoted,
+        spec: promoted.map((i) => ({
+            id: i.id,
+            title: i.title,
+            criteria: i.criteria,
+            out_of_scope: i.out_of_scope,
+            criteria_version: i.criteria_version,
+        })),
+    };
+}
+/** Ported from liblib-meet scripts/backlog/lib/items.ts — same output for the same input. */
+export function slugify(title) {
+    return title
+        .toLowerCase()
+        .normalize('NFKD')
+        .replace(/[̀-ͯ]/g, '')
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 60);
+}
+export function buildTrackSlug(primaryTitle, date) {
+    return `${slugify(primaryTitle)}_${date.replace(/-/g, '')}`;
+}
+//# sourceMappingURL=promote.js.map

package/dist/_core/promote.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"promote.js","sourceRoot":"","sources":["../src/promote.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAE7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAc/C,gGAAgG;AAChG,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,IAAoC;IAC9E,KAAK,MAAM,EAAE,IAAI,KAAK;QACpB,IAAI,EAAE,CAAC,eAAe,KAAK,QAAQ;YAAE,MAAM,IAAI,cAAc,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,eAAe,CAAC,CAAC;IAC3F,MAAM,QAAQ,GAAG,KAAK,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,EAAE;QAChC,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,gBAAgB,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QAChF,OAAO,EAAE,GAAG,gBAAgB,CAAC,MAAM,EAAE,UAAU,CAAC,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC;IACvE,CAAC,CAAC,CAAC;IACH,MAAM,KAAK,GAAU;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,WAAW,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtC,iBAAiB,EAAE,EAAE;QACrB,MAAM,EAAE,IAAI;QACZ,cAAc,EAAE,YAAY;QAC5B,UAAU,EAAE,KAAK;QACjB,QAAQ,EAAE,IAAI;KACf,CAAC;IACF,OAAO;QACL,KAAK;QACL,KAAK,EAAE,QAAQ;QACf,IAAI,EAAE,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;YACzB,EAAE,EAAE,CAAC,CAAC,EAAE;YACR,KAAK,EAAE,CAAC,CAAC,KAAK;YACd,QAAQ,EAAE,CAAC,CAAC,QAAQ;YACpB,YAAY,EAAE,CAAC,CAAC,YAAY;YAC5B,gBAAgB,EAAE,CAAC,CAAC,gBAAgB;SACrC,CAAC,CAAC;KACJ,CAAC;AACJ,CAAC;AAED,6FAA6F;AAC7F,MAAM,UAAU,OAAO,CAAC,KAAa;IACnC,OAAO,KAAK;SACT,WAAW,EAAE;SACb,SAAS,CAAC,MAAM,CAAC;SACjB,OAAO,CAAC,QAAQ,EAAE,EAAE,CAAC;SACrB,OAAO,CAAC,aAAa,EAAE,GAAG,CAAC;SAC3B,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC;SACvB,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;AAClB,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,YAAoB,EAAE,IAAY;IAC/D,OAAO,GAAG,OAAO,CAAC,YAAY,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC,EAAE,CAAC;AAC9D,CAAC"}

package/dist/_core/ready.d.ts

@@ -0,0 +1,8 @@
+import type { Item } from './schema.js';
+/** §6.2 `next_ready`: locked, not yet promoted, and every prerequisite already shipped. */
+export declare function isReady(item: Item, shippedRefs: ReadonlySet<string>): boolean;
+/**
+ * The "what should I work on" answer: ready items ranked by priority, then age, then id.
+ * Pure — the input array is never reordered in place.
+ */
+export declare function nextReady(items: readonly Item[], shippedRefs: ReadonlySet<string>): Item[];

package/dist/_core/ready.js

@@ -0,0 +1,22 @@
+/** `P0` first. Sorting on the string would put `P0` first too, but only by accident. */
+const PRIORITY_RANK = { P0: 0, P1: 1, P2: 2, P3: 3, P4: 4 };
+/** §6.2 `next_ready`: locked, not yet promoted, and every prerequisite already shipped. */
+export function isReady(item, shippedRefs) {
+    if (item.criteria_status !== 'locked')
+        return false;
+    if (item.status !== 'backlog' && item.status !== 'scheduled')
+        return false;
+    return item.prerequisites.every((ref) => shippedRefs.has(ref));
+}
+/**
+ * The "what should I work on" answer: ready items ranked by priority, then age, then id.
+ * Pure — the input array is never reordered in place.
+ */
+export function nextReady(items, shippedRefs) {
+    return items
+        .filter((it) => isReady(it, shippedRefs))
+        .sort((a, b) => PRIORITY_RANK[a.priority] - PRIORITY_RANK[b.priority] ||
+        a.created.localeCompare(b.created) ||
+        a.id.localeCompare(b.id));
+}
+//# sourceMappingURL=ready.js.map

package/dist/_core/ready.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ready.js","sourceRoot":"","sources":["../src/ready.ts"],"names":[],"mappings":"AAEA,wFAAwF;AACxF,MAAM,aAAa,GAA6B,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC;AAEtF,2FAA2F;AAC3F,MAAM,UAAU,OAAO,CAAC,IAAU,EAAE,WAAgC;IAClE,IAAI,IAAI,CAAC,eAAe,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,IAAI,CAAC,MAAM,KAAK,SAAS,IAAI,IAAI,CAAC,MAAM,KAAK,WAAW;QAAE,OAAO,KAAK,CAAC;IAC3E,OAAO,IAAI,CAAC,aAAa,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;AACjE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,SAAS,CAAC,KAAsB,EAAE,WAAgC;IAChF,OAAO,KAAK;SACT,MAAM,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,EAAE,WAAW,CAAC,CAAC;SACxC,IAAI,CACH,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CACP,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC,GAAG,aAAa,CAAC,CAAC,CAAC,QAAQ,CAAC;QACrD,CAAC,CAAC,OAAO,CAAC,aAAa,CAAC,CAAC,CAAC,OAAO,CAAC;QAClC,CAAC,CAAC,EAAE,CAAC,aAAa,CAAC,CAAC,CAAC,EAAE,CAAC,CAC3B,CAAC;AACN,CAAC"}

package/dist/_core/review.d.ts

@@ -0,0 +1,49 @@
+import { type SpecField } from './criteria.js';
+import type { CommentTarget, Item, Revision, Role, Suggestion, SuggestionStatus } from './schema.js';
+export interface Actor {
+    id: string;
+    role: Role;
+}
+/** One-way, in the house style of `status.ts`: nothing leaves a resolved suggestion. */
+export declare const SUGGESTION_TRANSITIONS: ReadonlyArray<readonly [SuggestionStatus, SuggestionStatus]>;
+export declare function canTransitionSuggestion(from: SuggestionStatus, to: SuggestionStatus): boolean;
+export interface FileSuggestionInput {
+    id: string;
+    text: string;
+    rationale: string;
+    target?: CommentTarget;
+    created_at: string;
+}
+/**
+ * A suggestion is only meaningful on a **locked** item: on `draft` Engineer and QA can just edit,
+ * on `reviewed` they comment. Filing against anything else is refused with the current status.
+ */
+export declare function fileSuggestion(item: Item, input: FileSuggestionInput, actor: Actor): Suggestion;
+export type SuggestionResolution = {
+    accept: true;
+    patch: Partial<Pick<Item, SpecField>>;
+    note?: string;
+} | {
+    accept: false;
+    note: string;
+};
+export interface ResolveSuggestionResult {
+    item: Item;
+    suggestion: Suggestion;
+    revision: Revision | null;
+    /** The caller sets `spec_drift` on the track; core stays pure, as `unlockCriteria` already does. */
+    flagDrift: boolean;
+}
+/** §5.4 rule 4 — accept (unlock → edit → re-lock as one action) or decline with a note. */
+export declare function resolveSuggestion(item: Item, suggestion: Suggestion, resolution: SuggestionResolution, actor: Actor, opts: {
+    now: string;
+}): ResolveSuggestionResult;
+/** Mechanical, not a judgement call: the item's version moved past the one this was filed against. */
+export declare function supersede(suggestion: Suggestion, now: string): Suggestion;
+/**
+ * Author-scoped: the matrix row says *may withdraw a suggestion*, the identity check says *own*.
+ * The Owner is excepted — someone has to be able to close a departed author's suggestion.
+ */
+export declare function withdrawSuggestion(suggestion: Suggestion, actor: Actor, opts: {
+    now: string;
+}): Suggestion;

package/dist/_core/review.js

@@ -0,0 +1,137 @@
+import { SPEC_FIELDS } from './criteria.js';
+import { NotLockedError, PermissionError, ReasonRequiredError, SupersededError, TransitionError, } from './errors.js';
+import { assertCan } from './permissions.js';
+import { specDiffFields } from './spec-diff.js';
+/** One-way, in the house style of `status.ts`: nothing leaves a resolved suggestion. */
+export const SUGGESTION_TRANSITIONS = [
+    ['open', 'accepted'],
+    ['open', 'declined'],
+    ['open', 'withdrawn'],
+    ['open', 'superseded'],
+];
+export function canTransitionSuggestion(from, to) {
+    return SUGGESTION_TRANSITIONS.some(([f, t]) => f === from && t === to);
+}
+function assertOpen(suggestion, to) {
+    if (!canTransitionSuggestion(suggestion.status, to))
+        throw new TransitionError('suggestion_status', suggestion.status, to);
+}
+/**
+ * A suggestion is only meaningful on a **locked** item: on `draft` Engineer and QA can just edit,
+ * on `reviewed` they comment. Filing against anything else is refused with the current status.
+ */
+export function fileSuggestion(item, input, actor) {
+    assertCan(actor.role, 'suggest_change');
+    if (item.criteria_status !== 'locked')
+        throw new NotLockedError(item.id, item.criteria_status);
+    if (!input.text.trim())
+        throw new ReasonRequiredError('suggest_change (text)');
+    if (!input.rationale.trim())
+        throw new ReasonRequiredError('suggest_change (rationale)');
+    return {
+        id: input.id,
+        item_id: item.id,
+        criteria_version: item.criteria_version,
+        target: input.target ?? { kind: 'item' },
+        text: input.text,
+        rationale: input.rationale,
+        status: 'open',
+        created_by: actor.id,
+        created_at: input.created_at,
+        resolved_by: null,
+        resolved_at: null,
+        resolution_note: null,
+    };
+}
+const SPEC_FIELD_SET = new Set(SPEC_FIELDS);
+/**
+ * The locked-bypassing edit. `editSpecFields` refuses a locked item and must keep refusing it —
+ * an accepted suggestion is a *controlled amendment*, not an unlock: Product has already read the
+ * exact proposed text and ruled on it, so the item comes out `locked` with a higher version.
+ */
+function applySpecPatch(item, patch) {
+    for (const key of Object.keys(patch)) {
+        if (!SPEC_FIELD_SET.has(key))
+            throw new Error(`${item.id}: ${key} is not a spec field; a suggestion may only change ${SPEC_FIELDS.join(', ')}`);
+    }
+    return { ...item, ...patch, criteria_version: item.criteria_version + 1 };
+}
+/** §5.4 rule 4 — accept (unlock → edit → re-lock as one action) or decline with a note. */
+export function resolveSuggestion(item, suggestion, resolution, actor, opts) {
+    assertCan(actor.role, 'resolve_suggestion');
+    const { now } = opts;
+    const to = resolution.accept ? 'accepted' : 'declined';
+    if (suggestion.item_id !== item.id)
+        throw new Error(`suggestion ${suggestion.id} was filed against ${suggestion.item_id}, not ${item.id}`);
+    assertOpen(suggestion, to);
+    if (suggestion.criteria_version !== item.criteria_version) {
+        // The closure travels with the refusal: the caller persists `err.suggestion` and rethrows.
+        throw new SupersededError(supersede(suggestion, now), suggestion.criteria_version, item.criteria_version);
+    }
+    if (item.criteria_status !== 'locked')
+        throw new NotLockedError(item.id, item.criteria_status);
+    const note = resolution.note?.trim() ?? '';
+    if (!resolution.accept) {
+        if (!note)
+            throw new ReasonRequiredError('decline a suggestion');
+        return {
+            item,
+            suggestion: {
+                ...suggestion,
+                status: 'declined',
+                resolved_by: actor.id,
+                resolved_at: now,
+                resolution_note: note,
+            },
+            revision: null,
+            flagDrift: false,
+        };
+    }
+    const next = applySpecPatch(item, resolution.patch);
+    const revision = {
+        id: null,
+        item_id: item.id,
+        version_before: item.criteria_version,
+        version_after: next.criteria_version,
+        fields: specDiffFields(item, next),
+        source: 'suggestion_accept',
+        reason: note ? `${suggestion.rationale} — ${note}` : suggestion.rationale,
+        changed_by: actor.id,
+        changed_at: now,
+    };
+    return {
+        item: next,
+        suggestion: {
+            ...suggestion,
+            status: 'accepted',
+            resolved_by: actor.id,
+            resolved_at: now,
+            resolution_note: note || null,
+        },
+        revision,
+        // Same rule as `unlockCriteria`: the version moved under a track that is already building.
+        flagDrift: next.status === 'promoted' || next.status === 'in-progress',
+    };
+}
+/** Mechanical, not a judgement call: the item's version moved past the one this was filed against. */
+export function supersede(suggestion, now) {
+    assertOpen(suggestion, 'superseded');
+    return { ...suggestion, status: 'superseded', resolved_at: now, resolution_note: null };
+}
+/**
+ * Author-scoped: the matrix row says *may withdraw a suggestion*, the identity check says *own*.
+ * The Owner is excepted — someone has to be able to close a departed author's suggestion.
+ */
+export function withdrawSuggestion(suggestion, actor, opts) {
+    assertCan(actor.role, 'withdraw_own_suggestion');
+    if (suggestion.created_by !== actor.id && actor.role !== 'owner')
+        throw new PermissionError(actor.role, 'withdraw_own_suggestion', 'not the author');
+    assertOpen(suggestion, 'withdrawn');
+    return {
+        ...suggestion,
+        status: 'withdrawn',
+        resolved_by: actor.id,
+        resolved_at: opts.now,
+    };
+}
+//# sourceMappingURL=review.js.map

package/dist/_core/review.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"review.js","sourceRoot":"","sources":["../src/review.ts"],"names":[],"mappings":"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"}