@specship/specship 0.11.0

package/dist/directory.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Directory Management
+ *
+ * Manages the .specship/ directory structure for SpecShip data.
+ *
+ * Layout: `<projectRoot>/.specship/` holds the SQLite index, lock file,
+ * daemon PID, workflow artifacts, logs, and project-level workflow
+ * definitions. The directory lives **inside the project** by design so
+ * that team-shared assets — notably `.specship/workflows/*.yaml` — are
+ * checked in alongside the code they govern. Per-machine files (the DB,
+ * the lock, the daemon socket, log output) are gitignored by the
+ * `.gitignore` written into the folder on init.
+ */
+/**
+ * SpecShip directory name
+ */
+export declare const SPECSHIP_DIR = ".specship";
+/**
+ * Get the .specship directory path for a project. All callers that
+ * compose subdirectories (artifacts, logs, lock files, daemon PID)
+ * should funnel through here so the layout has one source of truth.
+ */
+export declare function getSpecShipDir(projectRoot: string): string;
+/**
+ * Check if a project has been initialized with SpecShip.
+ * Requires both .specship/ directory AND specship.db to exist.
+ */
+export declare function isInitialized(projectRoot: string): boolean;
+/**
+ * Find the nearest parent directory containing .specship/
+ *
+ * Walks up from the given path to find a SpecShip-initialized project,
+ * similar to how git finds .git/ directories.
+ *
+ * @param startPath - Directory to start searching from
+ * @returns The project root containing .specship/, or null if not found
+ */
+export declare function findNearestSpecShipRoot(startPath: string): string | null;
+/**
+ * Create the .specship directory structure
+ * Note: Only throws if specship.db already exists, not just if .specship/ exists.
+ */
+export declare function createDirectory(projectRoot: string): void;
+/**
+ * Remove the .specship directory
+ */
+export declare function removeDirectory(projectRoot: string): void;
+/**
+ * Get all files in the .specship directory
+ */
+export declare function listDirectoryContents(projectRoot: string): string[];
+/**
+ * Get the total size of the .specship directory in bytes
+ */
+export declare function getDirectorySize(projectRoot: string): number;
+/**
+ * Ensure a subdirectory exists within .specship
+ */
+export declare function ensureSubdirectory(projectRoot: string, subdirName: string): string;
+/**
+ * Check if the .specship directory has valid structure
+ */
+export declare function validateDirectory(projectRoot: string): {
+    valid: boolean;
+    errors: string[];
+};
+//# sourceMappingURL=directory.d.ts.map

package/dist/directory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory.d.ts","sourceRoot":"","sources":["../src/directory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH;;GAEG;AACH,eAAO,MAAM,YAAY,cAAc,CAAC;AAExC;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE1D;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAQ1D;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBxE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CA6BzD;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAuBzD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE,CA8BnE;AAED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CA+B5D;AAED;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,WAAW,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAYlF;AAED;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG;IACtD,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,CA8BA"}

package/dist/directory.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * Directory Management
+ *
+ * Manages the .specship/ directory structure for SpecShip data.
+ *
+ * Layout: `<projectRoot>/.specship/` holds the SQLite index, lock file,
+ * daemon PID, workflow artifacts, logs, and project-level workflow
+ * definitions. The directory lives **inside the project** by design so
+ * that team-shared assets — notably `.specship/workflows/*.yaml` — are
+ * checked in alongside the code they govern. Per-machine files (the DB,
+ * the lock, the daemon socket, log output) are gitignored by the
+ * `.gitignore` written into the folder on init.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SPECSHIP_DIR = void 0;
+exports.getSpecShipDir = getSpecShipDir;
+exports.isInitialized = isInitialized;
+exports.findNearestSpecShipRoot = findNearestSpecShipRoot;
+exports.createDirectory = createDirectory;
+exports.removeDirectory = removeDirectory;
+exports.listDirectoryContents = listDirectoryContents;
+exports.getDirectorySize = getDirectorySize;
+exports.ensureSubdirectory = ensureSubdirectory;
+exports.validateDirectory = validateDirectory;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+/**
+ * SpecShip directory name
+ */
+exports.SPECSHIP_DIR = '.specship';
+/**
+ * Get the .specship directory path for a project. All callers that
+ * compose subdirectories (artifacts, logs, lock files, daemon PID)
+ * should funnel through here so the layout has one source of truth.
+ */
+function getSpecShipDir(projectRoot) {
+    return path.join(projectRoot, exports.SPECSHIP_DIR);
+}
+/**
+ * Check if a project has been initialized with SpecShip.
+ * Requires both .specship/ directory AND specship.db to exist.
+ */
+function isInitialized(projectRoot) {
+    const specshipDir = getSpecShipDir(projectRoot);
+    if (!fs.existsSync(specshipDir) || !fs.statSync(specshipDir).isDirectory()) {
+        return false;
+    }
+    // Must have specship.db, not just .specship folder
+    const dbPath = path.join(specshipDir, 'specship.db');
+    return fs.existsSync(dbPath);
+}
+/**
+ * Find the nearest parent directory containing .specship/
+ *
+ * Walks up from the given path to find a SpecShip-initialized project,
+ * similar to how git finds .git/ directories.
+ *
+ * @param startPath - Directory to start searching from
+ * @returns The project root containing .specship/, or null if not found
+ */
+function findNearestSpecShipRoot(startPath) {
+    let current = path.resolve(startPath);
+    const root = path.parse(current).root;
+    while (current !== root) {
+        if (isInitialized(current)) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break; // Reached filesystem root
+        current = parent;
+    }
+    // Check root as well
+    if (isInitialized(current)) {
+        return current;
+    }
+    return null;
+}
+/**
+ * Create the .specship directory structure
+ * Note: Only throws if specship.db already exists, not just if .specship/ exists.
+ */
+function createDirectory(projectRoot) {
+    const specshipDir = getSpecShipDir(projectRoot);
+    const dbPath = path.join(specshipDir, 'specship.db');
+    // Only throw if SpecShip is actually initialized (db exists)
+    // .specship/ folder alone is fine
+    if (fs.existsSync(dbPath)) {
+        throw new Error(`SpecShip already initialized in ${projectRoot}`);
+    }
+    // Create main directory (if it doesn't exist)
+    fs.mkdirSync(specshipDir, { recursive: true });
+    // Create .gitignore inside .specship (if it doesn't exist)
+    const gitignorePath = path.join(specshipDir, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+        const gitignoreContent = `# SpecShip data files — local to each machine, not for committing.
+# Ignore everything in .specship/ except this file itself, so transient
+# files (the database, daemon.pid, sockets, logs) never show up in git.
+# Team-shared content (workflows/*.yaml) should be explicitly !-allowed
+# below if you want it tracked.
+*
+!.gitignore
+!workflows/
+!workflows/**
+`;
+        fs.writeFileSync(gitignorePath, gitignoreContent, 'utf-8');
+    }
+}
+/**
+ * Remove the .specship directory
+ */
+function removeDirectory(projectRoot) {
+    const specshipDir = getSpecShipDir(projectRoot);
+    if (!fs.existsSync(specshipDir)) {
+        return;
+    }
+    // Verify .specship is a real directory, not a symlink pointing elsewhere
+    const lstat = fs.lstatSync(specshipDir);
+    if (lstat.isSymbolicLink()) {
+        // Only remove the symlink itself, never follow it for recursive delete
+        fs.unlinkSync(specshipDir);
+        return;
+    }
+    if (!lstat.isDirectory()) {
+        // Not a directory - remove the single file
+        fs.unlinkSync(specshipDir);
+        return;
+    }
+    // Recursively remove directory
+    fs.rmSync(specshipDir, { recursive: true, force: true });
+}
+/**
+ * Get all files in the .specship directory
+ */
+function listDirectoryContents(projectRoot) {
+    const specshipDir = getSpecShipDir(projectRoot);
+    if (!fs.existsSync(specshipDir)) {
+        return [];
+    }
+    const files = [];
+    function walkDir(dir, prefix = '') {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            const relativePath = prefix ? `${prefix}/${entry.name}` : entry.name;
+            // Skip symlinks to prevent following links outside .specship
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            if (entry.isDirectory()) {
+                walkDir(path.join(dir, entry.name), relativePath);
+            }
+            else {
+                files.push(relativePath);
+            }
+        }
+    }
+    walkDir(specshipDir);
+    return files;
+}
+/**
+ * Get the total size of the .specship directory in bytes
+ */
+function getDirectorySize(projectRoot) {
+    const specshipDir = getSpecShipDir(projectRoot);
+    if (!fs.existsSync(specshipDir)) {
+        return 0;
+    }
+    let totalSize = 0;
+    function walkDir(dir) {
+        const entries = fs.readdirSync(dir, { withFileTypes: true });
+        for (const entry of entries) {
+            // Skip symlinks to prevent following links outside .specship
+            if (entry.isSymbolicLink()) {
+                continue;
+            }
+            const fullPath = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                walkDir(fullPath);
+            }
+            else {
+                const stats = fs.statSync(fullPath);
+                totalSize += stats.size;
+            }
+        }
+    }
+    walkDir(specshipDir);
+    return totalSize;
+}
+/**
+ * Ensure a subdirectory exists within .specship
+ */
+function ensureSubdirectory(projectRoot, subdirName) {
+    if (subdirName.includes('..') || subdirName.includes(path.sep) || subdirName.includes('/')) {
+        throw new Error(`Invalid subdirectory name: ${subdirName}`);
+    }
+    const subdirPath = path.join(getSpecShipDir(projectRoot), subdirName);
+    if (!fs.existsSync(subdirPath)) {
+        fs.mkdirSync(subdirPath, { recursive: true });
+    }
+    return subdirPath;
+}
+/**
+ * Check if the .specship directory has valid structure
+ */
+function validateDirectory(projectRoot) {
+    const errors = [];
+    const specshipDir = getSpecShipDir(projectRoot);
+    if (!fs.existsSync(specshipDir)) {
+        errors.push('SpecShip directory does not exist');
+        return { valid: false, errors };
+    }
+    if (!fs.statSync(specshipDir).isDirectory()) {
+        errors.push('.specship exists but is not a directory');
+        return { valid: false, errors };
+    }
+    // Auto-repair missing .gitignore (non-critical file)
+    const gitignorePath = path.join(specshipDir, '.gitignore');
+    if (!fs.existsSync(gitignorePath)) {
+        try {
+            const gitignoreContent = `# SpecShip data files — local to each machine, not for committing.\n# Ignore everything in .specship/ except this file itself, so transient\n# files (the database, daemon.pid, sockets, logs) never show up in git.\n*\n!.gitignore\n`;
+            fs.writeFileSync(gitignorePath, gitignoreContent, 'utf-8');
+        }
+        catch {
+            // Non-fatal: warn but don't block
+            errors.push('.gitignore missing in .specship directory and could not be created');
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+    };
+}
+//# sourceMappingURL=directory.js.map

package/dist/directory.js.map

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

package/dist/enforce/enforce.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Enforcement mode (REQ-ENFORCE-001 / 002 / 003).
+ *
+ * Composes SpecShip's checks — spec↔code drift, architecture fitness,
+ * maintainability, and the spec→test→verify behaviour chain — into a single
+ * report whose gating subset can fail CI. Strictly opt-in: with no gating
+ * configuration every check is advisory and the run passes, so turning SpecShip
+ * on in an existing repo never breaks a build (REQ-ENFORCE-002.A2).
+ *
+ * `evaluateEnforcement` is a pure function over a `deps` snapshot so it is
+ * testable without a database; SpecShip.getEnforce() assembles the snapshot.
+ *
+ * The behaviour chain reuses the existing spec-link machinery: a `tests` link
+ * from a requirement (or its acceptance criteria) to a test symbol, in the
+ * `verified` (passing) or `broken` (ran-and-failed) state.
+ */
+import { SpecLink } from './../types';
+import { FitnessReport } from '../fitness/fitness';
+import { MaintainabilityReport } from '../graph/maintainability';
+export type CheckName = 'drift' | 'fitness' | 'maintainability' | 'behaviour';
+/** Which checks gate (fail CI) vs merely advise. Absent key → advisory. */
+export interface GateConfig {
+    drift?: boolean;
+    fitness?: boolean;
+    maintainability?: boolean;
+    behaviour?: boolean;
+}
+export interface EnforceConfig {
+    gate?: GateConfig;
+    /** Requirement IDs explicitly out of behaviour-gating scope (REQ-ENFORCE-003.A4). */
+    behaviour?: {
+        exclude?: string[];
+    };
+}
+/** Tests-link summary for one requirement (its own + its acceptance criteria's). */
+export interface RequirementVerification {
+    id: string;
+    title: string;
+    /** All `tests`-kind links for the requirement and its acceptance children. */
+    testsLinks: SpecLink[];
+}
+export interface EnforceDeps {
+    /** Links currently in drifted / broken / orphaned state. */
+    drift: SpecLink[];
+    fitness: FitnessReport;
+    maintainability: MaintainabilityReport;
+    requirements: RequirementVerification[];
+}
+export interface CheckOutcome {
+    check: CheckName;
+    gating: boolean;
+    passed: boolean;
+    findings: string[];
+}
+export interface EnforceReport {
+    checks: CheckOutcome[];
+    /** Names of gating checks that failed. */
+    gatedFailures: CheckName[];
+    /** True when no gating check failed (CI gate result). */
+    passed: boolean;
+}
+export declare function evaluateEnforcement(deps: EnforceDeps, config?: EnforceConfig): EnforceReport;
+/** Default name of the checked-in project config file at the project root. */
+export declare const ENFORCE_CONFIG_FILE = "specship.config.json";
+/**
+ * Load the enforcement config from `specship.config.json` (`enforce`). Missing
+ * or unparseable → `{}` (all checks advisory — the opt-in default).
+ */
+export declare function loadEnforceConfig(projectRoot: string): EnforceConfig;
+//# sourceMappingURL=enforce.d.ts.map

package/dist/enforce/enforce.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"enforce.d.ts","sourceRoot":"","sources":["../../src/enforce/enforce.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACnD,OAAO,EAAE,qBAAqB,EAAE,MAAM,0BAA0B,CAAC;AAEjE,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,iBAAiB,GAAG,WAAW,CAAC;AAE9E,2EAA2E;AAC3E,MAAM,WAAW,UAAU;IACzB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB,qFAAqF;IACrF,SAAS,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;KAAE,CAAC;CACpC;AAED,oFAAoF;AACpF,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,8EAA8E;IAC9E,UAAU,EAAE,QAAQ,EAAE,CAAC;CACxB;AAED,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,KAAK,EAAE,QAAQ,EAAE,CAAC;IAClB,OAAO,EAAE,aAAa,CAAC;IACvB,eAAe,EAAE,qBAAqB,CAAC;IACvC,YAAY,EAAE,uBAAuB,EAAE,CAAC;CACzC;AAED,MAAM,WAAW,YAAY;IAC3B,KAAK,EAAE,SAAS,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,aAAa;IAC5B,MAAM,EAAE,YAAY,EAAE,CAAC;IACvB,0CAA0C;IAC1C,aAAa,EAAE,SAAS,EAAE,CAAC;IAC3B,yDAAyD;IACzD,MAAM,EAAE,OAAO,CAAC;CACjB;AAED,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,WAAW,EAAE,MAAM,GAAE,aAAkB,GAAG,aAAa,CAoDhG;AAED,8EAA8E;AAC9E,eAAO,MAAM,mBAAmB,yBAAyB,CAAC;AAE1D;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,aAAa,CASpE"}

package/dist/enforce/enforce.js

@@ -0,0 +1,125 @@
+"use strict";
+/**
+ * Enforcement mode (REQ-ENFORCE-001 / 002 / 003).
+ *
+ * Composes SpecShip's checks — spec↔code drift, architecture fitness,
+ * maintainability, and the spec→test→verify behaviour chain — into a single
+ * report whose gating subset can fail CI. Strictly opt-in: with no gating
+ * configuration every check is advisory and the run passes, so turning SpecShip
+ * on in an existing repo never breaks a build (REQ-ENFORCE-002.A2).
+ *
+ * `evaluateEnforcement` is a pure function over a `deps` snapshot so it is
+ * testable without a database; SpecShip.getEnforce() assembles the snapshot.
+ *
+ * The behaviour chain reuses the existing spec-link machinery: a `tests` link
+ * from a requirement (or its acceptance criteria) to a test symbol, in the
+ * `verified` (passing) or `broken` (ran-and-failed) state.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ENFORCE_CONFIG_FILE = void 0;
+exports.evaluateEnforcement = evaluateEnforcement;
+exports.loadEnforceConfig = loadEnforceConfig;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+function evaluateEnforcement(deps, config = {}) {
+    const gate = config.gate ?? {};
+    const exclude = new Set(config.behaviour?.exclude ?? []);
+    const checks = [];
+    // --- drift ---
+    {
+        const findings = deps.drift.map((l) => `${l.specId} ${l.state} → ${l.targetQualifiedName}`);
+        checks.push({ check: 'drift', gating: gate.drift === true, passed: findings.length === 0, findings });
+    }
+    // --- fitness ---
+    {
+        const findings = [
+            ...deps.fitness.configErrors.map((e) => `config error: ${e.rule} — ${e.message}`),
+            ...deps.fitness.violations.map((v) => `${v.rule}: ${v.source} → ${v.target} (${v.location})`),
+        ];
+        checks.push({ check: 'fitness', gating: gate.fitness === true, passed: deps.fitness.clean, findings });
+    }
+    // --- maintainability ---
+    {
+        const m = deps.maintainability;
+        const findings = m.clean ? [] : [
+            ...(m.coupling.length ? [`${m.coupling.length} coupling hotspot(s)`] : []),
+            ...(m.oversized.length ? [`${m.oversized.length} oversized symbol(s)`] : []),
+            ...(m.godFiles.length ? [`${m.godFiles.length} god-file(s)`] : []),
+            ...(m.cycles.length ? [`${m.cycles.length} dependency cycle(s)`] : []),
+            ...(m.deadCode.length ? [`${m.deadCode.length} dead-code candidate(s)`] : []),
+        ];
+        checks.push({ check: 'maintainability', gating: gate.maintainability === true, passed: m.clean, findings });
+    }
+    // --- behaviour (spec→test→verify) ---
+    {
+        const findings = [];
+        for (const req of deps.requirements) {
+            if (exclude.has(req.id))
+                continue; // out of behaviour-gating scope (A4)
+            const tests = req.testsLinks;
+            const broken = tests.filter((l) => l.state === 'broken');
+            const verified = tests.filter((l) => l.state === 'verified');
+            if (broken.length > 0) {
+                findings.push(`${req.id}: verification broken — ${broken.map((l) => l.targetQualifiedName).join(', ')}`); // A2
+            }
+            else if (verified.length === 0) {
+                findings.push(`${req.id}: unverified — no passing test links it`); // A3
+            }
+        }
+        checks.push({ check: 'behaviour', gating: gate.behaviour === true, passed: findings.length === 0, findings });
+    }
+    const gatedFailures = checks.filter((c) => c.gating && !c.passed).map((c) => c.check);
+    return { checks, gatedFailures, passed: gatedFailures.length === 0 };
+}
+/** Default name of the checked-in project config file at the project root. */
+exports.ENFORCE_CONFIG_FILE = 'specship.config.json';
+/**
+ * Load the enforcement config from `specship.config.json` (`enforce`). Missing
+ * or unparseable → `{}` (all checks advisory — the opt-in default).
+ */
+function loadEnforceConfig(projectRoot) {
+    try {
+        const raw = fs.readFileSync(path.join(projectRoot, exports.ENFORCE_CONFIG_FILE), 'utf-8');
+        const cfg = JSON.parse(raw);
+        if (cfg?.enforce && typeof cfg.enforce === 'object')
+            return cfg.enforce;
+    }
+    catch {
+        // no config / unparseable → advisory-only
+    }
+    return {};
+}
+//# sourceMappingURL=enforce.js.map

package/dist/enforce/enforce.js.map

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