@cleocode/core 2026.9.8 → 2026.9.9

package/dist/tasks/acceptance-input.js

@@ -0,0 +1,259 @@
+/**
+ * Canonical task acceptance input normalization, shared by CLI parsing and writes.
+ * @task T12197
+ */
+import { ExitCode } from '@cleocode/contracts';
+import { CleoError } from '../errors.js';
+/**
+ * Validate and normalize an explicitly supplied acceptance array.
+ *
+ * @remarks
+ * Absent input remains undefined. String entries are trimmed and blank strings
+ * are dropped; an explicitly empty result remains [] so update can clear it.
+ * Entries stay literal, including pipes and quoted unions. Nonstring entries
+ * reject the entire input before any task mutation.
+ *
+ * @param acceptance - Optional array of literal string criteria supplied by the caller.
+ * @returns Trimmed nonblank criteria, including an explicit empty array; undefined for absent input.
+ * @throws CleoError when the input is not an array or includes a nonstring entry.
+ * @example
+ * ```typescript
+ * const criteria = [' literal a|b ', '', ' verify output '];
+ * normalizeAcceptance(criteria);
+ * // ['literal a|b', 'verify output']
+ * normalizeAcceptance([]); // [] requests an explicit clear on update
+ * ```
+ */
+export function normalizeAcceptance(acceptance) {
+    if (acceptance === undefined)
+        return undefined;
+    if (!Array.isArray(acceptance)) {
+        throw new CleoError(ExitCode.VALIDATION_ERROR, 'Acceptance criteria must be an array of strings');
+    }
+    const normalized = [];
+    for (const [index, criterion] of acceptance.entries()) {
+        if (typeof criterion !== 'string') {
+            throw new CleoError(ExitCode.VALIDATION_ERROR, `Acceptance criterion ${index + 1} must be a string`);
+        }
+        const text = criterion.trim();
+        if (text)
+            normalized.push(text);
+    }
+    return normalized;
+}
+/**
+ * Find the previous non-whitespace character in `s` searching backwards from
+ * the end. Returns the empty string when `s` is empty or all-whitespace.
+ *
+ * Used by `splitAcceptance` to detect the string-union continuation rule
+ * (gh-409): a `|` between a closing quote and an opening quote is NOT a split.
+ *
+ * @internal
+ */
+function lastNonWsChar(s) {
+    for (let k = s.length - 1; k >= 0; k--) {
+        const c = s[k];
+        if (c !== ' ' && c !== '\t' && c !== '\n' && c !== '\r')
+            return c;
+    }
+    return '';
+}
+/**
+ * Find the next non-whitespace character in `s` starting at index `start`.
+ * Returns the empty string when no non-whitespace remains.
+ *
+ * @internal
+ */
+function nextNonWsChar(s, start) {
+    for (let k = start; k < s.length; k++) {
+        const c = s[k];
+        if (c !== ' ' && c !== '\t' && c !== '\n' && c !== '\r')
+            return c;
+    }
+    return '';
+}
+/**
+ * Bracket+quote+escape-aware tokenizer for pipe-delimited acceptance criteria.
+ *
+ * Splits `input` on the top-level `delim` character ONLY — pipes inside
+ * brackets/parens/braces or inside single-/double-quoted strings are preserved
+ * as part of the current token. A backslash at depth 0 (outside any quote)
+ * immediately preceding a delimiter escapes it (treats it as a literal
+ * character in the current token).
+ *
+ * Used by `parseAcceptanceCriteria` to fix the data-corruption bug where
+ * naive `String.split('|')` shredded criteria containing `ENUM (a|b|c)` or
+ * quoted string-unions like `'realtime-token'|'batch'`.
+ *
+ * Rules:
+ * - Quotes: `"` and `'` open a quote-context; the matching close char ends it.
+ *   Inside a quote, `|`, brackets, and escape sequences are passed through
+ *   literally (the only thing that exits the quote is the matching close).
+ * - Brackets: `(`, `[`, `{` increase depth; `)`, `]`, `}` decrease (clamped
+ *   at 0 — unbalanced closing brackets are tolerated, never throw).
+ * - Escape: `\|` at depth 0 with no active quote → literal `|` in the token.
+ * - Delimiter: `|` is a split point ONLY when depth === 0 AND no active quote
+ *   AND it does NOT join two quoted spans. A `|` whose preceding non-whitespace
+ *   char in `buf` is a closing quote AND whose next non-whitespace char in
+ *   `input` is an opening quote is treated as a continuation (the entire
+ *   `'a'|'b'` or `"a"|"b"` expression stays as one token). This is the
+ *   gh-409 "string-union" rule used by T239.
+ * - Trim: each emitted token is trimmed; empty tokens (after trim) are dropped.
+ * - Defensive: unbalanced opening brackets do NOT throw; the unterminated
+ *   tail is emitted as a single trailing token (no infinite loop possible —
+ *   the loop is bounded by `input.length`).
+ *
+ * @param input - Raw delimiter-separated string
+ * @param delim - Delimiter character (single char; default `|`)
+ * @returns Array of trimmed, non-empty tokens
+ *
+ * @internal
+ * @bug https://github.com/kryptobaseddev/cleo/issues/409
+ * @task T9839
+ */
+function splitAcceptance(input, delim = '|') {
+    const out = [];
+    let buf = '';
+    let depth = 0;
+    let quote = null;
+    let i = 0;
+    while (i < input.length) {
+        const ch = input[i];
+        // Escape: \| at depth 0 with no active quote → literal | in the token.
+        if (ch === '\\' && input[i + 1] === delim && depth === 0 && quote === null) {
+            buf += delim;
+            i += 2;
+            continue;
+        }
+        if (quote !== null) {
+            // Inside a quote: only the matching close char exits.
+            if (ch === quote)
+                quote = null;
+            buf += ch;
+        }
+        else if ((ch === '"' || ch === "'") &&
+            input.indexOf(ch, i + 1) !== -1 &&
+            // An apostrophe INSIDE or AFTER a word is never a quote opener. `doesn't`
+            // and `user's` are prose; `'batch'` is a quoted span. The discriminator is
+            // the preceding character, and it must be an ALLOWLIST rather than "not
+            // alphanumeric": `stash@{2}'s correction` is possessive even though `}` is
+            // not a letter or digit, and the not-alphanumeric form admitted it as a
+            // quote opener. With a second such possessive later in the string the
+            // quotes balance, the lookahead below is satisfied, and the whole span
+            // between them merges — supplied 5, parsed 4 (gh#1339).
+            //
+            // A quote that really opens a span sits at a token boundary: start of
+            // input, whitespace, the delimiter itself, or an opening bracket. Nothing
+            // else. A closing bracket, a letter, a digit or a period before it means
+            // prose.
+            /^$|[\s|([{,=:]$/.test(buf.slice(-1))) {
+            // gh#1321 — enter a quote context ONLY when a matching close exists later.
+            //
+            // An UNMATCHED quote used to open a context that nothing could close, so
+            // every remaining delimiter was absorbed and the rest of the input became
+            // one token. The common trigger is not exotic input — it is a prose
+            // apostrophe:
+            //
+            //   "ac one|the user doesn't care|ac three"  ->  2 tokens, not 3
+            //   "ac one|the user's token|ac three"       ->  2 tokens, not 3
+            //
+            // Measured: 804 characters of clean input split correctly, so the
+            // length hypothesis in the report was a correlation — an unmatched quote
+            // swallows the REMAINDER, so longer input loses more criteria. Length
+            // governs severity, not occurrence.
+            //
+            // The lookahead preserves every gh#409 case, because those quotes are
+            // balanced by construction (`'realtime-token'|'batch'`). An unmatched
+            // quote is now what it almost always is in prose: a literal character.
+            quote = ch;
+            buf += ch;
+        }
+        else if ((ch === '(' || ch === '[' || ch === '{') &&
+            // gh#1321 — only enter a bracket context when its partner exists later.
+            // An unbalanced `(` used to absorb the remainder exactly as an unmatched
+            // quote did: `"a|see (note|c|d|e"` became 2 tokens instead of 5. The old
+            // docblock promised the tail was "emitted as a single trailing token",
+            // which described the corruption rather than preventing it.
+            input.indexOf(ch === '(' ? ')' : ch === '[' ? ']' : '}', i + 1) !== -1) {
+            depth++;
+            buf += ch;
+        }
+        else if (ch === ')' || ch === ']' || ch === '}') {
+            depth = Math.max(0, depth - 1);
+            buf += ch;
+        }
+        else if (ch === delim && depth === 0) {
+            // gh-409 string-union rule: `'a'|'b'` and `"a"|"b"` stay as one token.
+            // If the previous non-ws char in buf is a closing quote AND the next
+            // non-ws char in input is an opening quote, treat this `|` as part of
+            // the current token (continuation), not as a split point.
+            const prev = lastNonWsChar(buf);
+            const next = nextNonWsChar(input, i + 1);
+            const isUnionContinuation = (prev === "'" || prev === '"') && (next === "'" || next === '"');
+            if (isUnionContinuation) {
+                buf += ch;
+            }
+            else {
+                const trimmed = buf.trim();
+                if (trimmed)
+                    out.push(trimmed);
+                buf = '';
+            }
+        }
+        else {
+            buf += ch;
+        }
+        i++;
+    }
+    // Flush trailing buffer (also handles unbalanced opens gracefully).
+    const trimmed = buf.trim();
+    if (trimmed)
+        out.push(trimmed);
+    return out;
+}
+/**
+ * Parse acceptance criteria from a raw CLI string.
+ *
+ * @remarks
+ * Supports two formats:
+ * - JSON array: `'["AC1","AC2","AC3"]'` (literal entries, normalized whitespace)
+ * - Pipe-separated: `"AC1|AC2|AC3"` (tokenized via `splitAcceptance`)
+ *
+ * The pipe-separated form uses a bracket+quote+escape-aware tokenizer so
+ * criteria containing `ENUM (hot|cold|batch|embed)`, quoted string-unions
+ * like `mode: 'realtime-token'|'batch'`, or escaped literals (`\|`) are
+ * preserved as single tokens rather than being shredded.
+ *
+ * @param raw - Raw string from `--acceptance` flag
+ * @returns Array of trimmed, non-empty acceptance criteria strings
+ * @throws CleoError for malformed explicit JSON arrays or nonstring JSON elements.
+ * @example
+ * ```typescript
+ * parseAcceptanceCriteria('first|ENUM (hot|cold)|third');
+ * // ['first', 'ENUM (hot|cold)', 'third']
+ * const raw = '["literal a|b", " verified "]';
+ * parseAcceptanceCriteria(raw);
+ * // ['literal a|b', 'verified']
+ * ```
+ *
+ * @bug https://github.com/kryptobaseddev/cleo/issues/409
+ * @task T1490
+ * @task T9839
+ */
+export function parseAcceptanceCriteria(raw) {
+    // A bracketed prose fragment is not necessarily JSON. Preserve existing
+    // delimiter behavior unless the first element has explicit JSON syntax.
+    const jsonArray = /^\s*\[\s*(?:["[\]{}]|-?\d|true\b|false\b|null\b)/.test(raw);
+    if (jsonArray) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new CleoError(ExitCode.VALIDATION_ERROR, 'Invalid JSON acceptance array');
+        }
+        return normalizeAcceptance(parsed) ?? [];
+    }
+    return normalizeAcceptance(splitAcceptance(raw, '|')) ?? [];
+}
+//# sourceMappingURL=acceptance-input.js.map

package/dist/tasks/acceptance-input.js.map

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

package/dist/tasks/add.d.ts

@@ -4,8 +4,9 @@
  * @epic T4454
  * @task T1633 — BRAIN-powered duplicate detection
  */
-import type { Task, TaskKind, TaskPriority, TaskScope, TaskSeverity, TaskSize, TaskStatus, TaskType, TaskVerification } from '@cleocode/contracts';
+import type { Task, TaskKind, TaskPriority, TaskScope, TaskSeverity, TaskSize, TaskStatus, TasksAddParams, TaskType, TaskVerification } from '@cleocode/contracts';
 import type { DataAccessor } from '../store/data-accessor.js';
+export { normalizeAcceptance } from './acceptance-input.js';
 /**
  * Options for creating a task.
  *
@@ -43,6 +44,8 @@ export interface AddTaskOptions {
     files?: string[];
     acceptance?: string[];
     depends?: string[];
+    /** Critical-priority justification committed with task_created audit provenance. */
+    dependsWaiver?: string;
     notes?: string;
     position?: number;
     addPhase?: boolean;
@@ -91,9 +94,48 @@ export interface AddTaskOptions {
      * @task T11811
      */
     skipContainmentInvariant?: boolean;
+    /**
+     * Suppress ONLY the PM-Core V2 design-point 3 guard (a `task`/`subtask`
+     * holding free-text ACs may not gain a child). Every other check still runs.
+     *
+     * MUST be set ONLY by {@link decomposeTask}, and there only on its `dryRun`
+     * preflight: that preflight asks "would this child be placeable?" while the
+     * parent still holds the criteria it is about to hand over, so design-point 3
+     * is the one rule that is legitimately not yet satisfied. The real write that
+     * follows sets nothing — by then the parent has been stripped and the guard
+     * passes honestly. Agent-facing `cleo add` / `add-batch` MUST NOT set this.
+     *
+     * @task T12281
+     */
+    skipMixedAcParentGuard?: boolean;
+    /**
+     * Resolve PM-Core V2 design-point 3 in-line instead of refusing.
+     *
+     * When the parent is a `task`/`subtask` carrying free-text ACs, run
+     * {@link decomposeTask} first — lifting those criteria onto a new first child
+     * so the parent becomes a pure container — and then proceed with this add.
+     *
+     * OPT-IN by design. Without it the guard still fires unchanged, because
+     * decomposing rewrites a task the caller only named as `--parent`, and doing
+     * that silently would mutate a row nobody asked about. The result reports
+     * what moved in {@link AddTaskResult.autoDecomposed}.
+     *
+     * @task T12298
+     */
+    autoDecompose?: boolean;
 }
 /** Result of adding a task. */
 export interface AddTaskResult {
+    /**
+     * Set when `autoDecompose` resolved design-point 3 before this add: the
+     * parent's criteria were lifted onto this child first. Absent otherwise.
+     *
+     * @task T12298
+     */
+    autoDecomposed?: {
+        childId: string;
+        movedAcceptance: string[];
+    };
     task: Task;
     duplicate?: boolean;
     dryRun?: boolean;
@@ -113,8 +155,30 @@ export interface AddTaskResult {
      */
     reopenedAncestors?: string[];
 }
-/** Normalize AC arrays once so legacy JSON, AC rows, and projections stay aligned. */
-export declare function normalizeAcceptance(acceptance: readonly string[] | undefined): string[] | undefined;
+/**
+ * Translate canonical creation input into core options without dropping fields.
+ * @param params - Canonical task creation input.
+ * @returns Core options with the parent alias and enum boundaries resolved.
+ * @remarks Entry points share this boundary; CLI parsing does not establish authorization.
+ * @example
+ * ```ts
+ * toTaskAddOptions({ title: 'Fix persistence', description: 'Verify durable task writes' });
+ * ```
+ */
+export declare function toTaskAddOptions(params: TasksAddParams): AddTaskOptions;
+/**
+ * Enforce the established explicit-critical dependency policy before mutation.
+ * @param priority - Explicit requested priority; waivers require critical.
+ * @param justification - Original reason, retained verbatim in transaction audit details.
+ * @param dependencies - Effective dependencies after applying the requested changes.
+ * @throws CleoError for invalid waivers or critical mutations without dependencies.
+ * @remarks Entry points share this boundary; CLI parsing does not establish authorization.
+ * @example
+ * ```ts
+ * validateDependencyWaiver('critical', 'Independent restoration', []);
+ * ```
+ */
+export declare function validateDependencyWaiver(priority: string | undefined, justification: string | undefined, dependencies: readonly string[]): void;
 /**
  * Build the default verification metadata applied to every new task.
  * Gates are initialized to false (not yet passed). `passed` starts false
@@ -240,32 +304,6 @@ export declare function validateParent(parentId: string, tasks: Task[], maxDepth
  * ```
  */
 export declare function getTaskDepth(taskId: string, tasks: Task[]): number;
-/**
- * Infer task type from parent context.
- * @task T4460
- *
- * @example
- * ```ts
- * const now = new Date().toISOString();
- * const tasks = [
- *   { id: 'T001', title: 'My Epic', description: '', type: 'epic',
- *     status: 'pending', priority: 'medium', size: 'medium', parentId: null,
- *     position: 1, positionVersion: 0, createdAt: now, updatedAt: now },
- *   { id: 'T002', title: 'Child Task', description: '', type: 'task',
- *     status: 'pending', priority: 'medium', size: 'medium', parentId: 'T001',
- *     position: 1, positionVersion: 0, createdAt: now, updatedAt: now },
- * ] as Task[];
- *
- * // No parent → standalone task
- * console.assert(inferTaskType(null, tasks) === 'task', 'no parent → task');
- *
- * // Epic parent → child is a task
- * console.assert(inferTaskType('T001', tasks) === 'task', 'epic parent → task');
- *
- * // Task parent → child is a subtask
- * console.assert(inferTaskType('T002', tasks) === 'subtask', 'task parent → subtask');
- * ```
- */
 export declare function inferTaskType(parentId: string | null | undefined, tasks: Task[]): TaskType;
 /**
  * Get the next position for a task within a parent scope.

package/dist/tasks/add.d.ts.map

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