pumuki 6.3.44 → 6.3.46

package/integrations/sdd/syncDocs.ts

@@ -11,6 +11,18 @@ const SDD_STATUS_SECTION = {
   end: '<!-- PUMUKI:END SDD_STATUS -->',
 } as const;
 
+const TRACKING_HUB_SECTION = {
+  id: 'pumuki-sdd-sync',
+  begin: '<!-- PUMUKI:BEGIN SDD_SYNC_STATUS -->',
+  end: '<!-- PUMUKI:END SDD_SYNC_STATUS -->',
+} as const;
+
+const OPERATIONAL_SUMMARY_SECTION = {
+  id: 'pumuki-sdd-sync',
+  begin: '<!-- PUMUKI:BEGIN SDD_SYNC_STATUS -->',
+  end: '<!-- PUMUKI:END SDD_SYNC_STATUS -->',
+} as const;
+
 type ManagedSectionSyncResult = {
   sectionId: string;
   updated: boolean;
@@ -24,11 +36,15 @@ export type SddSyncDocsManagedSection = {
   beginMarker: string;
   endMarker: string;
   renderBody: (repoRoot: string) => string;
+  createIfMissing?: boolean;
 };
 
 export type SddSyncDocsTarget = {
   path: string;
-  sections: ReadonlyArray<SddSyncDocsManagedSection>;
+  sections?: ReadonlyArray<SddSyncDocsManagedSection>;
+  renderWholeFile?: (repoRoot: string, currentSource: string) => string;
+  optional?: boolean;
+  bootstrapIfMissing?: string | ((repoRoot: string) => string);
 };
 
 export type SddSyncDocsFileResult = {
@@ -182,7 +198,51 @@ const formatSddStatusManagedBody = (repoRoot: string): string => {
   ].join('\n');
 };
 
-const DEFAULT_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
+const formatTrackingManagedBody = (repoRoot: string): string => {
+  const status = readSddStatus(repoRoot);
+  return [
+    `- source: pumuki sdd sync-docs`,
+    `- repo_root: ${status.repoRoot}`,
+    `- openspec_installed: ${status.openspec.installed ? 'yes' : 'no'}`,
+    `- openspec_version: ${status.openspec.version ?? 'unknown'}`,
+    `- sdd_session_active: ${status.session.active ? 'yes' : 'no'}`,
+    `- sdd_session_valid: ${status.session.valid ? 'yes' : 'no'}`,
+    `- sdd_session_change: ${status.session.changeId ?? 'none'}`,
+  ].join('\n');
+};
+
+const renderLastRunJson = (repoRoot: string, currentSource: string): string => {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(currentSource);
+  } catch {
+    throw new Error('[pumuki][sdd] sync-docs invalid JSON in docs/validation/refactor/last-run.json');
+  }
+  if (parsed === null || Array.isArray(parsed) || typeof parsed !== 'object') {
+    throw new Error('[pumuki][sdd] sync-docs expected object JSON in docs/validation/refactor/last-run.json');
+  }
+
+  const status = readSddStatus(repoRoot);
+  const payload = parsed as Record<string, unknown>;
+  const next = {
+    ...payload,
+    pumuki_sdd_status: {
+      source: 'pumuki sdd sync-docs',
+      repo_root: status.repoRoot,
+      openspec_installed: status.openspec.installed,
+      openspec_version: status.openspec.version ?? null,
+      openspec_project_initialized: status.openspec.projectInitialized,
+      openspec_compatible: status.openspec.compatible,
+      session_active: status.session.active,
+      session_valid: status.session.valid,
+      session_change: status.session.changeId ?? null,
+    },
+  };
+
+  return `${JSON.stringify(next, null, 2)}\n`;
+};
+
+const PRIMARY_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
   {
     path: 'docs/technical/08-validation/refactor/pumuki-integration-feedback.md',
     sections: [
@@ -196,10 +256,151 @@ const DEFAULT_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
   },
 ];
 
+const OPTIONAL_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
+  {
+    path: 'docs/strategy/ruralgo-tracking-hub.md',
+    optional: true,
+    sections: [
+      {
+        id: TRACKING_HUB_SECTION.id,
+        beginMarker: TRACKING_HUB_SECTION.begin,
+        endMarker: TRACKING_HUB_SECTION.end,
+        renderBody: formatTrackingManagedBody,
+        createIfMissing: true,
+      },
+    ],
+  },
+  {
+    path: 'docs/technical/08-validation/refactor/operational-summary.md',
+    optional: true,
+    sections: [
+      {
+        id: OPERATIONAL_SUMMARY_SECTION.id,
+        beginMarker: OPERATIONAL_SUMMARY_SECTION.begin,
+        endMarker: OPERATIONAL_SUMMARY_SECTION.end,
+        renderBody: formatTrackingManagedBody,
+        createIfMissing: true,
+      },
+    ],
+  },
+  {
+    path: 'docs/validation/refactor/last-run.json',
+    optional: true,
+    renderWholeFile: renderLastRunJson,
+  },
+];
+
+const DEFAULT_SYNC_DOCS_TARGETS: ReadonlyArray<SddSyncDocsTarget> = [
+  ...PRIMARY_SYNC_DOCS_TARGETS,
+  ...OPTIONAL_SYNC_DOCS_TARGETS,
+];
+
 export const SDD_SYNC_DOCS_CANONICAL_FILES = DEFAULT_SYNC_DOCS_TARGETS.map(
   (target) => target.path
 );
 
+const resolveSyncDocsTargets = (
+  repoRoot: string,
+  targets?: ReadonlyArray<SddSyncDocsTarget>
+): ReadonlyArray<SddSyncDocsTarget> => {
+  if (targets) {
+    return targets;
+  }
+  return DEFAULT_SYNC_DOCS_TARGETS.filter((target) => {
+    if (!target.optional) {
+      return true;
+    }
+    return existsSync(resolve(repoRoot, target.path));
+  });
+};
+
+const OPENSPEC_AUTO_SYNC_SECTION = {
+  id: 'pumuki-auto-sync',
+  begin: '<!-- PUMUKI:BEGIN AUTO_SYNC_STATUS -->',
+  end: '<!-- PUMUKI:END AUTO_SYNC_STATUS -->',
+} as const;
+
+const formatOpenSpecAutoSyncBody = (params: {
+  change: string;
+  stage: SddStage | null;
+  task: string | null;
+  now: () => Date;
+}): string =>
+  [
+    `- source: pumuki sdd auto-sync`,
+    `- change: ${params.change}`,
+    `- stage: ${params.stage ?? 'none'}`,
+    `- task: ${params.task ?? 'none'}`,
+    `- updated_at: ${params.now().toISOString()}`,
+  ].join('\n');
+
+const buildOpenSpecAutoSyncTargets = (params: {
+  change: string;
+  stage: SddStage | null;
+  task: string | null;
+  now: () => Date;
+}): ReadonlyArray<SddSyncDocsTarget> => {
+  const buildDoc = (title: string): string =>
+    [
+      `# ${title}`,
+      '',
+      OPENSPEC_AUTO_SYNC_SECTION.begin,
+      '- source: bootstrap',
+      OPENSPEC_AUTO_SYNC_SECTION.end,
+      '',
+    ].join('\n');
+
+  const renderBody = () =>
+    formatOpenSpecAutoSyncBody({
+      change: params.change,
+      stage: params.stage,
+      task: params.task,
+      now: params.now,
+    });
+
+  return [
+    {
+      path: `openspec/changes/${params.change}/tasks.md`,
+      sections: [
+        {
+          id: OPENSPEC_AUTO_SYNC_SECTION.id,
+          beginMarker: OPENSPEC_AUTO_SYNC_SECTION.begin,
+          endMarker: OPENSPEC_AUTO_SYNC_SECTION.end,
+          renderBody,
+          createIfMissing: true,
+        },
+      ],
+      bootstrapIfMissing: buildDoc('Tasks'),
+    },
+    {
+      path: `openspec/changes/${params.change}/design.md`,
+      sections: [
+        {
+          id: OPENSPEC_AUTO_SYNC_SECTION.id,
+          beginMarker: OPENSPEC_AUTO_SYNC_SECTION.begin,
+          endMarker: OPENSPEC_AUTO_SYNC_SECTION.end,
+          renderBody,
+          createIfMissing: true,
+        },
+      ],
+      bootstrapIfMissing: buildDoc('Design'),
+    },
+    {
+      path: `openspec/changes/${params.change}/retrospective.md`,
+      sections: [
+        {
+          id: OPENSPEC_AUTO_SYNC_SECTION.id,
+          beginMarker: OPENSPEC_AUTO_SYNC_SECTION.begin,
+          endMarker: OPENSPEC_AUTO_SYNC_SECTION.end,
+          renderBody,
+          createIfMissing: true,
+        },
+      ],
+      bootstrapIfMissing: buildDoc('Retrospective'),
+    },
+  ];
+};
+
 const applyManagedSection = (params: {
   filePath: string;
   source: string;
@@ -207,14 +408,46 @@ const applyManagedSection = (params: {
   endMarker: string;
   renderedBody: string;
   sectionId: string;
+  createIfMissing?: boolean;
 }): {
   nextSource: string;
   result: ManagedSectionSyncResult;
 } => {
   const beginIndex = params.source.indexOf(params.beginMarker);
   const endIndex = params.source.indexOf(params.endMarker);
-
-  if (beginIndex === -1 || endIndex === -1 || endIndex < beginIndex) {
+  const missingBegin = beginIndex === -1;
+  const missingEnd = endIndex === -1;
+
+  if (missingBegin || missingEnd) {
+    if (params.createIfMissing === true && missingBegin && missingEnd) {
+      const beforeBody = '';
+      const afterBody = normalizeSectionBody(params.renderedBody);
+      const block = `${params.beginMarker}\n${params.renderedBody}\n${params.endMarker}`;
+      const sourceTrimmedEnd = params.source.replace(/\s*$/, '');
+      const nextSource =
+        sourceTrimmedEnd.length === 0
+          ? `${block}\n`
+          : `${sourceTrimmedEnd}\n\n${block}\n`;
+      return {
+        nextSource,
+        result: {
+          sectionId: params.sectionId,
+          updated: true,
+          before: beforeBody,
+          after: afterBody,
+          diffMarkdown: buildSectionDiffMarkdown({
+            sectionId: params.sectionId,
+            before: beforeBody,
+            after: afterBody,
+          }),
+        },
+      };
+    }
+    throw new Error(
+      `[pumuki][sdd] sync-docs conflict in ${params.filePath}: expected managed markers ${params.beginMarker} ... ${params.endMarker}`
+    );
+  }
+  if (endIndex < beginIndex) {
     throw new Error(
       `[pumuki][sdd] sync-docs conflict in ${params.filePath}: expected managed markers ${params.beginMarker} ... ${params.endMarker}`
     );
@@ -369,7 +602,7 @@ export const runSddSyncDocs = (params?: {
       flagName: '--from-evidence',
     })
     : null;
-  const targets = params?.targets ?? DEFAULT_SYNC_DOCS_TARGETS;
+  const targets = resolveSyncDocsTargets(repoRoot, params?.targets);
   const now = params?.now ?? (() => new Date());
   const evidenceReader =
     params?.evidenceReader ??
@@ -381,45 +614,88 @@ export const runSddSyncDocs = (params?: {
           : undefined
       ));
 
-  const updates = targets.map((target) => {
+  const updates: Array<{
+    relativePath: string;
+    absolutePath: string;
+    currentSource: string;
+    nextSource: string;
+    sections: ManagedSectionSyncResult[];
+  }> = [];
+
+  for (const target of targets) {
     const absolutePath = resolve(repoRoot, target.path);
-    if (!existsSync(absolutePath)) {
-      throw new Error(
-        `[pumuki][sdd] sync-docs missing canonical file: ${target.path}`
-      );
+    const exists = existsSync(absolutePath);
+    let currentSource = '';
+
+    if (!exists) {
+      if (target.bootstrapIfMissing !== undefined) {
+        currentSource =
+          typeof target.bootstrapIfMissing === 'function'
+            ? target.bootstrapIfMissing(repoRoot)
+            : target.bootstrapIfMissing;
+      } else if (target.optional) {
+        continue;
+      } else {
+        throw new Error(
+          `[pumuki][sdd] sync-docs missing canonical file: ${target.path}`
+        );
+      }
+    } else {
+      currentSource = readFileSync(absolutePath, 'utf8');
     }
 
-    const currentSource = readFileSync(absolutePath, 'utf8');
     let nextSource = currentSource;
     const sectionUpdates: ManagedSectionSyncResult[] = [];
 
-    for (const section of target.sections) {
-      const update = applyManagedSection({
-        filePath: target.path,
-        source: nextSource,
-        beginMarker: section.beginMarker,
-        endMarker: section.endMarker,
-        renderedBody: section.renderBody(repoRoot),
-        sectionId: section.id,
+    if (target.renderWholeFile) {
+      nextSource = target.renderWholeFile(repoRoot, nextSource);
+      sectionUpdates.push({
+        sectionId: 'file-content',
+        updated: normalizeSectionBody(currentSource) !== normalizeSectionBody(nextSource),
+        before: normalizeSectionBody(currentSource),
+        after: normalizeSectionBody(nextSource),
+        diffMarkdown: buildSectionDiffMarkdown({
+          sectionId: 'file-content',
+          before: normalizeSectionBody(currentSource),
+          after: normalizeSectionBody(nextSource),
+        }),
       });
-      nextSource = update.nextSource;
-      sectionUpdates.push(update.result);
+    } else {
+      if (!target.sections || target.sections.length === 0) {
+        throw new Error(
+          `[pumuki][sdd] sync-docs invalid target configuration for ${target.path}: expected sections or renderWholeFile`
+        );
+      }
+      for (const section of target.sections) {
+        const update = applyManagedSection({
+          filePath: target.path,
+          source: nextSource,
+          beginMarker: section.beginMarker,
+          endMarker: section.endMarker,
+          renderedBody: section.renderBody(repoRoot),
+          sectionId: section.id,
+          createIfMissing: section.createIfMissing,
+        });
+        nextSource = update.nextSource;
+        sectionUpdates.push(update.result);
+      }
     }
 
-    return {
+    updates.push({
       relativePath: target.path,
       absolutePath,
       currentSource,
       nextSource,
       sections: sectionUpdates,
-    };
-  });
+    });
+  }
 
   if (!dryRun) {
     for (const update of updates) {
-      if (update.currentSource === update.nextSource) {
+      if (update.currentSource === update.nextSource && existsSync(update.absolutePath)) {
         continue;
       }
+      mkdirSync(dirname(update.absolutePath), { recursive: true });
       writeFileSync(update.absolutePath, update.nextSource, 'utf8');
     }
   }
@@ -557,17 +833,30 @@ export const runSddAutoSync = (params?: {
   if (!change) {
     throw new Error('[pumuki][sdd] auto-sync requires --change=<change-id>.');
   }
+  const repoRoot = resolve(params?.repoRoot ?? process.cwd());
+  const now = params?.now ?? (() => new Date());
+  const targets =
+    params?.targets ??
+    [
+      ...resolveSyncDocsTargets(repoRoot),
+      ...buildOpenSpecAutoSyncTargets({
+        change,
+        stage: params?.stage ?? null,
+        task: params?.task?.trim() ? params.task.trim() : null,
+        now,
+      }),
+    ];
 
   const syncResult = runSddSyncDocs({
-    repoRoot: params?.repoRoot,
+    repoRoot,
     dryRun: params?.dryRun,
     change,
     stage: params?.stage,
     task: params?.task,
     fromEvidencePath: params?.fromEvidencePath,
-    now: params?.now,
+    now,
     evidenceReader: params?.evidenceReader,
-    targets: params?.targets,
+    targets,
   });
 
   if (!syncResult.learning) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pumuki",
-  "version": "6.3.44",
+  "version": "6.3.46",
   "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": {
@@ -49,7 +49,7 @@
     "test:heuristics": "npx --yes tsx@4.21.0 --test core/facts/__tests__/extractHeuristicFacts.test.ts",
     "test:evidence": "npx --yes tsx@4.21.0 --test integrations/evidence/__tests__/buildEvidence.test.ts integrations/evidence/__tests__/humanIntent.test.ts",
     "test:mcp": "npx --yes tsx@4.21.0 --test integrations/mcp/__tests__/*.test.ts",
-    "test:backlog-tooling": "npx --yes tsx@4.21.0 --test scripts/__tests__/backlog-action-reasons-lib.test.ts scripts/__tests__/backlog-json-contract-lib.test.ts scripts/__tests__/backlog-cli-help-exit-code.test.ts scripts/__tests__/backlog-id-issue-map-lib.test.ts scripts/__tests__/reconcile-consumer-backlog-issues.test.ts scripts/__tests__/watch-consumer-backlog.test.ts",
+    "test:backlog-tooling": "npx --yes tsx@4.21.0 --test scripts/__tests__/backlog-action-reasons-lib.test.ts scripts/__tests__/backlog-json-contract-lib.test.ts scripts/__tests__/backlog-cli-help-exit-code.test.ts scripts/__tests__/backlog-id-issue-map-lib.test.ts scripts/__tests__/reconcile-consumer-backlog-issues.test.ts scripts/__tests__/watch-consumer-backlog.test.ts scripts/__tests__/watch-consumer-backlog-fleet.test.ts scripts/__tests__/watch-consumer-backlog-fleet-tick.test.ts",
     "test:saas-ingestion": "npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/saasIngestionContract.test.ts integrations/lifecycle/__tests__/saasIngestionBuilder.test.ts integrations/lifecycle/__tests__/saasIngestionTransport.test.ts integrations/lifecycle/__tests__/saasIngestionIdempotency.test.ts integrations/lifecycle/__tests__/saasIngestionAuth.test.ts integrations/lifecycle/__tests__/saasIngestionAudit.test.ts integrations/lifecycle/__tests__/saasIngestionMetrics.test.ts integrations/lifecycle/__tests__/saasIngestionGovernance.test.ts integrations/lifecycle/__tests__/saasFederation.test.ts integrations/lifecycle/__tests__/saasEnterpriseAnalytics.test.ts integrations/lifecycle/__tests__/cli.test.ts",
     "test:operational-memory": "npx --yes tsx@4.21.0 --test integrations/lifecycle/__tests__/operationalMemoryContract.test.ts integrations/lifecycle/__tests__/operationalMemorySignals.test.ts integrations/lifecycle/__tests__/operationalMemorySnapshot.test.ts integrations/git/__tests__/runPlatformGate.test.ts integrations/git/__tests__/runPlatformGateEvidence.test.ts integrations/evidence/__tests__/buildEvidence.test.ts integrations/evidence/writeEvidence.test.ts integrations/evidence/generateEvidence.test.ts",
     "test:stage-gates": "npx --yes tsx@4.21.0 --test integrations/config/__tests__/*.test.ts integrations/gate/__tests__/*.test.ts integrations/git/__tests__/*.test.ts integrations/lifecycle/__tests__/*.test.ts integrations/sdd/__tests__/*.test.ts scripts/__tests__/*.test.ts",
@@ -101,6 +101,9 @@
     "validation:tracking-single-active": "bash scripts/check-tracking-single-active.sh",
     "validation:backlog-reconcile": "node --import tsx scripts/reconcile-consumer-backlog-issues.ts",
     "validation:backlog-watch": "node --import tsx scripts/watch-consumer-backlog.ts",
+    "validation:backlog-watch:fleet": "node --import tsx scripts/watch-consumer-backlog-fleet.ts",
+    "validation:backlog-watch:tick": "node --import tsx scripts/watch-consumer-backlog-fleet-tick.ts --json --no-fail",
+    "validation:backlog-watch:gate": "node --import tsx scripts/watch-consumer-backlog-fleet-tick.ts --json",
     "validation:phase5-escalation:ready-to-submit": "bash scripts/check-phase5-escalation-ready-to-submit.sh",
     "validation:phase5-escalation:prepare": "bash scripts/prepare-phase5-escalation-submission.sh",
     "validation:phase5-escalation:close-submission": "bash scripts/close-phase5-escalation-submission.sh",

package/scripts/backlog-id-issue-map-lib.ts

@@ -1,7 +1,7 @@
 import { readFileSync } from 'node:fs';
 import { resolve } from 'node:path';
 
-export const BACKLOG_ID_PATTERN = /^(PUMUKI-(?:M)?\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)$/;
+export const BACKLOG_ID_PATTERN = /^(PUMUKI-(?:M)?\d+|PUM-\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)$/;
 
 export type BacklogIdIssueMapRecord = Readonly<Record<string, number>>;
 

package/scripts/reconcile-consumer-backlog-issues-lib.ts

@@ -75,10 +75,10 @@ export type BacklogReconcileResult = {
 
 const STATUS_EMOJI_PATTERN = /(✅|🚧|⏳|⛔)/;
 const ISSUE_REF_PATTERN = /#(\d+)/;
-const BACKLOG_ID_PATTERN = /^(PUMUKI-(?:M)?\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)$/;
+const BACKLOG_ID_PATTERN = /^(PUMUKI-(?:M)?\d+|PUM-\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)$/;
 const PENDING_REFERENCE_PATTERN = /\|\s*Pendiente(?:\s*\(rel\.\s*#\d+\))?\s*\|/;
 const BACKLOG_SECTION_HEADING_PATTERN =
-  /^(\s*###\s*)(✅|🚧|⏳|⛔)(\s+)(PUMUKI-(?:M)?\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)\b/;
+  /^(\s*###\s*)(✅|🚧|⏳|⛔)(\s+)(PUMUKI-(?:M)?\d+|PUM-\d+|PUMUKI-INC-\d+|FP-\d+|AST-GAP-\d+)\b/;
 
 export type BacklogIssueNumberResolver = (
   backlogId: string,