pumuki 6.3.39 → 6.3.40

package/README.md

@@ -32,11 +32,17 @@ Install and bootstrap:
 
 ```bash
 npm install --save-exact pumuki
-npx --yes pumuki install
-npx --yes pumuki doctor
+npx --yes pumuki bootstrap --enterprise --agent=codex
 npx --yes pumuki status
 ```
 
+Fallback (equivalent in pasos separados):
+
+```bash
+npx --yes pumuki install --with-mcp --agent=codex
+npx --yes pumuki doctor --deep --json
+```
+
 OpenSpec/SDD baseline:
 
 ```bash
@@ -56,16 +62,16 @@ npx --yes pumuki loop list --json
 Run local gates:
 
 ```bash
-npx --yes pumuki-pre-write
-npx --yes pumuki-pre-commit
+npx --yes --package pumuki@latest pumuki-pre-write
+npx --yes --package pumuki@latest pumuki-pre-commit
 ```
 
 Run push/CI gates (requires proper git context):
 
 ```bash
 git push --set-upstream origin <branch>
-npx --yes pumuki-pre-push
-npx --yes pumuki-ci
+npx --yes --package pumuki@latest pumuki-pre-push
+npx --yes --package pumuki@latest pumuki-ci
 ```
 
 Expected behavior:
@@ -176,7 +182,7 @@ Example:
 export PUMUKI_TELEMETRY_JSONL_PATH=".pumuki/artifacts/gate-telemetry.jsonl"
 export PUMUKI_TELEMETRY_OTEL_ENDPOINT="https://otel.example/v1/logs"
 export PUMUKI_TELEMETRY_OTEL_SERVICE_NAME="pumuki-enterprise"
-npx --yes pumuki-pre-commit
+npx --yes --package pumuki@latest pumuki-pre-commit
 ```
 
 Each event captures deterministic stage/outcome/policy/repo context per gate execution.
@@ -258,16 +264,16 @@ npx --yes pumuki loop export --session=<session-id> --output-json=.audit-reports
 ### Stage Gates (Consumer)
 
 ```bash
-npx --yes pumuki-pre-write
-npx --yes pumuki-pre-commit
-npx --yes pumuki-pre-push
-npx --yes pumuki-ci
+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 pumuki-mcp-evidence
+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
@@ -359,6 +365,8 @@ Highlights:
 
 - Installation: `docs/INSTALLATION.md`
 - Usage: `docs/USAGE.md`
+- Backlog tooling quick nav (incluye snippet terminal): `docs/USAGE.md#backlog-tooling`
+- Backlog reasons shared module: `docs/USAGE.md#backlog-reasons`
 - Testing: `docs/TESTING.md`
 - API reference: `docs/API_REFERENCE.md`
 - Architecture: `docs/ARCHITECTURE.md`
@@ -382,6 +390,7 @@ Contributions are welcome. For high-quality collaboration:
 3. Keep scope focused and include deterministic evidence when relevant.
 4. Before opening a PR, run at least:
    - `npm run typecheck`
+   - `npm run -s test:backlog-tooling`
    - `npm run test:operational-memory`
    - `npm run test:saas-ingestion`
 5. Open a PR with clear problem statement, approach, and validation evidence.

package/VERSION

@@ -1 +1 @@
-v6.3.39
+v6.3.40

package/core/gate/evaluateRules.test.ts

@@ -75,6 +75,46 @@ test('evaluateRules usa id de la regla como code cuando no se define en consecue
   assert.equal(findings[0]?.severity, 'ERROR');
 });
 
+test('evaluateRules combina source del fact y source declarada por la regla', () => {
+  const rules: RuleSet = [
+    {
+      id: 'skills.backend.no-empty-catch',
+      description: 'Disallow empty catch blocks in backend runtime code.',
+      severity: 'ERROR',
+      when: {
+        kind: 'FileContent',
+        regex: ['catch\\s*\\{\\s*\\}'],
+      },
+      then: {
+        kind: 'Finding',
+        message: 'Disallow empty catch blocks in backend runtime code.',
+        code: 'SKILLS_BACKEND_NO_EMPTY_CATCH',
+        source:
+          'skills-ir:rule=skills.backend.no-empty-catch;source_skill=backend-guidelines;source_path=docs/codex-skills/windsurf-rules-backend.md;evaluation_mode=AUTO;ast_nodes=[heuristics.ts.empty-catch.ast]',
+      },
+      scope: {
+        include: ['apps/backend/'],
+      },
+    },
+  ];
+  const facts = [
+    {
+      kind: 'FileContent',
+      path: 'apps/backend/src/service.ts',
+      content: 'try { doStuff(); } catch {}',
+      source: 'git:staged',
+    },
+  ] as const;
+
+  const findings = evaluateRules(rules, facts);
+
+  assert.equal(findings.length, 1);
+  assert.equal(
+    findings[0]?.source,
+    'git:staged|skills-ir:rule=skills.backend.no-empty-catch;source_skill=backend-guidelines;source_path=docs/codex-skills/windsurf-rules-backend.md;evaluation_mode=AUTO;ast_nodes=[heuristics.ts.empty-catch.ast]'
+  );
+});
+
 test('evaluateRules respeta scope y no genera hallazgo cuando no coincide', () => {
   const rules: RuleSet = [
     {

package/core/gate/evaluateRules.ts

@@ -27,6 +27,12 @@ const toFinding = (
   consequence: Consequence,
   target?: FindingTarget
 ): Finding => {
+  const sourceParts = [
+    target?.source?.trim(),
+    consequence.source?.trim(),
+  ].filter((part): part is string => typeof part === 'string' && part.length > 0);
+  const mergedSource = sourceParts.length > 0 ? sourceParts.join('|') : undefined;
+
   return {
     ruleId: rule.id,
     severity: rule.severity,
@@ -34,7 +40,7 @@ const toFinding = (
     message: consequence.message,
     filePath: target?.filePath,
     matchedBy: target?.matchedBy,
-    source: target?.source,
+    source: mergedSource,
   };
 };
 

package/core/rules/Consequence.ts

@@ -2,4 +2,5 @@ export type Consequence = {
   kind: 'Finding';
   message: string;
   code?: string;
+  source?: string;
 };

package/docs/CONFIGURATION.md

@@ -192,6 +192,7 @@ Behavior:
 - `rule_updates`: deterministic recommendations derived from evidence/gate signals (`missing`, `invalid`, `blocked`, `allowed`).
 - dedicated command: `pumuki sdd learn --change=<id> [--stage=<stage>] [--task=<task>] [--dry-run] [--json]` generates/persists the same artifact without requiring `sync-docs`.
 - orchestration command: `pumuki sdd auto-sync --change=<id> [--stage=<stage>] [--task=<task>] [--dry-run] [--json]` executes deterministic docs sync plus learning generation in one step.
+- safety limit: `--from-evidence` must resolve inside the repository root; path traversal/outside-repo paths are blocked.
 
 ## Gate telemetry export (optional)
 
@@ -241,6 +242,18 @@ PUMUKI_ENABLE_AST_HEURISTICS=true
 
 When enabled, stage-based heuristic severity maturity applies via `applyHeuristicSeverityForStage`.
 
+## AST Intelligence dual mode (legacy + nodos)
+
+Controla la validación dual entre findings legacy y evaluación AST por nodos compilados desde `skills-ir`.
+
+```bash
+PUMUKI_AST_INTELLIGENCE_DUAL_MODE=off|shadow|strict
+```
+
+- `off` (default): desactivado.
+- `shadow`: compara y reporta divergencias sin bloquear.
+- `strict`: bloquea si hay divergencias (`false_positive/false_negative`) entre legacy y AST.
+
 ## Rule packs
 
 Version map lives in `core/rules/presets/rulePackVersions.ts`.
@@ -265,6 +278,43 @@ Configuration outcomes are reflected in `.ai_evidence.json`:
 
 Schema reference: `docs/evidence-v2.1.md`.
 
+## AI Gate skills contract
+
+`evaluateAiGate` now emits a machine-readable contract snapshot under `skills_contract`.
+
+Contract goals:
+
+- deterministic mapping: `detected platform -> required skills policy/rules`
+- explicit coverage checks for `active_rule_ids` and `evaluated_rule_ids`
+- stage-aware enforcement beyond PRE_WRITE (`PRE_COMMIT`, `PRE_PUSH`, `CI`)
+
+Runtime fields:
+
+- `skills_contract.stage`
+- `skills_contract.status` (`PASS|FAIL|NOT_APPLICABLE`)
+- `skills_contract.detected_platforms`
+- `skills_contract.requirements[]`
+- `skills_contract.violations[]`
+
+Blocking code:
+
+- `EVIDENCE_SKILLS_CONTRACT_INCOMPLETE` (when contract is incomplete outside PRE_WRITE)
+
+## PRE_WRITE worktree hygiene guard
+
+AI Gate can enforce early worktree hygiene in `PRE_WRITE` to reduce non-atomic changes before commit time.
+
+Environment variables:
+
+- `PUMUKI_PREWRITE_WORKTREE_HYGIENE_ENABLED` (`true|false`, default: `true`)
+- `PUMUKI_PREWRITE_WORKTREE_WARN_THRESHOLD` (default: `12`)
+- `PUMUKI_PREWRITE_WORKTREE_BLOCK_THRESHOLD` (default: `24`)
+
+Codes emitted:
+
+- `EVIDENCE_PREWRITE_WORKTREE_WARN` (warning, still `ALLOWED`)
+- `EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT` (blocking error)
+
 ## TDD/BDD Vertical Enforcement Contract
 
 For new/complex changes, Pumuki enforces a neutral TDD/BDD evidence contract.

package/docs/INSTALLATION.md

@@ -45,10 +45,10 @@ If both commands pass, the workspace is ready.
 npm install --save-exact pumuki
 ```
 
-### 2) Install managed lifecycle and OpenSpec bootstrap
+### 2) Bootstrap managed lifecycle (recommended single command)
 
 ```bash
-npx --yes pumuki install
+npx --yes pumuki bootstrap --enterprise --agent=codex
 ```
 
 Behavior:
@@ -56,11 +56,20 @@ Behavior:
 - Auto-installs `@fission-ai/openspec@latest` when OpenSpec is missing/incompatible (when `package.json` exists).
 - Scaffolds `openspec/` baseline if missing (`project` file plus archive/spec placeholders).
 - Bootstraps `.ai_evidence.json` when missing (deterministic empty baseline with repo state snapshot).
+- Scaffolds adapter wiring (`.pumuki/adapter.json` by default) and runs `doctor --deep` automatically.
+
+Fallback (equivalent):
+
+```bash
+npx --yes pumuki install --with-mcp --agent=codex
+npx --yes pumuki doctor --deep --json
+```
 
 ### 3) Verify lifecycle and SDD status
 
 ```bash
 npx --yes pumuki doctor
+npx --yes pumuki doctor --deep --json
 npx --yes pumuki status
 npx --yes pumuki sdd status
 ```
@@ -81,10 +90,10 @@ npx --yes pumuki sdd validate --stage=PRE_COMMIT
 ### 5) Run gates
 
 ```bash
-npx --yes pumuki-pre-write
-npx --yes pumuki-pre-commit
-npx --yes pumuki-pre-push
-npx --yes pumuki-ci
+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
 ```
 
 `PRE_WRITE` JSON shape:
@@ -121,23 +130,23 @@ Consumer repositories do not have the `framework:menu` npm script by default.
 Use the published binary instead:
 
 ```bash
-npx --yes pumuki-framework
+npx --yes --package pumuki@latest pumuki-framework
 ```
 
 ### Direct stage runners
 
 ```bash
 # PRE_WRITE
-npx --yes pumuki-pre-write
+npx --yes --package pumuki@latest pumuki-pre-write
 
 # PRE_COMMIT
-npx --yes pumuki-pre-commit
+npx --yes --package pumuki@latest pumuki-pre-commit
 
 # PRE_PUSH
-npx --yes pumuki-pre-push
+npx --yes --package pumuki@latest pumuki-pre-push
 
 # CI
-npx --yes pumuki-ci
+npx --yes --package pumuki@latest pumuki-ci
 ```
 
 ## Lifecycle + SDD commands
@@ -241,3 +250,21 @@ Then reopen/refresh active session:
 npx --yes pumuki sdd session --open --change=<change-id>
 npx --yes pumuki sdd session --refresh
 ```
+
+### Hooks/adapter use fragile `npx` binary resolution
+
+Run deep doctor diagnostics and verify `adapter-wiring`:
+
+```bash
+npx --yes pumuki doctor --deep --json
+```
+
+If doctor reports fragile commands in adapter wiring, repair with:
+
+```bash
+npx --yes pumuki adapter install --agent=codex
+```
+
+Notes for repos with `:` in path:
+- Avoid adapter/hook commands that mutate `PATH` inline (for example `PATH="...:$PATH" npx ...`).
+- Prefer generated commands from `pumuki adapter install` (local bin / local node entry / `npx --package` fallback).

package/docs/MCP_SERVERS.md

@@ -21,7 +21,7 @@ npm run mcp:enterprise
 ### Desde un repositorio consumidor
 
 ```bash
-npx --yes pumuki-mcp-evidence
+npx --yes --package pumuki@latest pumuki-mcp-evidence
 npx --yes --package pumuki@latest pumuki-mcp-enterprise
 npx --yes --package pumuki@latest pumuki-mcp-enterprise-stdio
 ```

package/docs/README.md

@@ -48,6 +48,7 @@ Canonical index for active Pumuki documentation.
 
 - `docs/validation/README.md`: enterprise minimal validation index.
 - `docs/validation/adapter-hook-runtime-validation.md`
+- `docs/validation/ast-intelligence-roadmap.md`
 - `docs/validation/c022-phase-acceptance-contract.md`
 - `docs/validation/enterprise-consumer-isolation-policy.md`
 - `docs/validation/mock-consumer-integration-runbook.md`

package/docs/RELEASE_NOTES.md

@@ -5,6 +5,50 @@ Detailed commit history remains available through Git history (`git log` / `git
 
 ## 2026-03 (enterprise hardening updates)
 
+### 2026-03-05 (v6.3.40)
+
+- AST Intelligence dual validation PoC (`#616`) integrado en gate:
+  - runtime mode: `PUMUKI_AST_INTELLIGENCE_DUAL_MODE=off|shadow|strict`.
+  - `shadow`: comparación legacy vs AST por nodos sin bloqueo.
+  - `strict`: bloqueo cuando hay divergencias.
+  - métricas en runtime: `mapped_rules`, `divergences`, `false_positives`, `false_negatives`, `latency_ms`, `languages`.
+- Señales de gate añadidas:
+  - `governance.ast-intelligence.dual-validation.shadow`
+  - `governance.ast-intelligence.dual-validation.mismatch`
+- Backlog tooling (`watch/reconcile`) amplía contrato JSON en `next_commands[]`:
+  - nuevo campo `probe_kind` (`json_contract` | `state_recheck`) para tipar verificación post-ejecución.
+- Correcciones de robustez operativa en consumidores reales:
+  - `PRE_PUSH` detecta upstream desalineado antes de evaluar scope coverage (evita falsos positivos de plataforma por delta contaminado).
+  - smoke de instalación local hace fallback cuando `npx --no-install` falla por `MODULE_NOT_FOUND`.
+  - `ai_gate_check` unifica hint de precedencia para códigos legacy `EVIDENCE_*` (incluye `EVIDENCE_INTEGRITY_MISSING`).
+- RFC y plan de rollout/rollback:
+  - `docs/validation/ast-intelligence-roadmap.md`.
+- Evidencia de validación:
+  - `npx --yes tsx@4.21.0 --test scripts/__tests__/backlog-cli-help-exit-code.test.ts` (`11 pass / 0 fail`)
+  - `npm run -s typecheck` (`PASS`)
+  - `npm run -s test:stage-gates` (`1033 pass / 0 fail / 4 skip`)
+
+### 2026-03-04 (next cut candidate, post v6.3.39)
+
+- Gate coverage hardening for SAAS backlog (`#622`):
+  - when code changes are present and `active_rule_ids` is empty, gate now blocks with:
+    - finding id: `governance.rules.active-rule-coverage.empty`
+    - code: `ACTIVE_RULE_IDS_EMPTY_FOR_CODE_CHANGES_HIGH`
+- iOS test quality hardening for SAAS backlog (`#623`):
+  - for XCTest sources in `apps/ios/**/Tests/**.swift`, gate now requires:
+    - `makeSUT()`
+    - `trackForMemoryLeaks()`
+  - blocking signal:
+    - finding id: `governance.skills.ios-test-quality.incomplete`
+    - code: `IOS_TEST_QUALITY_PATTERN_MISSING_HIGH`
+- Gate traceability consistency:
+  - fixed propagation of guard findings to `effectiveFindings` so `BLOCK` outcomes are always accompanied by explicit finding payload.
+- Validation evidence:
+  - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/runPlatformGate.test.ts` (`32 pass / 0 fail`)
+  - `npx --yes tsx@4.21.0 --test integrations/git/__tests__/stageRunners.test.ts` (`21 pass / 0 fail`)
+  - `npm run -s typecheck` (`PASS`)
+  - `npm run -s test:stage-gates` (`1024 pass / 0 fail / 4 skip`)
+
 ### 2026-03-04 (v6.3.39)
 
 - Adapter/runtime bootstrap hardening: