gennady 0.8.3 → 0.8.4-draft.2

package/dist/services/vcs-client/gitlab/vcs-gitlab-pipeline.d.ts

@@ -0,0 +1,51 @@
+import { VcsClientPipeline } from '../abstract/vcs-client-pipeline.js';
+import type { VcsJob } from '../entities/vcs-job.type.js';
+import type { VcsJobQuery } from '../entities/vcs-job-query.type.js';
+/** @purpose Custom init options extending standard RequestInit with response type control. */
+type RequestInit_ = RequestInit & {
+    responseType?: 'json' | 'text';
+};
+type RequestFn = (path: string, init?: RequestInit_) => Promise<unknown>;
+/**
+ * @purpose GitLab REST adapter for pipeline job management.
+ * @invariant Error Policy: Network/status errors are thrown outward from request().
+ * @consumer VcsGitlabClient
+ */
+export declare class VcsGitlabPipeline extends VcsClientPipeline {
+    /** @purpose Bound HTTP request function injected for GitLab API calls */
+    protected _request: RequestFn;
+    /**
+     * @purpose Wire the HTTP request adapter for GitLab job endpoints.
+     * @param request Authenticated HTTP request function targeting GitLab API.
+     */
+    constructor(request: RequestFn);
+    /**
+     * @param query Scoping parameters: project and job ID.
+     * @returns Job details from GitLab API.
+     * @sideEffect Network: GET /projects/:project/jobs/:job_id
+     * @see {VcsClientPipeline#getJob} in services/vcs-client/abstract/vcs-client-pipeline.ts
+     */
+    getJob(query: VcsJobQuery): Promise<VcsJob>;
+    /**
+     * @param query Scoping parameters: project and job ID.
+     * @returns Updated job details after retry is initiated.
+     * @sideEffect Network: POST /projects/:project/jobs/:job_id/play
+     * @see {VcsClientPipeline#playJob} in services/vcs-client/abstract/vcs-client-pipeline.ts
+     */
+    playJob(query: VcsJobQuery): Promise<VcsJob>;
+    /**
+     * @param query Scoping parameters: project and job ID.
+     * @returns Updated job details after cancellation.
+     * @sideEffect Network: POST /projects/:project/jobs/:job_id/cancel
+     * @see {VcsClientPipeline#cancelJob} in services/vcs-client/abstract/vcs-client-pipeline.ts
+     */
+    cancelJob(query: VcsJobQuery): Promise<VcsJob>;
+    /**
+     * @param query Scoping parameters: project and job ID.
+     * @returns Raw log text from the job runner.
+     * @sideEffect Network: GET /projects/:project/jobs/:job_id/trace
+     * @see {VcsClientPipeline#getJobLog} in services/vcs-client/abstract/vcs-client-pipeline.ts
+     */
+    getJobLog(query: VcsJobQuery): Promise<string>;
+}
+export {};

package/dist/services/vcs-client/gitlab/vcs-gitlab-reactions.d.ts

@@ -0,0 +1,31 @@
+import { VcsClientReactions } from '../abstract/vcs-client-reactions.js';
+import type { VcsReactionQuery } from '../entities/vcs-reaction-query.type.js';
+type RequestFn = (path: string, init?: RequestInit) => Promise<unknown>;
+/**
+ * @purpose GitLab emoji reactions via award_emoji REST API.
+ * @consumer VcsGitlabClient
+ */
+export declare class VcsGitlabReactions extends VcsClientReactions {
+    /** @purpose Bound HTTP request function injected for GitLab API calls */
+    protected _request: RequestFn;
+    /**
+     * @purpose Wire the HTTP request adapter for GitLab reaction endpoints.
+     * @param request Authenticated HTTP request function targeting GitLab API.
+     */
+    constructor(request: RequestFn);
+    /**
+     * @param query Parameters: { project, iid, noteId, emoji }.
+     * @returns Nothing; void operation.
+     * @sideEffect Network: POST /projects/:id/merge_requests/:iid/notes/:note_id/award_emoji?name=<emoji>
+     * @see {VcsClientReactions#add} in services/vcs-client/abstract/vcs-client-reactions.ts
+     */
+    add(query: VcsReactionQuery): Promise<void>;
+    /**
+     * @param query Parameters: { project, iid, noteId, emoji }.
+     * @returns Nothing; void operation.
+     * @sideEffect Network: DELETE /projects/:id/merge_requests/:iid/notes/:note_id/award_emoji/<award_id>
+     * @see {VcsClientReactions#remove} in services/vcs-client/abstract/vcs-client-reactions.ts
+     */
+    remove(query: VcsReactionQuery): Promise<void>;
+}
+export {};

package/dist/shared/common/changed-files.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @purpose Changed source files (vs HEAD, plus untracked) under `root`. Test/spec files are excluded.
+ * @param root Repository root.
+ * @returns Repo-root-relative paths.
+ */
+export declare function getChangedSourceFiles(root: string): string[];
+/**
+ * @purpose Read a file's content at HEAD, or null when it has no HEAD version (new file).
+ * @invariant Exit 128 (no HEAD version — new/untracked file) is expected, not an error — suppressed.
+ * @param root Repository root.
+ * @param relPath Repo-root-relative path.
+ * @returns HEAD content, or null.
+ */
+export declare function getHeadContent(root: string, relPath: string): string | null;

package/dist/shared/common/exec.d.ts

@@ -1,7 +1,12 @@
+/** @purpose Options for execSyncSafe. */
+export type ExecSyncSafeOptions = {
+    /** @purpose Exit codes that are a normal outcome for this command (e.g. grep's 1 for "no match") — suppresses the error log, still returns ''. */
+    expectedExitCodes?: number[];
+};
 /**
  * @purpose Execute system command synchronously with safe error handling.
  * @pre Command and binary available in PATH; run in correct environment.
- * @sideEffect Process: launch external process; Logs: error on failure.
+ * @sideEffect Process: launch external process; Logs: error on failure, unless the exit code is in `expectedExitCodes`.
  * @consumer git/git-core, other domains via utils
  */
-export declare const execSyncSafe: (cmd: string) => string;
+export declare const execSyncSafe: (cmd: string, options?: ExecSyncSafeOptions) => string;

package/dist/shared/common/parse-args.d.ts

@@ -1,7 +1,14 @@
+/** @purpose Options controlling parseArgs behavior beyond the schema itself. */
+export type ParseArgsOptions = {
+    /** @purpose When true, a `-`-prefixed arg matching no schema alias throws instead of being silently dropped. */
+    strict?: boolean;
+};
 /**
  * @purpose Parse command-line arguments by options schema and aliases.
+ * @invariant `strict: true` throws on any unmatched `-`-prefixed arg — catches typo'd flags that would
+ *   otherwise be silently dropped or misread as a positional.
  * @consumer CLI (gennady, cmd/*)
  */
-export declare const parseArgs: <T extends Record<string, string[]>>(argv: string[], schema?: T) => Record<keyof T | "_", unknown> & {
+export declare const parseArgs: <T extends Record<string, unknown>>(argv: string[], schema?: T, options?: ParseArgsOptions) => Record<keyof T | "_", unknown> & {
     _: string[];
 };

package/dist/shared/common/sync/sync-core.shared.d.ts

@@ -1,5 +1,5 @@
 /**
- * @purpose Locate a subdirectory inside the installed gennady npm package.
+ * @purpose Locate a subdirectory inside the installed gennady npm package, or the gennady repo itself.
  * @param projectRoot Project root directory (contains node_modules/).
  * @param subdir Subdirectory path inside the gennady package (e.g., 'ai/directives').
  * @returns Absolute path or null if the package or subdirectory is not found.

package/dist/shared/mermaid/mermaid.d.ts

@@ -0,0 +1,19 @@
+/**
+ * @purpose Lazily load mermaid + a jsdom DOM shim (both browser-oriented) only when a diagram is actually validated.
+ * @invariant mermaid reads `window`/`document`/`navigator` from global scope at parse time; jsdom provides them. Loaded once, then cached.
+ * @returns mermaid's `parse` — resolves for valid diagram source, rejects (throws) on invalid syntax.
+ */
+export declare function loadMermaidParse(): Promise<(text: string) => Promise<unknown>>;
+/**
+ * @purpose Extract every closed ```mermaid … ``` block body from a document. Pure.
+ * @param content Full document text.
+ * @returns Block bodies (fence markers stripped); empty when the document has no mermaid block.
+ */
+export declare function extractMermaidBlocks(content: string): string[];
+/**
+ * @purpose Validate one mermaid diagram source through the real parser.
+ * @param text Diagram body (no fence markers).
+ * @returns `null` when the diagram parses; else the first line of the parser error.
+ * @sideEffect Lazily loads mermaid + jsdom on first call.
+ */
+export declare function validateMermaid(text: string): Promise<string | null>;

package/dist/shared/prompt-lint/stop-words.d.ts

@@ -0,0 +1,34 @@
+/** @purpose One stop-word rule for the dictionary. */
+export type StopWord = {
+    /** @purpose Matcher for the banned word (Unicode word boundaries, `iu` flags). */
+    re: RegExp;
+    /** @purpose Short reason category shown to the operator (Russian data). */
+    why: string;
+    /** @purpose Suggested replacement shown to the operator (Russian data). */
+    use: string;
+};
+/**
+ * @purpose High-precision banned Russian words (bookish, calque, slang). Extended as offenders appear.
+ * @invariant Review domain terms are excluded; `why`/`use` are Russian operator-facing data.
+ */
+export declare const STOP_WORDS: StopWord[];
+/** @purpose A found stop-word occurrence. */
+export type StopWordHit = {
+    /** @purpose The matched word as it appears in the text. */
+    word: string;
+    /** @purpose 1-based line number of the match. */
+    line: number;
+    /** @purpose 1-based column number of the match. */
+    col: number;
+    /** @purpose Reason category from the dictionary (Russian data). */
+    why: string;
+    /** @purpose Suggested replacement from the dictionary (Russian data). */
+    use: string;
+};
+/**
+ * @purpose Find stop-words in text, skipping code and comments (mentions-as-tokens, not usage).
+ * @invariant Skips inline backticks, fenced blocks, HTML comments; `<!-- stop-ok -->` opts a line out. Pure.
+ * @param text Text to scan (markdown / prompt).
+ * @returns Hits in order of appearance; empty when clean.
+ */
+export declare function findStopWords(text: string): StopWordHit[];

package/dist/shared/sdd/anchor-inject.d.ts

@@ -0,0 +1,32 @@
+/**
+ * @purpose Body of one canonical v1 header — text from just after it to the next header of level ≤ its own (or EOF).
+ * @invariant Reuses `injectAnchors`' header/span logic — a legacy body is exactly what it would wrap in markers.
+ * @param content Full markdown (v1, plain headers).
+ * @param name Canonical section name (e.g. `META`, `EXECUTION_LOG`).
+ * @returns The header's body text, or null when no header maps to `name`.
+ */
+export declare function legacyHeaderBody(content: string, name: string): string | null;
+/**
+ * @purpose Wrap each canonical section of a v1 ticket in `<!--SECTION:NAME-->` / `<!--/SECTION:NAME-->` markers.
+ * @invariant A section spans from its header to the next header of level ≤ its own (or EOF); sections never nest.
+ * @invariant Idempotent — a section already carrying its open marker is left untouched.
+ * @param content Full ticket markdown (v1, plain headers).
+ * @returns The anchored text and the list of section names that were injected (empty when already anchored / not a ticket).
+ */
+export declare function injectAnchors(content: string): {
+    text: string;
+    injected: string[];
+};
+/**
+ * @purpose Scaffold a minimal `## Execution Log` section onto a v1 ticket (Meta header/anchor present)
+ * that never had one, so `isTicket` stops missing it.
+ * @invariant Idempotent — a text that already carries the EXECUTION_LOG open marker is left untouched.
+ * @invariant Only fires when a Meta header/anchor is present; files with no Meta signature are not touched.
+ * @param content Ticket markdown, typically already run through `injectAnchors`.
+ * @param dateStr Migration date stamp for the scaffolded note line (caller-supplied — this stays pure).
+ * @returns The (possibly appended) text and whether a section was scaffolded.
+ */
+export declare function scaffoldExecutionLog(content: string, dateStr: string): {
+    text: string;
+    scaffolded: boolean;
+};

package/dist/shared/sdd/bdd-coverage.d.ts

@@ -0,0 +1,72 @@
+import type { Finding } from './check.js';
+import type { FlowVersion } from './flow.js';
+/**
+ * @purpose One `## Test Scenario Coverage` row, parsed.
+ * @invariant `deferred` carries the owning Task-ID for a `Deferred Test Ownership:` row — informational, never checked against a test file.
+ */
+export type CoverageEntry = {
+    /** @purpose The scenario label text (tag like `[simulation-backed]` stripped). */
+    scenario: string;
+    /** @purpose Declared test-file basename (e.g. `session-lifecycle.test.ts`). */
+    testFile: string;
+    /** @purpose Canonical `it`/`test` case names claimed for this scenario (one row may claim several, comma-separated). */
+    caseNames: string[];
+    /** @purpose Task-ID owning a deferred scenario, or null for a concrete (checkable) row. */
+    deferred: string | null;
+};
+/**
+ * @purpose Parse the `## Test Scenario Coverage` section body into its rows.
+ * @invariant Rows `parseCoverageRow` can't match are skipped — see `findUnparsedCoverageRows` for the "row-shaped but unparseable" cases this silently drops.
+ * @param body Section markdown (TEST_COVERAGE anchor content).
+ * @returns One CoverageEntry per matched line.
+ */
+export declare function parseTestCoverage(body: string): CoverageEntry[];
+/**
+ * @purpose Find `- ...` lines shaped like a coverage row that `parseCoverageRow` can't match — these silently vanish from `parseTestCoverage`, hiding a scenario.
+ * @param body Section markdown (TEST_COVERAGE anchor content).
+ * @returns Trimmed line text for each unparseable row, in document order.
+ */
+export declare function findUnparsedCoverageRows(body: string): string[];
+/**
+ * @purpose Extract `it(...)`/`test(...)` canonical case-name string literals from a test file.
+ * @invariant Regex-based (no AST) — matches `it`/`test` calls including `.only`/`.skip`/`.todo` modifiers; `describe` blocks are not tracked, only the leaf case name matters for BDD matching.
+ * @param content Full test-file source.
+ * @returns Case names in file order (duplicates possible across separate `it`/`test` calls).
+ */
+export declare function extractTestCaseNames(content: string): string[];
+/**
+ * @purpose Resolve a declared test-file reference (basename or path) by suffix match against disk.
+ * @invariant `f === norm || f.endsWith('/' + norm)`. Pure — `allFiles` must be forward-slash normalized.
+ * @param allFiles Every test-file path on disk, forward-slash normalized.
+ * @param declared The ticket's declared test-file reference — basename or path, either separator style.
+ * @returns Every file matching the suffix rule (0, 1, or many).
+ */
+export declare function resolveTestFileMatches(allFiles: string[], declared: string): string[];
+/**
+ * @purpose Flag a declared test-file reference resolving to >1 file — case-name lookup can't tell which.
+ * @invariant Pure. Always `warn` — ambiguity is a spec-hygiene issue, not proof of missing coverage.
+ * @param file Ticket path (finding location).
+ * @param testFile The declared test-file reference, as written in the ticket.
+ * @param matches The files `resolveTestFileMatches` found for it.
+ * @returns One `SDD_BDD_TESTFILE_AMBIGUOUS` when `matches.length > 1`, else empty.
+ */
+export declare function checkTestFileAmbiguity(file: string, testFile: string, matches: string[]): Finding[];
+/**
+ * @purpose Check each concrete coverage row's case names against its test file, and flag any row deferred to this ticket's own Task-ID.
+ * @invariant Pure. `SDD_BDD_SCENARIO_UNTESTED` severity follows `flowVersion` (`v1` warn, `v2` error); `SDD_BDD_DEFERRED_TO_SELF` is always `error` — a self-deferral hides missing coverage, never a real one.
+ * @param file Ticket path (finding location).
+ * @param entries Parsed coverage rows (`parseTestCoverage`).
+ * @param caseNamesByFile Test-file basename → its extracted `it`/`test` case names (adapter-read).
+ * @param [flowVersion] The ticket's own flow version — `'v1'` default, the conservative choice.
+ * @param [selfTaskId] This ticket's own Task-ID (from its META), or null when unknown/unparseable.
+ * @returns One `SDD_BDD_SCENARIO_UNTESTED` per claimed case name not found, plus one `SDD_BDD_DEFERRED_TO_SELF` per row deferred to `selfTaskId`; empty when clean.
+ */
+export declare function checkBddCoverage(file: string, entries: CoverageEntry[], caseNamesByFile: Map<string, string[]>, flowVersion?: FlowVersion, selfTaskId?: string | null): Finding[];
+/**
+ * @purpose Flag rows `findUnparsedCoverageRows` could not parse — else an unmapped scenario silently stops being checkable.
+ * @invariant Pure. Always `warn` — one real row-shaped-but-malformed line, not graded by `flowVersion`.
+ * @param file Ticket path (finding location).
+ * @param body Section markdown (TEST_COVERAGE anchor content).
+ * @returns One `SDD_BDD_COVERAGE_ROW_UNPARSED` per unparseable row, in document order.
+ */
+export declare function checkUnparsedCoverageRows(file: string, body: string): Finding[];

package/dist/shared/sdd/check.d.ts

@@ -0,0 +1,225 @@
+import type { Scope, GraphEdge } from './portal.js';
+import type { FlowVersion } from './flow.js';
+/**
+ * @purpose One audit finding.
+ * @invariant `error` fails the gate; `warn` is advisory (reported, non-fatal).
+ */
+export type Finding = {
+    /** @purpose Severity — error fails the gate, warn is advisory. */
+    severity: 'error' | 'warn';
+    /** @purpose Stable finding code token. */
+    code: string;
+    /** @purpose File the finding refers to. */
+    file: string;
+    /** @purpose Description with the issue and a location hint. */
+    message: string;
+};
+/**
+ * @purpose True when a file looks like a ticket (carries both META and EXECUTION_LOG sections).
+ * @param content Full file markdown.
+ * @returns True when both section markers are present.
+ */
+export declare function isTicket(content: string): boolean;
+/**
+ * @purpose True when a file looks like a pre-migration (v1) ticket — plain-markdown Meta + Execution Log headers, no `<!--SECTION-->` markers.
+ * @invariant Callers must check `isTicket` first — an anchored ticket keeps its old plain headers too, so the two are not mutually exclusive alone.
+ * @param content Full file markdown.
+ * @returns True when both canonical headers resolve via `legacyHeaderBody`.
+ */
+export declare function isLegacyTicket(content: string): boolean;
+/**
+ * @purpose Run the mechanical checks against one ticket's content.
+ * @invariant Pure — no I/O; cross-file checks (spec-link resolution, walking) live in the command.
+ * @param file Path used in finding locations.
+ * @param content Full ticket markdown.
+ * @returns Findings (possibly empty); errors fail the gate.
+ */
+export declare function checkTicket(file: string, content: string): Finding[];
+/**
+ * @purpose Gathered portal facts for the integrity check — the command supplies the fs-derived spec dirs.
+ * @invariant `specDirs` are the names of `specs/<dir>` directories that hold a `<dir>.spec.md` (top-level scope specs only).
+ */
+export type PortalInput = {
+    /** @purpose Scopes parsed from the portal Scopes table. */
+    scopes: Scope[];
+    /** @purpose Depends-on edges parsed from the portal Scope Graph. */
+    edges: GraphEdge[];
+    /** @purpose Names of top-level `specs/<dir>` directories that contain a `<dir>.spec.md` on disk. */
+    specDirs: string[];
+};
+/**
+ * @purpose Run the mechanical integrity checks against the project portal (specs/README.md).
+ * @invariant Pure — fs-derived `specDirs` are supplied by the caller; reports against the fixed `specs/README.md` path.
+ * @param input The gathered portal facts: table scopes, graph edges, on-disk spec dirs.
+ * @returns Findings (possibly empty); errors fail the gate.
+ */
+export declare function checkPortal(input: PortalInput): Finding[];
+/** @purpose The graph-relevant fields of one ticket, built by the command from each ticket file. */
+export type TicketRef = {
+    /** @purpose Ticket file path (for finding locations). */
+    file: string;
+    /** @purpose Task-ID from Meta, or null when unparseable. */
+    taskId: string | null;
+    /** @purpose Status token from Meta (e.g. `[x] DONE`), or null. */
+    status: string | null;
+    /** @purpose Dependency Task-IDs declared in Meta. */
+    dependencies: string[];
+    /** @purpose The ticket's own scope flow version — grades SDD_TRACKER_MISSING_ROW severity. Defaults to `'v1'` (conservative) when the caller omits it. */
+    flowVersion?: FlowVersion;
+};
+/** @purpose One Tracker-Index row plus the index file it came from. */
+export type TrackerRowRef = {
+    /** @purpose The `*.3-tasks.md` index file path (or a legacy `tasks/<scope>/README.md` carrying an embedded Tracker table). */
+    file: string;
+    /** @purpose Task-ID from the row. */
+    taskId: string;
+    /** @purpose Status cell text. */
+    status: string;
+    /** @purpose The tracker file's own scope flow version — grades SDD_TRACKER_ORPHAN_ROW severity. Defaults to `'v1'` (conservative) when the caller omits it. */
+    flowVersion?: FlowVersion;
+};
+/**
+ * @purpose Build the task-graph fields of a ticket from its content.
+ * @param file Ticket file path.
+ * @param content Full ticket markdown.
+ * @param [flowVersion] The ticket's own scope flow version (caller-supplied; not derivable from content alone).
+ * @returns A TicketRef: the Meta Task-ID + dependencies (null / empty when absent).
+ */
+export declare function ticketRef(file: string, content: string, flowVersion?: FlowVersion): TicketRef;
+/**
+ * @purpose Build a legacy ticket's task-graph fields — same shape as `ticketRef`, sourced from its plain-markdown Meta header instead of a SECTION marker.
+ * @invariant This is what lights up the tracker cross-check and task DAG for legacy tickets.
+ * @param file Ticket file path.
+ * @param content Full ticket markdown (v1, plain headers).
+ * @param [flowVersion] The ticket's own scope flow version.
+ * @returns A TicketRef; null/empty fields when the Meta header is absent or unparseable.
+ */
+export declare function legacyTicketRef(file: string, content: string, flowVersion?: FlowVersion): TicketRef;
+/**
+ * @purpose Single advisory finding for a legacy ticket, in place of `checkTicket` (marker-dependent, would just drown the file in format-mismatch noise).
+ * @param file Ticket file path.
+ * @returns One SDD_LEGACY_TICKET_UNANCHORED warn.
+ */
+export declare function checkLegacyTicket(file: string): Finding[];
+/**
+ * @purpose Compute the pickable task set — the deterministic execution map: which tickets are ready to run now.
+ * @invariant Pickable = Status TODO (not DONE / not blocked) AND every dependency is DONE. Pure — derived from the gathered TicketRefs, never eyeballed.
+ * @param refs Every ticket's graph fields (taskId, status, dependencies).
+ * @returns The TicketRefs ready to execute, in input order.
+ */
+export declare function pickableTasks(refs: TicketRef[]): TicketRef[];
+/**
+ * @purpose Check the cross-ticket task DAG — Task-ID collisions, unresolved dependencies, cycles.
+ * @invariant Pure — operates on the gathered TicketRefs; graph-wide findings use `(task graph)` as the location.
+ * @param tickets Every ticket's graph fields, from the project tree.
+ * @returns Findings (possibly empty); errors fail the gate.
+ */
+export declare function checkTaskGraph(tickets: TicketRef[]): Finding[];
+/**
+ * @purpose Cross-check tickets against their Tracker-Index rows — status drift, missing rows, orphan rows.
+ * @invariant Pure — matched by Task-ID. STATUS_DRIFT is always `error`; MISSING_ROW/ORPHAN_ROW grade by
+ *   `flowVersion` (default `'v1'`, like `checkBddCoverage`) — `warn` on legacy, `error` once migrated.
+ * @param tickets Every ticket's graph fields (Task-ID + Status + scope flow version).
+ * @param rows Every Tracker-Index row across the tree (+ its tracker file's scope flow version).
+ * @returns Findings (possibly empty); errors fail the gate.
+ */
+export declare function checkTrackers(tickets: TicketRef[], rows: TrackerRowRef[]): Finding[];
+/**
+ * @purpose Minimal required section-anchor skeleton per scope-type — the load-bearing sections only.
+ * @invariant Keyed by `scope-type`; a spec may carry MORE sections but never fewer. Derived from
+ * `shared/sdd/templates.ts`'s `loadBearing:true` sections per kind — see templates.ts docs.
+ */
+export declare const REQUIRED_SECTIONS: Record<string, string[]>;
+/**
+ * @purpose v2 module-spec load-bearing sections (AX_MODULE_SPEC_FLOOR).
+ * @invariant v2-only; diagram presence is checked separately (SDD_NO_DIAGRAM_BLOCK). Derived from
+ * `shared/sdd/templates.ts` (module kind, `loadBearing:true` sections).
+ */
+export declare const MODULE_REQUIRED_V2: string[];
+/**
+ * @purpose v2 heavy/reference sections whose detail must fold under `<details>` (AX_SPEC_PROGRESSIVE_DISCLOSURE) — the machine part of the two-part spec (module AND scope specs).
+ * @invariant Checked only when present; `PUBLIC_OPTIONS` excluded (real specs carry it unfolded). Derived
+ * from `shared/sdd/templates.ts` — union of `fold:true` sections across scope-type kinds plus module.
+ */
+export declare const FOLD_REQUIRED_V2: string[];
+/**
+ * @purpose Deterministic language lint for operator-facing prose — flag transliterated anglicisms
+ * and chancellery phrasing the language policy bans (flat engineering Russian, no bureaucratic register).
+ * @invariant Warn-only pre-filter for unambiguous words; document-level judgment stays the audit's job. One finding per word per file.
+ * @param file Artifact path.
+ * @param content Full artifact markdown.
+ * @returns SDD_LANGUAGE_CALQUE warnings, one per distinct calque or chancellery marker found.
+ */
+export declare function checkSpecLanguage(file: string, content: string): Finding[];
+/**
+ * @purpose Mechanical structure checks for a spec file (.spec.md) — anchor balance, required sections, and (v2) mandatory diagrams + folded heavy detail.
+ * @invariant Pure. Scope required-sections apply to any scope spec (SCOPE_TYPE present). v2-only rules (module floor, mandatory diagram, `<details>` folding) stay dormant under `flowVersion='v1'`.
+ * @param file Spec file path.
+ * @param content Full spec markdown.
+ * @param [flowVersion] SDD flow generation; `'v2'` enables the strict spec rules. Defaults to `'v1'`.
+ * @returns Findings (possibly empty); errors fail the gate.
+ */
+export declare function checkSpecStructure(file: string, content: string, flowVersion?: FlowVersion): Finding[];
+/**
+ * @purpose Mechanical table-cell checks — a table is an index, not text (AX_SPEC_TABLE_IS_INDEX, v2 only).
+ * @invariant Pure. Fence-aware — pipes in fenced code are never rows. A row before a separator row is a header; its cell count gates SDD_TABLE_TOO_MANY_COLUMNS.
+ * @param file Spec file path.
+ * @param content Full spec markdown.
+ * @returns Findings (possibly empty); all entries are errors (the caller gates this behind flowVersion='v2').
+ */
+export declare function checkTableCells(file: string, content: string): Finding[];
+/**
+ * @purpose Parse a module spec's Inter-Module Dependencies (## 9) Mermaid graph into edges.
+ * @invariant Reads ONLY the INTER_MODULE_DEPENDENCIES section; cross-scope dotted edges (`.->`) are ignored by parseGraphEdges.
+ * @param content Full module-spec markdown.
+ * @returns Edges (empty when the section or graph is absent).
+ */
+export declare function moduleGraphEdges(content: string): GraphEdge[];
+/**
+ * @purpose Cross-check a scope spec's declared dependencies against the portal Scope Graph (B5) — the graph is authoritative, the spec must acknowledge each outgoing edge.
+ * @invariant Warn-only; graph→spec direction only (reverse is too noisy). No SCOPE_DEPENDENCIES section → [] (module/legacy specs). Pure.
+ * @param file Spec file path — error location and the source of the scope name (basename stem).
+ * @param content Full scope-spec markdown.
+ * @param portalEdges Edges parsed from the portal Scope Graph (specs/README.md).
+ * @returns One warn per portal edge `<scope> --> <dep>` not acknowledged in the spec; empty when all covered or no deps section.
+ */
+export declare function checkScopeDeps(file: string, content: string, portalEdges: GraphEdge[]): Finding[];
+/**
+ * @purpose Detect a cycle in a scope's module dependency graph (edges unioned from every module's ## 9).
+ * @invariant Cycle only — no dangling-ref check (the graph legitimately carries non-module nodes: entry points, shared libs).
+ * @param scope Scope name (for the message).
+ * @param scopeFile Scope spec path the finding is reported against.
+ * @param edges Unioned inter-module edges for the scope.
+ * @returns One SDD_MODULE_DAG_CYCLE error when cyclic, else empty.
+ */
+export declare function checkModuleGraph(scope: string, scopeFile: string, edges: GraphEdge[]): Finding[];
+/**
+ * @purpose One `.spec.md` file's graph-relevant fields, gathered by the command from the project tree.
+ * @invariant `file` paths across one `checkSpecHierarchy` call must share the same root form
+ *   (all-absolute or all-relative) — the ancestor walk compares them structurally.
+ */
+export type SpecEntry = {
+    /** @purpose Spec file path (module or scope spec). */
+    file: string;
+    /** @purpose Full spec markdown. */
+    content: string;
+    /** @purpose This spec's own scope flow version — grades hierarchy-check severity, like checkBddCoverage. */
+    flowVersion?: FlowVersion;
+};
+/**
+ * @purpose Spec-hierarchy verification (AX_HIERARCHICAL_SPECS / AX_SCOPE_STAYS_THIN): every module
+ *   spec is linked from its nearest ancestor index; a parent with children became a thin index.
+ * @invariant Pure — no I/O; the command supplies every spec from the walk. Severity per entry
+ *   graded by its own `flowVersion` (default `'v1'`), like `checkBddCoverage`.
+ * @param specs Every module + scope spec in the tree, from the project walk.
+ * @returns SDD_MODULE_NOT_IN_INDEX / SDD_PARENT_MODULE_NOT_INDEX findings (possibly empty).
+ */
+export declare function checkSpecHierarchy(specs: SpecEntry[]): Finding[];
+/**
+ * @purpose Track a spec's lifecycle state (master vs review-state) and flag broken or stuck review-states.
+ * @invariant master = no CHANGE_MANIFEST and no ✚/~ marks; review-state = manifest (marks optional for greenfield). Mismatches surfaced per AX_SPEC_LIFECYCLE.
+ * @param file Spec file path.
+ * @param content Full spec markdown.
+ * @returns Findings: SDD_REVIEW_INCONSISTENT (error) for a malformed review-state; SDD_REVIEW_STATE_STUCK (warn) for a lingering manifest.
+ */
+export declare function checkReviewState(file: string, content: string): Finding[];

package/dist/shared/sdd/consumers-resolvable.d.ts

@@ -0,0 +1,41 @@
+import type { Finding } from './check.js';
+/**
+ * @purpose One classified `@consumers:` entry.
+ * @invariant `external` entries are never resolved and never flagged — they are free-text descriptions, not codebase identifiers.
+ */
+export type ConsumerEntry = {
+    /** @purpose Original entry text, trimmed. */
+    raw: string;
+    /** @purpose The identifier to resolve — the entry with any trailing `(...)` detail stripped. Meaningless when `external`. */
+    name: string;
+    /** @purpose True when the entry reads as a free-text description (contains the word "external", or its head carries whitespace) rather than a single codebase identifier. */
+    external: boolean;
+};
+/**
+ * @purpose Split a header field on top-level commas — commas inside `(...)` do not split, so `cli/cmd/inbox (debug dump, D-124)` stays one entry.
+ * @param field The text after `@consumers:`.
+ * @returns Trimmed, non-empty entries.
+ */
+export declare function splitConsumerEntries(field: string): string[];
+/**
+ * @purpose Parse a file's `@consumers:` header comment into its top-level entry list.
+ * @param content Full file source.
+ * @returns Raw entries (`splitConsumerEntries`); empty when the header is absent.
+ */
+export declare function parseConsumersHeader(content: string): string[];
+/**
+ * @purpose Classify one raw `@consumers:` entry: a resolvable codebase identifier, or a free-text / external description.
+ * @invariant Trailing `(...)` detail is stripped to get `name`; a whitespace-bearing/empty head, or the word "external" anywhere, marks it `external`.
+ * @param raw One `@consumers:` entry (already top-level-split via `splitConsumerEntries`).
+ * @returns The classified ConsumerEntry.
+ */
+export declare function classifyConsumerEntry(raw: string): ConsumerEntry;
+/**
+ * @purpose Check that every non-external `@consumers:` entry resolves somewhere in the codebase.
+ * @invariant Pure — codebase text search is the adapter's job; `resolved` is the set of `name` values the adapter found referenced elsewhere in the repo.
+ * @param file File path (finding location).
+ * @param entries Classified entries (`classifyConsumerEntry` over `parseConsumersHeader`).
+ * @param resolved Identifier names the adapter confirmed are referenced elsewhere in the repo.
+ * @returns One `SDD_CONSUMERS_UNRESOLVED` (warn — text search is crude) per unresolved identifier; empty when every entry resolves or is external.
+ */
+export declare function checkConsumersResolvable(file: string, entries: ConsumerEntry[], resolved: Set<string>): Finding[];

package/dist/shared/sdd/flow.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @purpose SDD flow generation — v1 (`tasks/` layout) or v2 (co-located specs + `*.3-tasks.md`).
+ * @invariant `v1` is the pre-migration layout; strict v2-only spec rules stay dormant under `v1`.
+ */
+export type FlowVersion = 'v1' | 'v2';
+/**
+ * @purpose Detect the SDD flow version from the project layout — a `tasks/` directory marks v1.
+ * @invariant The `tasks/` directory is the single v1 marker; its absence means the repo is on v2.
+ * @param root Absolute project root.
+ * @returns `'v1'` when `<root>/tasks/` is a directory, else `'v2'`.
+ */
+export declare function detectFlowVersion(root: string): FlowVersion;
+/**
+ * @purpose Detect the flow version of ONE scope — the mixed-state marker during migration.
+ * @invariant v2 repo: every scope is v2. v1 repo: a scope is v2 only when `tasks/<scope>/` is
+ *   gone AND `<scope>.3-tasks.md` exists; untouched scopes stay v1-lenient.
+ * @param repoRoot Absolute repo root (the directory holding `specs/` and `tasks/`).
+ * @param scope Scope name (the first path segment under `specs/`).
+ * @returns The scope's flow version.
+ */
+export declare function detectScopeFlowVersion(repoRoot: string, scope: string): FlowVersion;