pumuki 6.3.7

package/docs/validation/phase8-external-rollout-pack.md

@@ -0,0 +1,168 @@
+# Phase 8 External Rollout Pack
+
+## Purpose
+
+Provide a single operational package to close external rollout blockers with deterministic artifacts and explicit handoff evidence.
+
+This runbook is read-only with respect to framework behavior. It does not change core gate logic.
+
+## Preconditions
+
+- Repository branch is up to date.
+- Consumer repository access is confirmed (`repo` + `actions:read` scopes).
+- Existing deterministic validation commands are available in this repository.
+
+## One-Shot Execution
+
+Run the orchestration command:
+
+```bash
+npm run validation:phase5-execution-closure -- \
+  --repo <owner>/<repo> \
+  --out-dir .audit-reports/phase5 \
+  --skip-workflow-lint
+```
+
+Strict mode (adapter readiness required):
+
+```bash
+npm run validation:phase5-execution-closure -- \
+  --repo <owner>/<repo> \
+  --out-dir .audit-reports/phase5 \
+  --repo-path /absolute/path/to/consumer-repo \
+  --actionlint-bin /tmp/actionlint-bin/actionlint \
+  --require-adapter-readiness
+```
+
+## Artifact Contract (Required)
+
+The rollout is considered externally handoff-ready only when all artifacts exist and meet the required verdict.
+
+| Artifact | Path | Required verdict |
+| --- | --- | --- |
+| Blockers readiness | `.audit-reports/phase5/phase5-blockers-readiness.md` | `READY` |
+| Closure status | `.audit-reports/phase5/phase5-execution-closure-status.md` | `READY` |
+| External handoff | `.audit-reports/phase5/phase5-external-handoff.md` | `READY` |
+| Orchestration run report | `.audit-reports/phase5/phase5-execution-closure-run-report.md` | Informational |
+
+Optional but recommended:
+
+| Artifact | Path | Required verdict |
+| --- | --- | --- |
+| Adapter readiness | `.audit-reports/adapter/adapter-readiness.md` | `READY` |
+| Adapter real-session report | `.audit-reports/adapter/adapter-real-session-report.md` | Informational |
+| Mock consumer A/B report | `.audit-reports/phase5/mock-consumer-ab-report.md` | `READY` |
+
+## External Runtime Incident Gate
+
+If external pre/post tool runtime still shows `node: command not found`:
+
+1. Execute `docs/validation/adapter-hook-runtime-validation.md`.
+2. Regenerate:
+   - `.audit-reports/adapter/adapter-session-status.md`
+   - `.audit-reports/adapter/adapter-real-session-report.md`
+   - `.audit-reports/adapter/adapter-readiness.md`
+3. Re-run Phase 5 execution closure command.
+
+## Handoff Template
+
+Use the following template as final rollout note:
+
+```md
+# Phase 8 External Rollout Handoff
+
+- Date: <YYYY-MM-DD>
+- Operator: <name>
+- Consumer repo: <owner/repo>
+- Branch/ref: <branch or sha>
+
+## Verification
+
+- [ ] phase5-blockers-readiness => READY
+- [ ] phase5-execution-closure-status => READY
+- [ ] phase5-external-handoff => READY
+- [ ] artifact URLs attached
+
+## Artifact URLs
+
+1. <url>
+2. <url>
+3. <url>
+
+## Notes
+
+- <incident updates, if any>
+```
+
+## Exit Criteria
+
+- All required artifact contract entries exist with required verdicts.
+- Handoff template is filled and shared with artifact URLs.
+- `docs/TODO.md` external rollout blocker items are updated.
+
+## Current Live Snapshot (2026-02-11)
+
+Latest regenerated external evidence (`.audit-reports/phase5-latest/*`) remains blocked:
+
+- `phase5-blockers-readiness.md`: `READY`
+- `phase5-execution-closure-status.md`: `BLOCKED`
+- `phase5-external-handoff.md`: `BLOCKED`
+- `consumer-startup-unblock-status.md`: `BLOCKED`
+- `consumer-startup-failure-support-bundle.md` signals:
+  - `startup_failure_runs: 0`
+  - `startup_stalled_runs: 8`
+  - `oldest_queued_run_age_minutes: 32`
+  - queued runs still show `jobs.total_count: 0` and `artifacts.total_count: 0`
+  - cancel attempts on queued runs return `HTTP 500`
+  - latest cancel request id sample: `86BD:50C44:E9BB08D:D8B86F4:698C4FC9`
+
+Latest controlled probe run URL:
+
+- `https://github.com/SwiftEnProfundidad/pumuki-actions-healthcheck-temp/actions/runs/21944339604`
+
+## Escalation Refresh Sequence (Phase5 Latest)
+
+Use this sequence to refresh the latest escalation evidence before opening/continuing a support case:
+
+```bash
+# one-shot helper (probe + closure + handoff + bundle checksum)
+npm run validation:phase5-latest:refresh -- \
+  SwiftEnProfundidad/pumuki-actions-healthcheck-temp \
+  8 \
+  .audit-reports/phase5-latest \
+  .audit-reports/phase5/mock-consumer-ab-report.md
+```
+
+Equivalent explicit steps:
+
+```bash
+# 1) Trigger a controlled probe run (consumer private repo)
+gh workflow run health.yml --repo <owner>/<repo>
+
+# 2) Recompute phase5 latest closure chain (consumer side only)
+npx --yes tsx@4.21.0 scripts/run-phase5-execution-closure.ts \
+  --repo <owner>/<repo> \
+  --limit 5 \
+  --out-dir .audit-reports/phase5-latest \
+  --skip-adapter \
+  --skip-workflow-lint
+
+# 3) Regenerate external handoff with explicit run URLs
+npx --yes tsx@4.21.0 scripts/build-phase5-external-handoff.ts \
+  --repo <owner>/<repo> \
+  --phase5-status-report .audit-reports/phase5-latest/phase5-execution-closure-status.md \
+  --phase5-blockers-report .audit-reports/phase5-latest/phase5-blockers-readiness.md \
+  --consumer-unblock-report .audit-reports/phase5-latest/consumer-startup-unblock-status.md \
+  --mock-ab-report .audit-reports/phase5/mock-consumer-ab-report.md \
+  --run-report .audit-reports/phase5-latest/phase5-execution-closure-run-report.md \
+  --artifact-url <run_url_1> \
+  --artifact-url <run_url_2> \
+  --out .audit-reports/phase5-latest/phase5-external-handoff.md
+```
+
+## Related References
+
+- `docs/validation/phase5-execution-closure.md`
+- `docs/validation/consumer-ci-startup-failure-playbook.md`
+- `docs/validation/adapter-hook-runtime-validation.md`
+- `docs/REFRACTOR_PROGRESS.md`

package/docs/validation/phase8-post-billing-reactivation-runbook.md

@@ -0,0 +1,133 @@
+# Phase 8 Post-Billing Reactivation Runbook
+
+## Purpose
+
+Resume Phase 8 closure deterministically after billing is reactivated in the consumer GitHub account.
+
+This runbook does not change framework logic; it only executes existing validation/orchestration commands.
+
+## Preconditions
+
+- Billing for GitHub Actions is reactivated/healthy in the consumer account.
+- Repository is on `enterprise-refactor` with latest changes.
+- `gh auth status` is healthy for the operator account.
+
+## One-Shot Resume (Preferred)
+
+```bash
+npm run validation:phase8:resume-after-billing -- \
+  SwiftEnProfundidad/pumuki-actions-healthcheck-temp \
+  8 \
+  .audit-reports/phase5-latest \
+  .audit-reports/phase5/mock-consumer-ab-report.md
+```
+
+Expected outcome:
+
+- Exit code `0`
+- `phase5-blockers-readiness`: `READY`
+- `phase5-execution-closure-status`: `READY`
+- `phase5-external-handoff`: `READY`
+- `consumer-startup-unblock-status`: `READY`
+
+## Operator Quick Block (Copy/Paste)
+
+Use this exact sequence right after billing is reactivated:
+
+```bash
+npm run validation:phase8:resume-after-billing -- \
+  SwiftEnProfundidad/pumuki-actions-healthcheck-temp \
+  8 \
+  .audit-reports/phase5-latest \
+  .audit-reports/phase5/mock-consumer-ab-report.md \
+&& npm run validation:phase5-latest:ready-check
+```
+
+Interpretation:
+
+- exit code `0`: Phase 8 chain is `READY` and you can continue with `P8-4`.
+- exit code `1`: still blocked; follow `If Still Blocked`.
+
+## Deterministic Verification
+
+Run the explicit gate check:
+
+```bash
+npm run validation:phase5-latest:ready-check
+```
+
+Expected:
+
+- Exit code `0`
+- No blocker report in `BLOCKED` state.
+
+Optional status helper (prints the next deterministic command):
+
+```bash
+npm run validation:phase8:next-step -- \
+  .audit-reports/phase5-latest \
+  SwiftEnProfundidad/pumuki-actions-healthcheck-temp \
+  8 \
+  .audit-reports/phase5/mock-consumer-ab-report.md
+```
+
+Optional diagnostics helper (signals + next command in one output):
+
+```bash
+npm run validation:phase8:doctor -- \
+  .audit-reports/phase5-latest \
+  SwiftEnProfundidad/pumuki-actions-healthcheck-temp \
+  8 \
+  .audit-reports/phase5/mock-consumer-ab-report.md
+```
+
+Optional autopilot helper (doctor + conditional close-ready):
+
+```bash
+npm run validation:phase8:autopilot -- \
+  .audit-reports/phase5-latest \
+  SwiftEnProfundidad/pumuki-actions-healthcheck-temp \
+  8 \
+  .audit-reports/phase5/mock-consumer-ab-report.md
+```
+
+Optional status pack helper (progress guardrail + doctor):
+
+```bash
+npm run validation:phase8:status-pack -- \
+  .audit-reports/phase5-latest \
+  SwiftEnProfundidad/pumuki-actions-healthcheck-temp \
+  8 \
+  .audit-reports/phase5/mock-consumer-ab-report.md
+```
+
+Optional tick helper (refresh + status-pack in one command):
+
+```bash
+npm run validation:phase8:tick -- \
+  SwiftEnProfundidad/pumuki-actions-healthcheck-temp \
+  8 \
+  .audit-reports/phase5-latest \
+  .audit-reports/phase5/mock-consumer-ab-report.md
+```
+
+## If Still Blocked
+
+1. Refresh latest evidence:
+   - `npm run validation:phase5-latest:refresh -- SwiftEnProfundidad/pumuki-actions-healthcheck-temp 8 .audit-reports/phase5-latest .audit-reports/phase5/mock-consumer-ab-report.md`
+2. Confirm queued runs still show stalled signal (`jobs=0`, `artifacts=0`) or any new failure mode.
+3. Append latest run URLs and new counters in:
+   - `docs/validation/consumer-startup-escalation-handoff-latest.md`
+4. Re-open escalation cycle only if needed.
+
+## Phase 8 Closure
+
+When all required reports are `READY`:
+
+1. Mark `P8-3` as done in `docs/REFRACTOR_PROGRESS.md`.
+2. Mark `P8-4` as in progress.
+3. Generate final ready-handoff summary/checklist:
+   - `npm run validation:phase8:ready-handoff -- .audit-reports/phase5-latest`
+4. Generate close-ready package (summary + READY reports):
+   - `npm run validation:phase8:close-ready -- .audit-reports/phase5-latest`
+5. Regenerate final handoff package and publish URLs.

package/docs/validation/skills-rollout-consumer-repositories.md

@@ -0,0 +1,124 @@
+# Skills Phase 5 Rollout Validation (Consumer Repositories)
+
+## Objective
+
+Validate that repository-enforced skills (`skills.lock.json` + `skills.policy.json`) behave deterministically across `PRE_COMMIT`, `PRE_PUSH`, and `CI` in real consumer repositories.
+
+## Scope
+
+- Framework line: `enterprise-refactor`
+- Evidence contract: `.ai_evidence.json` with `version: "2.1"`
+- Target platforms in consumer repos:
+  - iOS (`.swift`)
+  - Backend (`apps/backend/**/*.ts`)
+  - Frontend (`apps/frontend/**/*.{ts,tsx,js,jsx}`)
+  - Android (`.kt`, `.kts`)
+
+## Preconditions
+
+1. Consumer repository is pinned to a framework revision that includes:
+   - stage runners (`PRE_COMMIT`, `PRE_PUSH`, `CI`)
+   - deterministic evidence v2.1
+   - skills lock/policy integration
+2. `skills.lock.json`, `skills.policy.json`, and `skills.sources.json` are committed.
+3. Local runtime and CI use the same Node major version.
+4. Baseline checks are green:
+   - `npm ci`
+   - `npm run skills:lock:check`
+   - `npm run test:deterministic`
+
+## Validation Matrix
+
+Use this table per consumer repository and append execution links/artifacts.
+
+| Consumer Repo | Stage | Command | Expected Gate Behavior | Evidence Checks |
+| --- | --- | --- | --- | --- |
+| iOS consumer | PRE_COMMIT | `npx tsx integrations/git/preCommitIOS.cli.ts` | Blocks on `CRITICAL`, warns on `ERROR` | `snapshot.stage=PRE_COMMIT`, `version=2.1`, skills ruleset trace present |
+| iOS consumer | PRE_PUSH | `npx tsx integrations/git/prePushIOS.cli.ts` | Blocks on `ERROR`, warns on `WARN` | `snapshot.stage=PRE_PUSH`, range scope reflected by findings |
+| iOS consumer | CI | `npx tsx integrations/git/ciIOS.cli.ts` | Blocks on `ERROR`, warns on `WARN` | `snapshot.stage=CI`, deterministic rerun unchanged |
+| Backend consumer | PRE_COMMIT | `npx tsx integrations/git/preCommitBackend.cli.ts` | Blocks on `CRITICAL`, warns on `ERROR` | `platforms.backend.detected=true` |
+| Backend consumer | PRE_PUSH | `npx tsx integrations/git/prePushBackend.cli.ts` | Blocks on `ERROR`, warns on `WARN` | `snapshot.stage=PRE_PUSH` |
+| Backend consumer | CI | `npx tsx integrations/git/ciBackend.cli.ts` | Blocks on `ERROR`, warns on `WARN` | CI artifact contains `.ai_evidence.json` |
+| Frontend consumer | PRE_COMMIT | `npx tsx integrations/git/preCommitFrontend.cli.ts` | Blocks on `CRITICAL`, warns on `ERROR` | `platforms.frontend.detected=true` |
+| Frontend consumer | PRE_PUSH | `npx tsx integrations/git/prePushFrontend.cli.ts` | Blocks on `ERROR`, warns on `WARN` | `snapshot.stage=PRE_PUSH` |
+| Frontend consumer | CI | `npx tsx integrations/git/ciFrontend.cli.ts` | Blocks on `ERROR`, warns on `WARN` | CI artifact contains `.ai_evidence.json` |
+| Android consumer | PRE_COMMIT | `npx tsx integrations/git/preCommitAndroid.cli.ts` | Blocks on `CRITICAL`, warns on `ERROR` | `platforms.android.detected=true` |
+| Android consumer | PRE_PUSH | `npx tsx integrations/git/prePushAndroid.cli.ts` | Blocks on `ERROR`, warns on `WARN` | `snapshot.stage=PRE_PUSH` |
+| Android consumer | CI | `npx tsx integrations/git/ciAndroid.cli.ts` | Blocks on `ERROR`, warns on `WARN` | CI artifact contains `.ai_evidence.json` |
+
+## Evidence Assertions
+
+Validate each run with deterministic checks:
+
+```bash
+jq -r '.version' .ai_evidence.json
+jq -r '.snapshot.stage' .ai_evidence.json
+jq -r '.snapshot.outcome' .ai_evidence.json
+jq -r '.rulesets[]?.bundle' .ai_evidence.json
+jq -r '.platforms | keys[]' .ai_evidence.json
+```
+
+Expected:
+
+- version equals `2.1`
+- stage equals executed stage
+- `rulesets[]` includes active baseline/project/skills bundles
+- platform keys match detected facts
+
+## Determinism Check
+
+Run the same stage twice without code changes:
+
+1. Execute stage command.
+2. Save `sha256` of `.ai_evidence.json` (raw).
+3. Execute stage command again.
+4. Compare normalized payloads with `timestamp` removed.
+
+Why normalized compare:
+
+- `timestamp` is expected to change between executions.
+- Determinism target is stable semantic content (snapshot/findings/platforms/rulesets), not byte-identical wall-clock metadata.
+
+Example:
+
+```bash
+cp .ai_evidence.json /tmp/evidence-1.json
+# re-run the same stage command
+cp .ai_evidence.json /tmp/evidence-2.json
+
+jq -S 'del(.timestamp)' /tmp/evidence-1.json > /tmp/evidence-1.normalized.json
+jq -S 'del(.timestamp)' /tmp/evidence-2.json > /tmp/evidence-2.normalized.json
+cmp -s /tmp/evidence-1.normalized.json /tmp/evidence-2.normalized.json
+```
+
+## Artifact Checklist (Per Consumer Repo)
+
+- Command logs (`PRE_COMMIT`, `PRE_PUSH`, `CI`)
+- `.ai_evidence.json` per stage
+- Determinism hash comparison output
+- CI artifact URL
+- Commit SHA and branch evaluated
+
+## Current Execution Status
+
+This runbook is prepared and versioned. Execution in external consumer repositories must be attached to this file (or sibling reports under `docs/validation/`) before marking Phase 5 rollout validation as complete.
+
+## Execution Reports
+
+- `docs/validation/archive/skills-rollout-consumer-ci-artifacts.md` (consumer GitHub Actions artifact availability status)
+
+Archived historical reports:
+
+- `docs/validation/archive/skills-rollout-mock_consumer-report.md` (initial real-consumer checkpoint)
+- `docs/validation/archive/skills-rollout-mock_consumer-multi-platform-report.md` (positive multi-platform detection across `PRE_COMMIT`, `PRE_PUSH`, and `CI`)
+- `docs/validation/archive/skills-rollout-mock_consumer-workflow-lint.md` (semantic workflow lint findings linked to startup-failure triage)
+- `docs/validation/archive/skills-rollout-mock_consumer-startup-fix-experiment.md` (branch-only remediation test outcome)
+- `docs/validation/archive/private-actions-healthcheck.md` (account-level private Actions reproduction evidence)
+
+Generated diagnostic outputs (not versioned by default):
+
+- `.audit-reports/consumer-triage/consumer-ci-artifacts-report.md`
+- `.audit-reports/consumer-triage/consumer-workflow-lint-report.md`
+- `.audit-reports/consumer-triage/consumer-startup-failure-support-bundle.md`
+- `.audit-reports/consumer-triage/consumer-ci-auth-check.md`
+- `.audit-reports/consumer-triage/consumer-support-ticket-draft.md`

package/index.js

@@ -0,0 +1,15 @@
+const pkg = require('./package.json');
+
+module.exports = Object.freeze({
+  name: pkg.name,
+  version: pkg.version,
+  description: pkg.description,
+  cli: Object.freeze({
+    lifecycle: 'pumuki',
+    framework: 'pumuki-framework',
+    preCommit: 'pumuki-pre-commit',
+    prePush: 'pumuki-pre-push',
+    ci: 'pumuki-ci',
+    mcpEvidence: 'pumuki-mcp-evidence',
+  }),
+});

package/integrations/config/compileSkillsLock.ts

@@ -0,0 +1,231 @@
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import {
+  createSkillsLockDeterministicHash,
+  loadSkillsLock,
+  parseSkillsLock,
+  type SkillsCompiledRule,
+  type SkillsLockBundle,
+  type SkillsLockV1,
+} from './skillsLock';
+import {
+  SKILLS_LOCK_COMPILER_VERSION,
+  skillsCompilerTemplates,
+  type SkillsRuleTemplate,
+} from './skillsCompilerTemplates';
+import { loadSkillsSources, type SkillsSourceBundleV1 } from './skillsSources';
+
+const DEFAULT_MANIFEST_FILE = 'skills.sources.json';
+const DEFAULT_OUTPUT_FILE = 'skills.lock.json';
+
+export type CompileSkillsLockParams = {
+  repoRoot?: string;
+  manifestFile?: string;
+  generatedAt?: string;
+};
+
+export type WriteSkillsLockParams = {
+  repoRoot?: string;
+  outputFile?: string;
+};
+
+export type SkillsLockCheckResult = {
+  status: 'fresh' | 'stale' | 'missing' | 'invalid';
+  details: string;
+};
+
+const isObject = (value: unknown): value is Record<string, unknown> => {
+  return typeof value === 'object' && value !== null;
+};
+
+const stableStringify = (value: unknown): string => {
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item)).join(',')}]`;
+  }
+
+  if (isObject(value)) {
+    const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+    return `{${entries
+      .map(([key, item]) => `${JSON.stringify(key)}:${stableStringify(item)}`)
+      .join(',')}}`;
+  }
+
+  return JSON.stringify(value) ?? 'null';
+};
+
+const toCompiledRule = (
+  rule: SkillsRuleTemplate,
+  sourceBundle: SkillsSourceBundleV1
+): SkillsCompiledRule => {
+  return {
+    ...rule,
+    sourceSkill: sourceBundle.name,
+    sourcePath: sourceBundle.sourcePath,
+  };
+};
+
+const buildBundleHash = (params: {
+  sourceBundle: SkillsSourceBundleV1;
+  sourceContent: string;
+  compiledRules: ReadonlyArray<SkillsCompiledRule>;
+}): string => {
+  const normalized = {
+    name: params.sourceBundle.name,
+    version: params.sourceBundle.version,
+    template: params.sourceBundle.template,
+    sourcePath: params.sourceBundle.sourcePath,
+    sourceContentSha256: createHash('sha256').update(params.sourceContent).digest('hex'),
+    rules: [...params.compiledRules].sort((left, right) => left.id.localeCompare(right.id)),
+  };
+
+  return createHash('sha256').update(stableStringify(normalized)).digest('hex');
+};
+
+const compileBundle = (
+  sourceBundle: SkillsSourceBundleV1,
+  repoRoot: string
+): SkillsLockBundle => {
+  const template = skillsCompilerTemplates[sourceBundle.template];
+  if (!template) {
+    throw new Error(
+      `Unknown skills template \"${sourceBundle.template}\" for bundle \"${sourceBundle.name}\".`
+    );
+  }
+
+  const sourceFilePath = resolve(repoRoot, sourceBundle.sourcePath);
+  if (!existsSync(sourceFilePath)) {
+    throw new Error(
+      `Skills source file not found for bundle \"${sourceBundle.name}\": ${sourceBundle.sourcePath}`
+    );
+  }
+
+  const sourceContent = readFileSync(sourceFilePath, 'utf8');
+  const compiledRules = template.rules
+    .map((rule) => toCompiledRule(rule, sourceBundle))
+    .sort((left, right) => left.id.localeCompare(right.id));
+
+  const hash = buildBundleHash({
+    sourceBundle,
+    sourceContent,
+    compiledRules,
+  });
+
+  return {
+    name: sourceBundle.name,
+    version: sourceBundle.version,
+    source: sourceBundle.source ?? `file:${sourceBundle.sourcePath}`,
+    hash,
+    rules: compiledRules,
+  };
+};
+
+export const compileSkillsLock = (params: CompileSkillsLockParams = {}): SkillsLockV1 => {
+  const repoRoot = params.repoRoot ?? process.cwd();
+  const manifestFile = params.manifestFile ?? DEFAULT_MANIFEST_FILE;
+  const sources = loadSkillsSources(repoRoot, manifestFile);
+
+  if (!sources) {
+    throw new Error(
+      `Skills sources manifest not found or invalid: ${resolve(repoRoot, manifestFile)}`
+    );
+  }
+
+  const activeBundles = sources.bundles
+    .filter((bundle) => bundle.enabled !== false)
+    .map((bundle) => compileBundle(bundle, repoRoot))
+    .sort((left, right) => {
+      const byName = left.name.localeCompare(right.name);
+      if (byName !== 0) {
+        return byName;
+      }
+      return left.version.localeCompare(right.version);
+    });
+
+  return {
+    version: '1.0',
+    compilerVersion: SKILLS_LOCK_COMPILER_VERSION,
+    generatedAt: params.generatedAt ?? new Date().toISOString(),
+    bundles: activeBundles,
+  };
+};
+
+export const writeSkillsLock = (
+  lock: SkillsLockV1,
+  params: WriteSkillsLockParams = {}
+): string => {
+  const repoRoot = params.repoRoot ?? process.cwd();
+  const outputFile = params.outputFile ?? DEFAULT_OUTPUT_FILE;
+  const outputPath = resolve(repoRoot, outputFile);
+  writeFileSync(outputPath, `${JSON.stringify(lock, null, 2)}\n`, 'utf8');
+  return outputPath;
+};
+
+export const checkSkillsLockStatus = (
+  params: {
+    repoRoot?: string;
+    manifestFile?: string;
+    lockFile?: string;
+  } = {}
+): SkillsLockCheckResult => {
+  const repoRoot = params.repoRoot ?? process.cwd();
+  const lockFile = params.lockFile ?? DEFAULT_OUTPUT_FILE;
+  const lockPath = resolve(repoRoot, lockFile);
+
+  const existingLock =
+    lockFile === DEFAULT_OUTPUT_FILE
+      ? loadSkillsLock(repoRoot)
+      : (() => {
+          if (!existsSync(lockPath)) {
+            return undefined;
+          }
+          try {
+            const parsed: unknown = JSON.parse(readFileSync(lockPath, 'utf8'));
+            return parseSkillsLock(parsed);
+          } catch {
+            return undefined;
+          }
+        })();
+
+  if (!existsSync(lockPath)) {
+    return {
+      status: 'missing',
+      details: `${lockFile} is missing. Run skills lock compilation.`,
+    };
+  }
+
+  if (!existingLock || existingLock.version !== '1.0') {
+    return {
+      status: 'invalid',
+      details: `${lockFile} is invalid for SkillsLockV1.`,
+    };
+  }
+
+  try {
+    const compiled = compileSkillsLock({
+      repoRoot,
+      manifestFile: params.manifestFile,
+      generatedAt: existingLock.generatedAt,
+    });
+    const existingHash = createSkillsLockDeterministicHash(existingLock);
+    const compiledHash = createSkillsLockDeterministicHash(compiled);
+
+    if (existingHash === compiledHash) {
+      return {
+        status: 'fresh',
+        details: `${lockFile} is fresh.`,
+      };
+    }
+
+    return {
+      status: 'stale',
+      details: `${lockFile} is stale. Re-run skills lock compilation.`,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : 'Unknown compilation error.';
+    return {
+      status: 'invalid',
+      details: message,
+    };
+  }
+};

package/integrations/config/heuristics.ts

@@ -0,0 +1,18 @@
+export type HeuristicsConfig = {
+  astSemanticEnabled: boolean;
+};
+
+const TRUE_VALUES = new Set(['1', 'true', 'yes', 'on']);
+
+const parseBooleanFlag = (value: string | undefined): boolean => {
+  if (!value) {
+    return false;
+  }
+  return TRUE_VALUES.has(value.trim().toLowerCase());
+};
+
+export const loadHeuristicsConfig = (): HeuristicsConfig => {
+  return {
+    astSemanticEnabled: parseBooleanFlag(process.env.PUMUKI_ENABLE_AST_HEURISTICS),
+  };
+};