pumuki 6.3.374 → 6.3.375

package/integrations/lifecycle/cli.ts

@@ -104,6 +104,7 @@ type LifecycleCommand =
 type SddCommand =
   | 'status'
   | 'validate'
+  | 'guard'
   | 'session'
   | 'sync-docs'
   | 'learn'
@@ -219,6 +220,7 @@ Pumuki lifecycle commands:
   pumuki context repair [--json]
   pumuki sdd status [--json]
   pumuki sdd validate [--stage=PRE_WRITE|PRE_COMMIT|PRE_PUSH|CI] [--json]
+  pumuki sdd guard [--stage=PRE_WRITE] [--json]
   pumuki sdd session --open --change=<change-id|auto> [--ttl-minutes=<n>] [--json]
   pumuki sdd session --refresh [--ttl-minutes=<n>] [--json]
   pumuki sdd session --close [--json]
@@ -998,6 +1000,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
     if (
       subcommandRaw !== 'status' &&
       subcommandRaw !== 'validate' &&
+      subcommandRaw !== 'guard' &&
       subcommandRaw !== 'session' &&
       subcommandRaw !== 'sync-docs' &&
       subcommandRaw !== 'sync' &&
@@ -1039,7 +1042,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         throw new Error(`--dry-run is only supported with "pumuki sdd sync-docs", "pumuki sdd learn", "pumuki sdd auto-sync", "pumuki sdd evidence" or "pumuki sdd state-sync".\n\n${HELP_TEXT}`);
       }
       if (arg.startsWith('--stage=')) {
-        if (sddCommand === 'validate') {
+        if (sddCommand === 'validate' || sddCommand === 'guard') {
           sddStage = parseSddStage(arg.slice('--stage='.length));
           continue;
         }
@@ -1055,7 +1058,7 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
           sddAutoSyncStage = parseSddStage(arg.slice('--stage='.length));
           continue;
         }
-        throw new Error(`--stage is only supported with "pumuki sdd validate", "pumuki sdd sync-docs", "pumuki sdd learn" or "pumuki sdd auto-sync".\n\n${HELP_TEXT}`);
+        throw new Error(`--stage is only supported with "pumuki sdd validate", "pumuki sdd guard", "pumuki sdd sync-docs", "pumuki sdd learn" or "pumuki sdd auto-sync".\n\n${HELP_TEXT}`);
       }
       if (arg.startsWith('--status=')) {
         if (sddCommand !== 'state-sync') {
@@ -1272,6 +1275,15 @@ export const parseLifecycleCliArgs = (argv: ReadonlyArray<string>): ParsedArgs =
         sddStage: sddStage ?? 'PRE_COMMIT',
       };
     }
+    if (sddCommand === 'guard') {
+      return {
+        command: commandRaw,
+        purgeArtifacts: false,
+        json,
+        sddCommand,
+        sddStage: sddStage ?? 'PRE_WRITE',
+      };
+    }
     if (sddCommand === 'sync-docs') {
       if (
         sddSessionAction ||

package/integrations/lifecycle/cliSdd.ts

@@ -22,6 +22,7 @@ import {
 } from '../policy/preWriteEnforcement';
 import { readLifecycleExperimentalFeaturesSnapshot } from './experimentalFeaturesSnapshot';
 import { GitService } from '../git/GitService';
+import { evaluatePreWriteAgentGuard } from './preWriteLease';
 
 import {
   type ParsedArgs,
@@ -68,6 +69,39 @@ export const runSddCommand = async (parsed: ParsedArgs, activeDependencies: Life
           }
           return 0;
         }
+        if (parsed.sddCommand === 'guard') {
+          const requestedStage = parsed.sddStage ?? 'PRE_WRITE';
+          if (requestedStage !== 'PRE_WRITE') {
+            if (parsed.json) {
+              writeInfo(JSON.stringify({
+                allowed: false,
+                stage: requestedStage,
+                code: 'PRE_WRITE_AGENT_GUARD_UNSUPPORTED_STAGE',
+                message: 'Agent pre-write guard only supports PRE_WRITE.',
+              }, null, 2));
+            } else {
+              writeInfo('[pumuki][sdd] guard allowed=no code=PRE_WRITE_AGENT_GUARD_UNSUPPORTED_STAGE');
+              writeInfo('[pumuki][sdd] Agent pre-write guard only supports PRE_WRITE.');
+            }
+            return 1;
+          }
+          const guard = evaluatePreWriteAgentGuard({
+            repoRoot: process.cwd(),
+            git: new GitService(),
+          });
+          if (parsed.json) {
+            writeInfo(JSON.stringify(guard, null, 2));
+          } else {
+            writeInfo(
+              `[pumuki][sdd] guard stage=PRE_WRITE allowed=${guard.allowed ? 'yes' : 'no'} code=${guard.code}`
+            );
+            writeInfo(`[pumuki][sdd] ${guard.message}`);
+            if (!guard.allowed) {
+              writeInfo(`[pumuki][sdd] solution: ${guard.expected_fix}`);
+            }
+          }
+          return guard.allowed ? 0 : 1;
+        }
         if (parsed.sddCommand === 'validate') {
           const requestedStage = parsed.sddStage ?? 'PRE_COMMIT';
           const preWriteEnforcement = requestedStage === 'PRE_WRITE'

package/integrations/lifecycle/preWriteLease.ts

@@ -50,6 +50,24 @@ export type PreWriteLeaseWriteResult = {
   changedCodePaths: string[];
 };
 
+export type PreWriteAgentGuardResult = {
+  allowed: boolean;
+  stage: 'PRE_WRITE';
+  code:
+    | 'PRE_WRITE_AGENT_GUARD_ALLOWED'
+    | 'PRE_WRITE_AGENT_GUARD_LEASE_MISSING'
+    | 'PRE_WRITE_AGENT_GUARD_LEASE_INVALID'
+    | 'PRE_WRITE_AGENT_GUARD_LEASE_EXPIRED'
+    | 'PRE_WRITE_AGENT_GUARD_LEASE_HEAD_MISMATCH'
+    | 'PRE_WRITE_AGENT_GUARD_LEASE_DIRTY_AT_ISSUE'
+    | 'PRE_WRITE_AGENT_GUARD_CODE_CHANGED_WITHOUT_LEASE';
+  message: string;
+  expected_fix: string;
+  path: string;
+  changedCodePaths: string[];
+  lease_status: PreWriteLeaseStatus;
+};
+
 const PRE_WRITE_LEASE_TTL_MS = 4 * 60 * 60 * 1000;
 
 export const resolvePreWriteLeasePath = (repoRoot: string): string =>
@@ -287,6 +305,48 @@ export const writePreWriteLease = (params: {
   };
 };
 
+export const evaluatePreWriteAgentGuard = (params: {
+  repoRoot: string;
+  git: Pick<IGitService, 'runGit'>;
+  now?: Date;
+}): PreWriteAgentGuardResult => {
+  const leaseStatus = readPreWriteLeaseStatus(params);
+  if (leaseStatus.valid) {
+    return {
+      allowed: true,
+      stage: 'PRE_WRITE',
+      code: 'PRE_WRITE_AGENT_GUARD_ALLOWED',
+      message: 'PRE_WRITE agent guard passed. A valid PRE_WRITE lease exists for this repo and diff.',
+      expected_fix: 'Continue with the current slice; keep edits inside the validated scope.',
+      path: leaseStatus.path,
+      changedCodePaths: leaseStatus.changedCodePaths,
+      lease_status: leaseStatus,
+    };
+  }
+
+  const hasCodeChanges = leaseStatus.changedCodePaths.length > 0;
+  const code = hasCodeChanges
+    ? 'PRE_WRITE_AGENT_GUARD_CODE_CHANGED_WITHOUT_LEASE'
+    : (`PRE_WRITE_AGENT_GUARD_${leaseStatus.code.replace('PRE_WRITE_', '')}` as PreWriteAgentGuardResult['code']);
+  const changedDetails = hasCodeChanges
+    ? ` Code changes already exist: ${leaseStatus.changedCodePaths.join(', ')}.`
+    : '';
+
+  return {
+    allowed: false,
+    stage: 'PRE_WRITE',
+    code,
+    message:
+      `AI agent instruction: STOP; do not apply patches or write files until PRE_WRITE is valid. ` +
+      `${leaseStatus.message}${changedDetails}`,
+    expected_fix:
+      'run `npx pumuki-pre-write` before editing code. If code changes already exist, stop and ask whether to validate the current diff, stash it, or restart from a clean PRE_WRITE lease.',
+    path: leaseStatus.path,
+    changedCodePaths: leaseStatus.changedCodePaths,
+    lease_status: leaseStatus,
+  };
+};
+
 export const toPreWriteEnforcementGapFinding = (params: {
   stage: 'PRE_COMMIT' | 'PRE_PUSH' | 'CI';
   status: PreWriteLeaseStatus;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.374",
+  "version": "6.3.375",
   "description": "Enterprise-grade AST Intelligence System with multi-platform support (iOS, Android, Backend, Frontend) and Feature-First + DDD + Clean Architecture enforcement. Includes dynamic violations API for intelligent querying.",
   "main": "index.js",
   "bin": {

package/scripts/package-install-smoke-execution-lib.ts

@@ -1,5 +1,8 @@
 import type { SmokeMode } from './package-install-smoke-contract';
-import { runDefaultSmokeGateSteps } from './package-install-smoke-execution-steps-lib';
+import {
+  runDefaultSmokeGateSteps,
+  runSmokeGoldenFlowEvidenceStep,
+} from './package-install-smoke-execution-steps-lib';
 import {
   assertLifecycleStatusMatchesSnapshot,
   captureLifecycleStatusSnapshot,
@@ -41,6 +44,7 @@ export const runPackageInstallSmoke = (mode: SmokeMode): void => {
     runLifecycleInstallStep(workspace);
     runLifecyclePreWriteStep(workspace);
     writeStagedPayload(workspace, mode);
+    runSmokeGoldenFlowEvidenceStep(workspace);
 
     const lifecycleStatusSnapshot = captureLifecycleStatusSnapshot(workspace);
 

package/scripts/package-install-smoke-execution-steps-lib.ts

@@ -1,7 +1,15 @@
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
 import type { SmokeExpectation } from './package-install-smoke-contract';
+import {
+  assertNoFatalOutput,
+  assertSuccess,
+  runCommand,
+} from './package-install-smoke-runner-common';
 import { runGateStep, type SmokeGateStep } from './package-install-smoke-gate-lib';
 import { resolveConsumerPumukiCommand } from './package-install-smoke-command-resolution-lib';
 import type { SmokeWorkspace } from './package-install-smoke-workspace-contract';
+import { pushCommandLog } from './package-install-smoke-workspace-lib';
 
 export type SmokeStepResult = {
   label: SmokeGateStep['label'];
@@ -62,3 +70,54 @@ export const runDefaultSmokeGateSteps = (params: {
       exitCode: result.exitCode,
     };
   });
+
+export const runSmokeGoldenFlowEvidenceStep = (workspace: SmokeWorkspace): void => {
+  writeFileSync(
+    join(workspace.consumerRepo, 'package-smoke-minimal.feature'),
+    [
+      'Feature: Package smoke minimal',
+      '',
+      '  Scenario: package smoke minimal',
+      '    Given a minimal package consumer',
+      '    When Pumuki gates run',
+      '    Then the package smoke passes',
+      '',
+    ].join('\n'),
+    'utf8'
+  );
+  const addFeatureResult = runCommand({
+    cwd: workspace.consumerRepo,
+    executable: 'git',
+    args: ['add', 'package-smoke-minimal.feature'],
+  });
+  pushCommandLog(workspace.commandLog, addFeatureResult);
+  assertSuccess(addFeatureResult, 'git add package smoke feature');
+
+  const resolvedCommand = resolveConsumerPumukiCommand({
+    consumerRepo: workspace.consumerRepo,
+    binary: 'pumuki',
+    args: [
+      'sdd',
+      'evidence',
+      '--scenario-id=package-smoke-minimal',
+      '--test-command=package-smoke-minimal',
+      '--test-status=passed',
+      '--json',
+    ],
+  });
+  const result = runCommand({
+    cwd: workspace.consumerRepo,
+    executable: resolvedCommand.executable,
+    args: resolvedCommand.args,
+    env: {
+      PUMUKI_DISABLE_SYSTEM_NOTIFICATIONS: '1',
+      PUMUKI_SYSTEM_NOTIFICATIONS: '0',
+      PUMUKI_NOTIFICATIONS: '0',
+      PUMUKI_SDD_BYPASS: '1',
+    },
+  });
+
+  pushCommandLog(workspace.commandLog, result);
+  assertNoFatalOutput(result, 'pumuki-sdd-evidence');
+  assertSuccess(result, 'pumuki-sdd-evidence');
+};