@libar-dev/architect 1.0.0-pre.3

package/dist/lint/index.d.ts

@@ -0,0 +1,26 @@
+/**
+ * @architect
+ * @architect-lint
+ * @architect-pattern LintModule
+ * @architect-status completed
+ * @architect-uses LintRules, LintEngine
+ *
+ * ## LintModule - Annotation Quality Checking
+ *
+ * Provides lint rules and engine for pattern annotation quality checking.
+ * Exports the complete lint API including rules, engine, and formatters.
+ *
+ * ### When to Use
+ *
+ * - Use when importing lint functionality into CLI or other consumers
+ * - Use for accessing both rules and engine from a single import
+ */
+export type { LintSeverity, LintViolation } from '../validation-schemas/lint.js';
+export type { LintRule, LintContext } from './rules.js';
+export { defaultRules, filterRulesBySeverity, missingPatternName, invalidStatus, missingStatus, missingWhenToUse, tautologicalDescription, missingRelationships, patternConflictInImplements, missingRelationshipTarget, } from './rules.js';
+export type { LintResult, LintSummary, DirectiveWithLocation } from './engine.js';
+export { lintDirective, lintFiles, hasFailures, sortViolationsBySeverity, formatPretty, formatJson, } from './engine.js';
+export * from './process-guard/index.js';
+export { runStepLint, STEP_LINT_RULES } from './steps/index.js';
+export type { StepLintRule, FeatureStepPair, StepLintOptions } from './steps/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lint/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lint/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AACjF,YAAY,EAAE,QAAQ,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AAGpB,YAAY,EAAE,UAAU,EAAE,WAAW,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAClF,OAAO,EACL,aAAa,EACb,SAAS,EACT,WAAW,EACX,wBAAwB,EACxB,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AAGrB,cAAc,0BAA0B,CAAC;AAGzC,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AAChE,YAAY,EAAE,YAAY,EAAE,eAAe,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/lint/index.js

@@ -0,0 +1,24 @@
+/**
+ * @architect
+ * @architect-lint
+ * @architect-pattern LintModule
+ * @architect-status completed
+ * @architect-uses LintRules, LintEngine
+ *
+ * ## LintModule - Annotation Quality Checking
+ *
+ * Provides lint rules and engine for pattern annotation quality checking.
+ * Exports the complete lint API including rules, engine, and formatters.
+ *
+ * ### When to Use
+ *
+ * - Use when importing lint functionality into CLI or other consumers
+ * - Use for accessing both rules and engine from a single import
+ */
+export { defaultRules, filterRulesBySeverity, missingPatternName, invalidStatus, missingStatus, missingWhenToUse, tautologicalDescription, missingRelationships, patternConflictInImplements, missingRelationshipTarget, } from './rules.js';
+export { lintDirective, lintFiles, hasFailures, sortViolationsBySeverity, formatPretty, formatJson, } from './engine.js';
+// Process Guard (FSM validation, change detection, protection enforcement)
+export * from './process-guard/index.js';
+// Step Lint (vitest-cucumber feature/step compatibility checking)
+export { runStepLint, STEP_LINT_RULES } from './steps/index.js';
+//# sourceMappingURL=index.js.map

package/dist/lint/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/lint/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH,OAAO,EACL,YAAY,EACZ,qBAAqB,EACrB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,gBAAgB,EAChB,uBAAuB,EACvB,oBAAoB,EACpB,2BAA2B,EAC3B,yBAAyB,GAC1B,MAAM,YAAY,CAAC;AAIpB,OAAO,EACL,aAAa,EACb,SAAS,EACT,WAAW,EACX,wBAAwB,EACxB,YAAY,EACZ,UAAU,GACX,MAAM,aAAa,CAAC;AAErB,2EAA2E;AAC3E,cAAc,0BAA0B,CAAC;AAEzC,kEAAkE;AAClE,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/lint/process-guard/decider.d.ts

@@ -0,0 +1,166 @@
+/**
+ * @architect
+ * @architect-lint
+ * @architect-pattern ProcessGuardDecider
+ * @architect-status active
+ * @architect-arch-role decider
+ * @architect-arch-context lint
+ * @architect-arch-layer application
+ * @architect-implements ProcessGuardLinter
+ * @architect-uses FSMValidator, DeriveProcessState, DetectChanges
+ * @architect-depends-on:FSMValidator,DeriveProcessState,DetectChanges
+ * @architect-convention process-guard-errors
+ * @architect-extract-shapes validateChanges
+ *
+ * ## ProcessGuardDecider - Pure Validation Logic
+ *
+ * Pure function that validates changes against process rules.
+ * Follows the Decider pattern from platform-core: no I/O, no side effects.
+ *
+ * ### When to Use
+ *
+ * - When validating proposed changes against workflow rules
+ * - When implementing custom validation rules for the process guard
+ * - When building pre-commit hooks that enforce FSM transitions
+ *
+ * ### Design Principles
+ *
+ * - **Pure Function**: (state, changes, options) => result
+ * - **No I/O**: All data passed in, no file reads
+ * - **Composable Rules**: Rules are separate functions combined in decider
+ * - **Testable**: Easy to unit test with mock data
+ *
+ * ### Rules Implemented
+ *
+ * 1. **Protection Level** - Completed files require unlock-reason
+ * 2. **Status Transition** - Transitions must follow PDR-005 FSM
+ * 3. **Scope Creep** - Active specs cannot add new deliverables
+ * 4. **Session Scope** - Modifications outside session scope warn
+ *
+ * ### Error Guide Content (convention: process-guard-errors)
+ *
+ * ## completed-protection
+ *
+ * **Invariant:** Completed specs are immutable without an explicit unlock
+ * reason. The unlock reason must be at least 10 characters and cannot be
+ * a placeholder.
+ *
+ * **Rationale:** The `completed` status represents verified, accepted work.
+ * Allowing silent modification undermines the terminal-state guarantee.
+ * Requiring an unlock reason creates an audit trail and forces the developer
+ * to justify why completed work needs revisiting.
+ *
+ * | Situation | Solution | Example |
+ * |-----------|----------|---------|
+ * | Fix typo in completed spec | Add unlock reason tag | `@architect-unlock-reason:Fix-typo-in-FSM-diagram` |
+ * | Spec needs rework | Create new spec instead | New feature file with `roadmap` status |
+ * | Legacy import | Multiple transitions in one commit | Set `roadmap` then `completed` |
+ *
+ * ## invalid-status-transition
+ *
+ * **Invariant:** Status transitions must follow the PDR-005 FSM path.
+ * The only valid paths are: roadmap to active, roadmap to deferred,
+ * active to completed, active to roadmap, deferred to roadmap.
+ *
+ * **Rationale:** The FSM enforces a deliberate progression through
+ * planning, implementation, and completion. Skipping states (e.g.,
+ * roadmap to completed) means work was never tracked as active, breaking
+ * session scoping and deliverable validation.
+ *
+ * | Attempted | Why Invalid | Valid Path |
+ * |-----------|-------------|------------|
+ * | roadmap to completed | Must go through active | roadmap to active to completed |
+ * | deferred to active | Must return to roadmap first | deferred to roadmap to active |
+ * | deferred to completed | Cannot skip two states | deferred to roadmap to active to completed |
+ *
+ * ## scope-creep
+ *
+ * **Invariant:** Active specs cannot add new deliverables. Scope is locked
+ * when status transitions to `active`.
+ *
+ * **Rationale:** Prevents scope creep during implementation. Plan fully
+ * before starting; implement what was planned. Adding deliverables mid-
+ * implementation signals inadequate planning and risks incomplete work.
+ *
+ * | Situation | Solution | Example |
+ * |-----------|----------|---------|
+ * | Need new deliverable | Revert to roadmap first | Change status to roadmap, add deliverable, then back to active |
+ * | Discovered work during implementation | Create new spec | New feature file for the discovered work |
+ *
+ * ## session-scope
+ *
+ * **Invariant:** Files outside the active session scope trigger warnings
+ * to prevent accidental cross-session modifications.
+ *
+ * **Rationale:** Session scoping ensures focused work. Modifying files
+ * outside the session scope often indicates scope creep or working on
+ * the wrong task. The warning is informational (not blocking) to allow
+ * intentional cross-scope changes with `--ignore-session`.
+ *
+ * ## session-excluded
+ *
+ * **Invariant:** Files explicitly excluded from a session cannot be
+ * modified in that session. This is a hard error, not a warning.
+ *
+ * **Rationale:** Explicit exclusion is a deliberate decision to protect
+ * certain files from modification during a session. Unlike session-scope
+ * (warning), exclusion represents a conscious boundary that should not
+ * be violated without changing the session configuration.
+ *
+ * ## deliverable-removed
+ *
+ * **Invariant:** Removing a deliverable from an active spec triggers a
+ * warning to ensure the removal is intentional and documented.
+ *
+ * **Rationale:** Deliverable removal during active implementation may
+ * indicate descoping or completion elsewhere. The warning ensures
+ * visibility -- the commit message should document why the deliverable
+ * was removed.
+ */
+import type { ValidationResult, ProcessViolation, DeciderInput, DeciderOutput, ProcessGuardRule } from './types.js';
+/**
+ * Validate changes against process rules.
+ *
+ * Pure function following the Decider pattern:
+ * - Takes all inputs explicitly (no hidden state)
+ * - Returns result without side effects
+ * - Emits events for observability
+ *
+ * @param input - Complete input including state, changes, and options
+ * @returns DeciderOutput with validation result and events
+ *
+ * @example
+ * ```typescript
+ * const output = validateChanges({
+ *   state: processState,
+ *   changes: changeDetection,
+ *   options: { strict: false, ignoreSession: false },
+ * });
+ *
+ * if (!output.result.valid) {
+ *   console.log('Violations:', output.result.violations);
+ * }
+ * ```
+ */
+export declare function validateChanges(input: DeciderInput): DeciderOutput;
+/**
+ * Check if validation result has any errors.
+ */
+export declare function hasErrors(result: ValidationResult): boolean;
+/**
+ * Check if validation result has any warnings.
+ */
+export declare function hasWarnings(result: ValidationResult): boolean;
+/**
+ * Get all violations and warnings combined.
+ */
+export declare function getAllIssues(result: ValidationResult): readonly ProcessViolation[];
+/**
+ * Filter violations by rule.
+ */
+export declare function getViolationsByRule(result: ValidationResult, rule: ProcessGuardRule): readonly ProcessViolation[];
+/**
+ * Create a summary string for the validation result.
+ */
+export declare function summarizeResult(result: ValidationResult): string;
+//# sourceMappingURL=decider.d.ts.map

package/dist/lint/process-guard/decider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decider.d.ts","sourceRoot":"","sources":["../../../src/lint/process-guard/decider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsHG;AAQH,OAAO,KAAK,EAGV,gBAAgB,EAChB,gBAAgB,EAEhB,YAAY,EACZ,aAAa,EAEb,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAQpB;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,YAAY,GAAG,aAAa,CAoElE;AAuPD;;GAEG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAE3D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,gBAAgB,GAAG,OAAO,CAE7D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,gBAAgB,GAAG,SAAS,gBAAgB,EAAE,CAElF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,gBAAgB,EACxB,IAAI,EAAE,gBAAgB,GACrB,SAAS,gBAAgB,EAAE,CAE7B;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,gBAAgB,GAAG,MAAM,CAiBhE"}

package/dist/lint/process-guard/decider.js

@@ -0,0 +1,412 @@
+/**
+ * @architect
+ * @architect-lint
+ * @architect-pattern ProcessGuardDecider
+ * @architect-status active
+ * @architect-arch-role decider
+ * @architect-arch-context lint
+ * @architect-arch-layer application
+ * @architect-implements ProcessGuardLinter
+ * @architect-uses FSMValidator, DeriveProcessState, DetectChanges
+ * @architect-depends-on:FSMValidator,DeriveProcessState,DetectChanges
+ * @architect-convention process-guard-errors
+ * @architect-extract-shapes validateChanges
+ *
+ * ## ProcessGuardDecider - Pure Validation Logic
+ *
+ * Pure function that validates changes against process rules.
+ * Follows the Decider pattern from platform-core: no I/O, no side effects.
+ *
+ * ### When to Use
+ *
+ * - When validating proposed changes against workflow rules
+ * - When implementing custom validation rules for the process guard
+ * - When building pre-commit hooks that enforce FSM transitions
+ *
+ * ### Design Principles
+ *
+ * - **Pure Function**: (state, changes, options) => result
+ * - **No I/O**: All data passed in, no file reads
+ * - **Composable Rules**: Rules are separate functions combined in decider
+ * - **Testable**: Easy to unit test with mock data
+ *
+ * ### Rules Implemented
+ *
+ * 1. **Protection Level** - Completed files require unlock-reason
+ * 2. **Status Transition** - Transitions must follow PDR-005 FSM
+ * 3. **Scope Creep** - Active specs cannot add new deliverables
+ * 4. **Session Scope** - Modifications outside session scope warn
+ *
+ * ### Error Guide Content (convention: process-guard-errors)
+ *
+ * ## completed-protection
+ *
+ * **Invariant:** Completed specs are immutable without an explicit unlock
+ * reason. The unlock reason must be at least 10 characters and cannot be
+ * a placeholder.
+ *
+ * **Rationale:** The `completed` status represents verified, accepted work.
+ * Allowing silent modification undermines the terminal-state guarantee.
+ * Requiring an unlock reason creates an audit trail and forces the developer
+ * to justify why completed work needs revisiting.
+ *
+ * | Situation | Solution | Example |
+ * |-----------|----------|---------|
+ * | Fix typo in completed spec | Add unlock reason tag | `@architect-unlock-reason:Fix-typo-in-FSM-diagram` |
+ * | Spec needs rework | Create new spec instead | New feature file with `roadmap` status |
+ * | Legacy import | Multiple transitions in one commit | Set `roadmap` then `completed` |
+ *
+ * ## invalid-status-transition
+ *
+ * **Invariant:** Status transitions must follow the PDR-005 FSM path.
+ * The only valid paths are: roadmap to active, roadmap to deferred,
+ * active to completed, active to roadmap, deferred to roadmap.
+ *
+ * **Rationale:** The FSM enforces a deliberate progression through
+ * planning, implementation, and completion. Skipping states (e.g.,
+ * roadmap to completed) means work was never tracked as active, breaking
+ * session scoping and deliverable validation.
+ *
+ * | Attempted | Why Invalid | Valid Path |
+ * |-----------|-------------|------------|
+ * | roadmap to completed | Must go through active | roadmap to active to completed |
+ * | deferred to active | Must return to roadmap first | deferred to roadmap to active |
+ * | deferred to completed | Cannot skip two states | deferred to roadmap to active to completed |
+ *
+ * ## scope-creep
+ *
+ * **Invariant:** Active specs cannot add new deliverables. Scope is locked
+ * when status transitions to `active`.
+ *
+ * **Rationale:** Prevents scope creep during implementation. Plan fully
+ * before starting; implement what was planned. Adding deliverables mid-
+ * implementation signals inadequate planning and risks incomplete work.
+ *
+ * | Situation | Solution | Example |
+ * |-----------|----------|---------|
+ * | Need new deliverable | Revert to roadmap first | Change status to roadmap, add deliverable, then back to active |
+ * | Discovered work during implementation | Create new spec | New feature file for the discovered work |
+ *
+ * ## session-scope
+ *
+ * **Invariant:** Files outside the active session scope trigger warnings
+ * to prevent accidental cross-session modifications.
+ *
+ * **Rationale:** Session scoping ensures focused work. Modifying files
+ * outside the session scope often indicates scope creep or working on
+ * the wrong task. The warning is informational (not blocking) to allow
+ * intentional cross-scope changes with `--ignore-session`.
+ *
+ * ## session-excluded
+ *
+ * **Invariant:** Files explicitly excluded from a session cannot be
+ * modified in that session. This is a hard error, not a warning.
+ *
+ * **Rationale:** Explicit exclusion is a deliberate decision to protect
+ * certain files from modification during a session. Unlike session-scope
+ * (warning), exclusion represents a conscious boundary that should not
+ * be violated without changing the session configuration.
+ *
+ * ## deliverable-removed
+ *
+ * **Invariant:** Removing a deliverable from an active spec triggers a
+ * warning to ensure the removal is intentional and documented.
+ *
+ * **Rationale:** Deliverable removal during active implementation may
+ * indicate descoping or completion elsewhere. The warning ensures
+ * visibility -- the commit message should document why the deliverable
+ * was removed.
+ */
+import { validateTransition, getValidTransitionsFrom, isTerminalState, } from '../../validation/fsm/index.js';
+import { isInSessionScope, isSessionExcluded } from './derive-state.js';
+import { DEFAULT_TAG_PREFIX } from '../../config/defaults.js';
+// =============================================================================
+// Decider - Main Entry Point
+// =============================================================================
+/**
+ * Validate changes against process rules.
+ *
+ * Pure function following the Decider pattern:
+ * - Takes all inputs explicitly (no hidden state)
+ * - Returns result without side effects
+ * - Emits events for observability
+ *
+ * @param input - Complete input including state, changes, and options
+ * @returns DeciderOutput with validation result and events
+ *
+ * @example
+ * ```typescript
+ * const output = validateChanges({
+ *   state: processState,
+ *   changes: changeDetection,
+ *   options: { strict: false, ignoreSession: false },
+ * });
+ *
+ * if (!output.result.valid) {
+ *   console.log('Violations:', output.result.violations);
+ * }
+ * ```
+ */
+export function validateChanges(input) {
+    const { state, changes, options } = input;
+    const events = [];
+    const violations = [];
+    const warnings = [];
+    // Emit start event
+    const allFiles = [...changes.modifiedFiles, ...changes.addedFiles];
+    events.push({ type: 'validation_started', fileCount: allFiles.length });
+    // Run each rule
+    const rules = [
+        {
+            rule: 'completed-protection',
+            fn: () => checkProtectionLevel(state, changes, options.registry),
+        },
+        {
+            rule: 'invalid-status-transition',
+            fn: () => checkStatusTransitions(state, changes),
+        },
+        { rule: 'scope-creep', fn: () => checkScopeCreep(state, changes) },
+        {
+            rule: 'session-scope',
+            fn: () => (options.ignoreSession ? [] : checkSessionScope(state, changes)),
+        },
+        {
+            rule: 'session-excluded',
+            fn: () => (options.ignoreSession ? [] : checkSessionExcluded(state, changes)),
+        },
+    ];
+    for (const { rule, fn } of rules) {
+        const ruleViolations = fn();
+        const passed = ruleViolations.length === 0;
+        events.push({ type: 'rule_checked', rule, passed });
+        for (const v of ruleViolations) {
+            if (v.severity === 'error') {
+                violations.push(v);
+            }
+            else {
+                warnings.push(v);
+            }
+        }
+    }
+    // In strict mode, promote warnings to violations
+    const finalViolations = options.strict
+        ? [...violations, ...warnings.map((w) => ({ ...w, severity: 'error' }))]
+        : violations;
+    const finalWarnings = options.strict ? [] : warnings;
+    const valid = finalViolations.length === 0;
+    events.push({
+        type: 'validation_completed',
+        valid,
+        violationCount: finalViolations.length,
+    });
+    return {
+        result: {
+            valid,
+            violations: finalViolations,
+            warnings: finalWarnings,
+            processState: state,
+            changes,
+        },
+        events,
+    };
+}
+// =============================================================================
+// Rule: Protection Level
+// =============================================================================
+/**
+ * Check protection level violations.
+ *
+ * - Completed (hard) files require unlock-reason tag
+ * - Returns error if modified without unlock
+ *
+ * @param state - Current process state
+ * @param changes - Detected changes
+ * @param registry - Optional tag registry for prefix-aware messages
+ */
+function checkProtectionLevel(state, changes, registry) {
+    const tagPrefix = registry?.tagPrefix ?? DEFAULT_TAG_PREFIX;
+    const violations = [];
+    for (const file of [...changes.modifiedFiles, ...changes.addedFiles]) {
+        const fileState = state.files.get(file);
+        if (!fileState)
+            continue;
+        // Check hard protection (completed)
+        if (fileState.protection === 'hard' && !fileState.hasUnlockReason) {
+            // Exempt files transitioning TO a terminal state — this is a completion, not a post-completion edit
+            const transition = changes.statusTransitions.get(file);
+            if (transition !== undefined && isTerminalState(transition.to)) {
+                continue;
+            }
+            violations.push(createViolation('completed-protection', 'error', `Cannot modify completed spec '${file}' without unlock reason`, file, `Add ${tagPrefix}unlock-reason:'your reason' to proceed`));
+        }
+    }
+    return violations;
+}
+// =============================================================================
+// Rule: Status Transitions
+// =============================================================================
+/**
+ * Check status transition validity.
+ *
+ * Uses FSM validation from phase-state-machine module.
+ * Enhanced error messages include line numbers and docstring context.
+ */
+function checkStatusTransitions(state, changes) {
+    const violations = [];
+    for (const [file, transition] of changes.statusTransitions) {
+        // Only validated unlock reasons bypass FSM, and only for retroactive completion paths
+        const fileState = state.files.get(file);
+        if (transition.to === 'completed' &&
+            transition.hasUnlockReason === true &&
+            fileState?.hasUnlockReason === true) {
+            continue;
+        }
+        const validationResult = validateTransition(transition.from, transition.to);
+        if (!validationResult.valid) {
+            const validTransitions = getValidTransitionsFrom(transition.from);
+            // Build detailed message with context
+            const fileContext = transition.isNewFile === true ? ' (new file)' : '';
+            const lineInfo = transition.toLocation ? ` at line ${transition.toLocation.lineNumber}` : '';
+            const message = `Invalid status transition in '${file}'${fileContext}${lineInfo}: ${transition.from} → ${transition.to}`;
+            // Build suggestion with debugging hints
+            let suggestion = `Valid transitions from '${transition.from}': ${validTransitions.join(', ')}`;
+            // Add docstring debugging info if multiple tags were found
+            if (transition.allDetectedTags && transition.allDetectedTags.length > 1) {
+                const docstringTags = transition.allDetectedTags.filter((t) => t.insideDocstring);
+                if (docstringTags.length > 0) {
+                    suggestion += `\n    Note: ${docstringTags.length} status tag(s) inside docstrings were ignored`;
+                    suggestion += '\n    Detected tags:';
+                    for (const tag of transition.allDetectedTags) {
+                        const context = tag.insideDocstring ? ' [inside docstring - ignored]' : ' [file-level]';
+                        suggestion += `\n      Line ${tag.lineNumber}${context}`;
+                    }
+                }
+            }
+            violations.push(createViolation('invalid-status-transition', 'error', message, file, suggestion));
+        }
+    }
+    return violations;
+}
+// =============================================================================
+// Rule: Scope Creep
+// =============================================================================
+/**
+ * Check for scope creep (new deliverables in active specs).
+ *
+ * Active specs cannot add new deliverables.
+ */
+function checkScopeCreep(state, changes) {
+    const violations = [];
+    for (const [file, deliverableChange] of changes.deliverableChanges) {
+        const fileState = state.files.get(file);
+        if (!fileState)
+            continue;
+        // Only check active specs (scope-locked)
+        if (fileState.protection === 'scope' && deliverableChange.added.length > 0) {
+            violations.push(createViolation('scope-creep', 'error', `Cannot add deliverables to active spec '${file}': ${deliverableChange.added.join(', ')}`, file, 'Create new spec or revert to roadmap status first'));
+        }
+        // Warn about removed deliverables
+        if (deliverableChange.removed.length > 0) {
+            violations.push(createViolation('deliverable-removed', 'warning', `Deliverable removed from '${file}': ${deliverableChange.removed.join(', ')}`, file, 'Was this completed or descoped? Consider documenting the reason.'));
+        }
+    }
+    return violations;
+}
+// =============================================================================
+// Rule: Session Scope
+// =============================================================================
+/**
+ * Check session scope violations.
+ *
+ * Files outside active session scope trigger warnings.
+ */
+function checkSessionScope(state, changes) {
+    const violations = [];
+    if (!state.activeSession) {
+        return violations; // No session, no scope rules
+    }
+    for (const file of [...changes.modifiedFiles, ...changes.addedFiles]) {
+        if (!isInSessionScope(state, file)) {
+            violations.push(createViolation('session-scope', 'warning', `File '${file}' is not in session scope`, file, `Add to session '${state.activeSession.id}' scope or use --ignore-session flag`));
+        }
+    }
+    return violations;
+}
+/**
+ * Check for explicitly excluded files.
+ *
+ * Explicitly excluded files trigger errors (not warnings).
+ */
+function checkSessionExcluded(state, changes) {
+    const violations = [];
+    if (!state.activeSession) {
+        return violations;
+    }
+    for (const file of [...changes.modifiedFiles, ...changes.addedFiles]) {
+        if (isSessionExcluded(state, file)) {
+            violations.push(createViolation('session-excluded', 'error', `File '${file}' is explicitly excluded from session '${state.activeSession.id}'`, file, 'This file was explicitly excluded and cannot be modified in this session'));
+        }
+    }
+    return violations;
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Create a process violation.
+ */
+function createViolation(rule, severity, message, file, suggestion) {
+    // Build violation (handle exactOptionalPropertyTypes)
+    const violation = { rule, severity, message, file };
+    // Only add suggestion if provided
+    if (suggestion !== undefined) {
+        violation.suggestion = suggestion;
+    }
+    return violation;
+}
+// =============================================================================
+// Convenience Functions
+// =============================================================================
+/**
+ * Check if validation result has any errors.
+ */
+export function hasErrors(result) {
+    return result.violations.length > 0;
+}
+/**
+ * Check if validation result has any warnings.
+ */
+export function hasWarnings(result) {
+    return result.warnings.length > 0;
+}
+/**
+ * Get all violations and warnings combined.
+ */
+export function getAllIssues(result) {
+    return [...result.violations, ...result.warnings];
+}
+/**
+ * Filter violations by rule.
+ */
+export function getViolationsByRule(result, rule) {
+    return result.violations.filter((v) => v.rule === rule);
+}
+/**
+ * Create a summary string for the validation result.
+ */
+export function summarizeResult(result) {
+    const errorCount = result.violations.length;
+    const warningCount = result.warnings.length;
+    if (result.valid && warningCount === 0) {
+        return 'Process guard check passed';
+    }
+    const parts = [];
+    if (errorCount > 0) {
+        parts.push(`${errorCount} error${errorCount !== 1 ? 's' : ''}`);
+    }
+    if (warningCount > 0) {
+        parts.push(`${warningCount} warning${warningCount !== 1 ? 's' : ''}`);
+    }
+    return `Process guard check: ${parts.join(', ')}`;
+}
+//# sourceMappingURL=decider.js.map

package/dist/lint/process-guard/decider.js.map

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