pumuki 6.3.55 → 6.3.57

package/README.md

@@ -238,87 +238,18 @@ Legacy parity report (strict comparator):
 node --import tsx scripts/build-legacy-parity-report.ts --legacy=<legacy-evidence-path> --enterprise=<enterprise-evidence-path> --out=<output-path>
 ```
 
-## Command Reference
+## Command Paths
 
-### Lifecycle (Consumer)
+Use these docs instead of treating `README.md` as the full command manual:
 
-```bash
-npx --yes pumuki install
-npx --yes pumuki update --latest
-npx --yes pumuki uninstall --purge-artifacts
-npx --yes pumuki remove
-npx --yes pumuki doctor
-npx --yes pumuki status
-```
-
-### SDD / OpenSpec (Consumer)
-
-```bash
-npx --yes pumuki sdd status
-npx --yes pumuki sdd session --open --change=<change-id>
-npx --yes pumuki sdd session --refresh
-npx --yes pumuki sdd session --close
-npx --yes pumuki sdd validate --stage=PRE_COMMIT
-```
-
-### Loop Runner (Consumer)
-
-```bash
-npx --yes pumuki loop run --objective="stabilize gate before commit" --max-attempts=3 --json
-npx --yes pumuki loop status --session=<session-id> --json
-npx --yes pumuki loop stop --session=<session-id> --json
-npx --yes pumuki loop resume --session=<session-id> --json
-npx --yes pumuki loop list --json
-npx --yes pumuki loop export --session=<session-id> --output-json=.audit-reports/loop-session.json
-```
-
-### Stage Gates (Consumer)
-
-```bash
-npx --yes --package pumuki@latest pumuki-pre-write
-npx --yes --package pumuki@latest pumuki-pre-commit
-npx --yes --package pumuki@latest pumuki-pre-push
-npx --yes --package pumuki@latest pumuki-ci
-```
-
-### MCP Servers (Optional, Long-Running)
-
-```bash
-npx --yes --package pumuki@latest pumuki-mcp-evidence
-npx --yes --package pumuki@latest pumuki-mcp-evidence-stdio
-npx --yes --package pumuki@latest pumuki-mcp-enterprise
-npx --yes --package pumuki@latest pumuki-mcp-enterprise-stdio
-```
-
-## Validation and Diagnostics (Framework-Only)
-
-These commands are for maintainers and may require additional arguments, external repo context, or authenticated GitHub access.
-
-```bash
-npm run validation:consumer-ci-artifacts -- --repo <owner/repo>
-npm run validation:consumer-ci-auth-check -- --repo <owner/repo>
-npm run validation:consumer-workflow-lint -- --repo-path <absolute-path-to-consumer-repo>
-npm run validation:consumer-support-bundle -- --repo <owner/repo>
-npm run validation:consumer-support-ticket-draft
-npm run validation:consumer-startup-unblock-status
-npm run validation:consumer-startup-triage -- --repo <owner/repo> --skip-workflow-lint
-npm run validation:mock-consumer-ab-report
-npm run validation:adapter-readiness
-npm run validation:adapter-session-status
-npm run validation:adapter-real-session-report
-npm run validation:phase5-blockers-readiness
-npm run validation:phase5-execution-closure-status
-npm run validation:phase5-execution-closure -- --repo <owner/repo> --skip-workflow-lint
-npm run validation:phase5-external-handoff
-npm run validation:clean-artifacts
-```
-
-Important:
-
-- Several validation scripts intentionally return non-zero when verdict is `BLOCKED`, `PENDING`, or `MISSING_INPUTS`.
-- Non-zero in these scripts is often diagnostic output, not a runtime crash.
-- `validation:consumer-support-ticket-draft` expects an existing support bundle generated by `validation:consumer-support-bundle`.
-- If workflow lint is required in your flow, provide `--repo-path` and `--actionlint-bin`; otherwise use `--skip-workflow-lint`.
+- Installation and bootstrap:
+  - `docs/product/INSTALLATION.md`
+- Daily usage, gates, menu, lifecycle, SDD and troubleshooting:
+  - `docs/product/USAGE.md`
+- Operator-focused short playbook:
+  - `PUMUKI.md`
+- Validation runbooks and framework-only diagnostics:
+  - `docs/validation/README.md`
 
 ## Menu Walkthrough and Screenshots
 
@@ -348,13 +279,13 @@ Important:
 
 Extended annotated walkthrough:
 
-- `docs/operations/framework-menu-option-1-walkthrough.md`
+- `docs/operations/framework-menu-consumer-walkthrough.md`
 
 ## Enterprise Operations Baseline
 
 Pumuki production SaaS operation baseline is defined in:
 
-- `docs/operations/OPERATIONS.md`
+- `docs/operations/production-operations-policy.md`
 
 Highlights:
 
@@ -384,11 +315,11 @@ Highlights:
 - Configuration: `docs/product/CONFIGURATION.md`
 - Code standards: `docs/governance/CODE_STANDARDS.md`
 - Branch protection: `docs/governance/BRANCH_PROTECTION_GUIDE.md`
-- MCP servers: `docs/mcp/MCP_SERVERS.md`
-- MCP evidence server: `docs/mcp/MCP_EVIDENCE_CONTEXT_SERVER.md`
-- MCP consumption: `docs/mcp/MCP_AGENT_CONTEXT_CONSUMPTION.md`
+- MCP servers: `docs/mcp/mcp-servers-overview.md`
+- MCP evidence server: `docs/mcp/evidence-context-server.md`
+- MCP consumption: `docs/mcp/agent-context-consumption.md`
 - Evidence schema v2.1: `docs/mcp/ai-evidence-v2.1-contract.md`
-- Operations policy (SLA/SLO): `docs/operations/OPERATIONS.md`
+- Operations policy (SLA/SLO): `docs/operations/production-operations-policy.md`
 - Release notes: `docs/operations/RELEASE_NOTES.md`
 - Changelog: `CHANGELOG.md`
 

package/VERSION

@@ -1 +1 @@
-v6.3.41
+v6.3.57

package/core/facts/HeuristicFact.test.ts

@@ -32,3 +32,31 @@ test('HeuristicFact permite omitir filePath', () => {
   assert.equal(factWithoutPath.filePath, undefined);
   assert.equal(factWithoutPath.severity, 'INFO');
 });
+
+test('HeuristicFact conserva metadata semantica opcional del canario iOS', () => {
+  const fact: HeuristicFact = {
+    kind: 'Heuristic',
+    ruleId: 'heuristics.ios.canary-001.presentation-mixed-responsibilities.ast',
+    severity: 'CRITICAL',
+    code: 'HEURISTICS_IOS_CANARY_001_PRESENTATION_MIXED_RESPONSIBILITIES_AST',
+    message: 'Semantic iOS canary triggered.',
+    filePath: 'apps/ios/Sources/AppShell/Application/AppShellViewModel.swift',
+    lines: [1, 2, 3, 4],
+    primary_node: {
+      kind: 'class',
+      name: 'AppShellViewModel',
+      lines: [1],
+    },
+    related_nodes: [
+      { kind: 'property', name: 'shared singleton', lines: [2] },
+      { kind: 'call', name: 'URLSession.shared', lines: [3] },
+    ],
+    why: 'Mezcla responsabilidades incompatibles.',
+    impact: 'Complica tests y cambios.',
+    expected_fix: 'Extraer collaborators.',
+  };
+
+  assert.equal(fact.primary_node?.name, 'AppShellViewModel');
+  assert.equal(fact.related_nodes?.length, 2);
+  assert.equal(fact.expected_fix, 'Extraer collaborators.');
+});

package/core/facts/HeuristicFact.ts

@@ -1,5 +1,11 @@
 import type { Severity } from '../rules/Severity';
 
+export type HeuristicNode = {
+  kind: 'class' | 'property' | 'call' | 'member';
+  name: string;
+  lines?: readonly number[];
+};
+
 export interface HeuristicFact {
   kind: 'Heuristic';
   ruleId: string;
@@ -8,4 +14,9 @@ export interface HeuristicFact {
   message: string;
   filePath?: string;
   lines?: readonly number[];
+  primary_node?: HeuristicNode;
+  related_nodes?: readonly HeuristicNode[];
+  why?: string;
+  impact?: string;
+  expected_fix?: string;
 }

package/core/facts/detectors/text/android.test.ts

@@ -1,6 +1,11 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import {
+  findKotlinConcreteDependencyDipMatch,
+  findKotlinInterfaceSegregationMatch,
+  findKotlinLiskovSubstitutionMatch,
+  findKotlinOpenClosedWhenMatch,
+  findKotlinPresentationSrpMatch,
   hasKotlinGlobalScopeUsage,
   hasKotlinRunBlockingUsage,
   hasKotlinThreadSleepCall,
@@ -85,3 +90,205 @@ fun main() {
   assert.equal(hasKotlinRunBlockingUsage(commentedSource), false);
   assert.equal(hasKotlinRunBlockingUsage(partialSource), false);
 });
+
+test('findKotlinPresentationSrpMatch devuelve payload semantico para SRP-Android en presentation', () => {
+  const source = `
+import android.content.SharedPreferences
+import androidx.lifecycle.ViewModel
+import androidx.navigation.NavController
+import okhttp3.OkHttpClient
+import okhttp3.Request
+
+class PumukiSrpAndroidCanaryViewModel(
+  private val navController: NavController,
+) : ViewModel() {
+  fun restoreSessionSnapshot() {}
+
+  suspend fun fetchRemoteCatalog() {
+    val client = OkHttpClient()
+    client.newCall(
+      Request.Builder()
+        .url("https://example.com/catalog.json")
+        .build()
+    )
+  }
+
+  fun cacheLastStore(preferences: SharedPreferences, storeId: String) {
+    preferences.edit().putString("last-store-id", storeId).apply()
+  }
+
+  fun openStoreMap() {
+    navController.navigate("store-map")
+  }
+}
+`;
+
+  const match = findKotlinPresentationSrpMatch(source);
+
+  assert.ok(match);
+  assert.deepEqual(match.primary_node, {
+    kind: 'class',
+    name: 'PumukiSrpAndroidCanaryViewModel',
+    lines: [8],
+  });
+  assert.deepEqual(match.related_nodes, [
+    { kind: 'member', name: 'session/auth flow', lines: [11] },
+    { kind: 'call', name: 'remote networking', lines: [14] },
+    { kind: 'call', name: 'local persistence', lines: [22] },
+    { kind: 'member', name: 'navigation flow', lines: [27] },
+  ]);
+  assert.match(match.why, /SRP/i);
+  assert.match(match.impact, /múltiples razones de cambio/i);
+  assert.match(match.expected_fix, /casos de uso|coordinadores/i);
+});
+
+test('findKotlinConcreteDependencyDipMatch devuelve payload semantico para DIP-Android en application', () => {
+  const source = `
+import android.content.SharedPreferences
+import okhttp3.OkHttpClient
+import okhttp3.Request
+
+class PumukiDipAndroidCanaryUseCase(
+  private val preferences: SharedPreferences,
+) {
+  private val client: OkHttpClient = OkHttpClient()
+
+  suspend fun execute() {
+    val request = Request.Builder()
+      .url("https://example.com/catalog.json")
+      .build()
+
+    client.newCall(request)
+    preferences.edit().putLong("last-sync", 1L).apply()
+  }
+}
+`;
+
+  const match = findKotlinConcreteDependencyDipMatch(source);
+
+  assert.ok(match);
+  assert.deepEqual(match.primary_node, {
+    kind: 'class',
+    name: 'PumukiDipAndroidCanaryUseCase',
+    lines: [6],
+  });
+  assert.deepEqual(match.related_nodes, [
+    { kind: 'property', name: 'concrete dependency: SharedPreferences', lines: [7] },
+    { kind: 'property', name: 'concrete dependency: OkHttpClient', lines: [9] },
+    { kind: 'call', name: 'OkHttpClient()', lines: [9] },
+  ]);
+  assert.match(match.why, /DIP/i);
+  assert.match(match.impact, /infraestructura|alto nivel|coste de sustituir/i);
+  assert.match(match.expected_fix, /puertos|abstracciones|gateways/i);
+});
+
+test('findKotlinOpenClosedWhenMatch devuelve payload semantico para OCP-Android en application', () => {
+  const source = `
+enum class PumukiOcpAndroidCanaryChannel {
+  GroceryPickup,
+  HomeDelivery,
+}
+
+class PumukiOcpAndroidCanaryUseCase {
+  fun resolve(channel: PumukiOcpAndroidCanaryChannel): String {
+    return when (channel) {
+      PumukiOcpAndroidCanaryChannel.GroceryPickup -> "pickup"
+      PumukiOcpAndroidCanaryChannel.HomeDelivery -> "delivery"
+    }
+  }
+}
+`;
+
+  const match = findKotlinOpenClosedWhenMatch(source);
+
+  assert.ok(match);
+  assert.deepEqual(match.primary_node, {
+    kind: 'class',
+    name: 'PumukiOcpAndroidCanaryUseCase',
+    lines: [7],
+  });
+  assert.deepEqual(match.related_nodes, [
+    { kind: 'member', name: 'discriminator switch: channel', lines: [9] },
+    { kind: 'member', name: 'branch GroceryPickup', lines: [10] },
+    { kind: 'member', name: 'branch HomeDelivery', lines: [11] },
+  ]);
+  assert.match(match.why, /OCP/i);
+  assert.match(match.impact, /nuevo caso|modificar/i);
+  assert.match(match.expected_fix, /estrategia|interfaz|registry/i);
+});
+
+test('findKotlinInterfaceSegregationMatch devuelve payload semantico para ISP-Android en application', () => {
+  const source = `
+interface PumukiIspAndroidCanarySessionPort {
+  suspend fun restoreSession()
+  suspend fun persistSessionID(id: String)
+  suspend fun clearSession()
+  suspend fun refreshToken(): String
+}
+
+class PumukiIspAndroidCanaryUseCase(
+  private val sessionPort: PumukiIspAndroidCanarySessionPort,
+) {
+  suspend fun execute() {
+    sessionPort.restoreSession()
+  }
+}
+`;
+
+  const match = findKotlinInterfaceSegregationMatch(source);
+
+  assert.ok(match);
+  assert.deepEqual(match.primary_node, {
+    kind: 'class',
+    name: 'PumukiIspAndroidCanaryUseCase',
+    lines: [9],
+  });
+  assert.deepEqual(match.related_nodes, [
+    { kind: 'member', name: 'fat interface: PumukiIspAndroidCanarySessionPort', lines: [2] },
+    { kind: 'call', name: 'used member: restoreSession', lines: [13] },
+    { kind: 'member', name: 'unused contract member: persistSessionID', lines: [4] },
+    { kind: 'member', name: 'unused contract member: clearSession', lines: [5] },
+  ]);
+  assert.match(match.why, /ISP/i);
+  assert.match(match.impact, /contrato demasiado ancho|cambios ajenos/i);
+  assert.match(match.expected_fix, /interfaces pequeñas|puerto mínimo/i);
+});
+
+test('findKotlinLiskovSubstitutionMatch devuelve payload semantico para LSP-Android en application', () => {
+  const source = `
+interface PumukiLspAndroidCanaryDiscountPolicy {
+  fun apply(amount: Double): Double
+}
+
+class PumukiLspAndroidCanaryStandardDiscountPolicy : PumukiLspAndroidCanaryDiscountPolicy {
+  override fun apply(amount: Double): Double {
+    return amount * 0.9
+  }
+}
+
+class PumukiLspAndroidCanaryPremiumDiscountPolicy : PumukiLspAndroidCanaryDiscountPolicy {
+  override fun apply(amount: Double): Double {
+    require(amount >= 100.0)
+    error("premium-only")
+  }
+}
+`;
+
+  const match = findKotlinLiskovSubstitutionMatch(source);
+
+  assert.ok(match);
+  assert.deepEqual(match.primary_node, {
+    kind: 'class',
+    name: 'PumukiLspAndroidCanaryPremiumDiscountPolicy',
+    lines: [12],
+  });
+  assert.deepEqual(match.related_nodes, [
+    { kind: 'member', name: 'base contract: PumukiLspAndroidCanaryDiscountPolicy', lines: [2] },
+    { kind: 'member', name: 'safe substitute: PumukiLspAndroidCanaryStandardDiscountPolicy', lines: [6] },
+    { kind: 'member', name: 'narrowed precondition: apply', lines: [14] },
+    { kind: 'call', name: 'error', lines: [15] },
+  ]);
+  assert.match(match.why, /LSP/i);
+  assert.match(match.impact, /sustituci|regresion|crash/i);
+  assert.match(match.expected_fix, /contrato base|estrategia|subtipo/i);
+});