pumuki 6.3.39 → 6.3.40

package/docs/USAGE.md

@@ -70,8 +70,8 @@ Pumuki enforces OpenSpec policy/session before allowing normal gate execution.
 Minimal daily flow:
 
 ```bash
-# bootstrap lifecycle + OpenSpec baseline when needed
-npx --yes pumuki install
+# bootstrap lifecycle + OpenSpec + MCP wiring + doctor deep
+npx --yes pumuki bootstrap --enterprise --agent=codex
 
 # inspect current SDD status
 npx --yes pumuki sdd status
@@ -110,7 +110,7 @@ npm run framework:menu
 Consumer repository:
 
 ```bash
-npx --yes pumuki-framework
+npx --yes --package pumuki@latest pumuki-framework
 ```
 
 Menu starts in `Consumer` mode by default (focused operational options).
@@ -211,16 +211,16 @@ Menu-driven audits apply SDD guardrails with the same strict semantics as stage
 
 ```bash
 # 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
 
 # PRE_WRITE (SDD + AI Gate pre-write policy check)
-npx --yes pumuki-pre-write
+npx --yes --package pumuki@latest pumuki-pre-write
 ```
 
 ### 2.1) Lifecycle + SDD + Loop CLI (install / uninstall / remove / update / doctor / status / sdd / loop)
@@ -236,15 +236,26 @@ npm uninstall pumuki
 `npm upgrade pumuki` is valid where npm maps `upgrade` to `update`.
 
 ```bash
-# install managed hooks
-npx --yes pumuki install
+# recommended: one-shot enterprise bootstrap
+npx --yes pumuki bootstrap --enterprise --agent=codex
+
+# fallback: separated flow
+npx --yes pumuki install --with-mcp --agent=codex
 
 # inspect enterprise baseline safety checks
 npx --yes pumuki doctor
+# include deterministic adapter/mcp wiring health checks
+npx --yes pumuki doctor --deep --json
 
 # show lifecycle status
 npx --yes pumuki status
 
+# proactive local watch (worktree + anti-spam notifications)
+npx --yes pumuki watch --stage=PRE_COMMIT --scope=workingTree --severity=high --interval-ms=3000 --notify-cooldown-ms=30000
+
+# one-shot watch tick (scripts/diagnostics)
+npx --yes pumuki watch --once --json
+
 # show SDD/OpenSpec status snapshot
 npx --yes pumuki sdd status
 
@@ -256,6 +267,15 @@ npx --yes pumuki sdd session --open --change=<change-id>
 npx --yes pumuki sdd session --refresh
 npx --yes pumuki sdd session --close
 
+# reconcile AGENTS/skills.lock/policy-as-code contract
+npx --yes pumuki policy reconcile --json
+
+# scaffold deterministic scenario evidence from real test metadata
+npx --yes pumuki sdd evidence --scenario-id=<scenario-id> --test-command='npm run test -- --grep <scenario-id>' --test-status=passed --dry-run --json
+
+# sync scenario state into board artifact (dry-run/apply + conflict-safe)
+npx --yes pumuki sdd state-sync --scenario-id=<scenario-id> --status=in_progress --dry-run --json
+
 # local hotspots analytics and SaaS publication diagnostics
 npx --yes pumuki analytics hotspots report --top=10 --since-days=90 --json
 npx --yes pumuki analytics hotspots diagnose --json
@@ -299,8 +319,134 @@ Loop runtime behavior:
 - Gate policy is strict fail-fast: a blocked attempt returns exit code `1` and status `blocked`.
 - Per-attempt evidence is persisted as `.pumuki/loop-sessions/<session-id>.attempt-<n>.json`.
 
+Watch runtime behavior:
+- `pumuki watch` evaluates gate policy on local changes and emits terminal summaries on each evaluation tick.
+- `--severity` defines notification threshold (`critical|high|medium|low`) without changing gate block policy.
+- `--notify-cooldown-ms` enables anti-spam throttling for repeated alerts with equal signature.
+- `--no-notify` keeps watch output without OS notifications.
+- `--once` or `--iterations=<n>` is recommended for CI/scripts to avoid long-running sessions.
+
+<a id="backlog-tooling"></a>
+Backlog tooling behavior (`watch` + `reconcile` scripts):
+- mapping precedence is deterministic: inline `#issue` -> `--id-issue-map-from` -> `--id-issue-map` -> `--resolve-missing-via-gh`.
+- `watch-consumer-backlog` is non-destructive and reports action-required drift.
+- `watch-consumer-backlog` reports heading drift (`heading_drift`) when section headers `### ✅/🚧/⏳/⛔ <ID>` diverge from effective table status.
+- `watch-consumer-backlog --json` exposes `heading_drift_count` for low-friction alerting parsers.
+- `watch-consumer-backlog --json` exposes `classification_counts` (`needs_issue`, `drift_closed_issue`, `active_issue`, `heading_drift`).
+- `watch-consumer-backlog --json` exposes `action_required_reasons` when findings are active.
+- `watch-consumer-backlog --json` exposes `next_command` when action is required (safe reconcile sequence).
+- `watch-consumer-backlog --json` exposes `next_command_reason` when `next_command` is present.
+- `watch-consumer-backlog --json` exposes `next_commands[]` (ordered dry-run/apply steps) when action is required.
+- `watch-consumer-backlog --json` includes `next_commands[].id` (1-based stable order).
+- `watch-consumer-backlog --json` includes `next_commands[].safety` (`read_only` | `mutating`) for orchestration safety.
+- `watch-consumer-backlog --json` includes `next_commands[].idempotent` for retry-safe orchestration.
+- `watch-consumer-backlog --json` includes `next_commands[].max_retries` (`2` for `dry_run`, `0` for `apply`) for bounded retries.
+- `watch-consumer-backlog --json` includes `next_commands[].retry_strategy` (`immediate` for `dry_run`, `manual` for `apply`) for retry policy semantics.
+- `watch-consumer-backlog --json` includes `next_commands[].estimated_duration_ms` for timeout/scheduling hints.
+- `watch-consumer-backlog --json` includes `next_commands[].requires_confirmation` for safe mutating-step execution.
+- `watch-consumer-backlog --json` includes `next_commands[].depends_on` for step sequencing (`null` for dry-run, `dry_run` for apply).
+- `watch-consumer-backlog --json` includes `next_commands[].execution_group_id` to correlate all suggested steps in the same run.
+- `watch-consumer-backlog --json` includes `next_commands[].origin_tool` (`backlog-watch`) for multi-tool aggregation.
+- `watch-consumer-backlog --json` includes `next_commands[].origin_schema_version` to bind each step to the emitting schema contract.
+- `watch-consumer-backlog --json` includes `next_commands[].origin_contract_id` to bind each step to compatibility contract id.
+- `watch-consumer-backlog --json` includes `next_commands[].recommendation_type` (`reconcile_loop`) for recommendation classification.
+- `watch-consumer-backlog --json` includes `next_commands[].priority` (`high` for `dry_run`, `medium` for `apply`) for scheduling.
+- `watch-consumer-backlog --json` includes `next_commands[].description` for human-readable step guidance.
+- `watch-consumer-backlog --json` includes `next_commands[].expected_outcome` with success signal per step.
+- `watch-consumer-backlog --json` includes `next_commands[].success_criteria` with stable machine-readable success checks.
+- `watch-consumer-backlog --json` includes `next_commands[].success_probe` with deterministic post-execution verification hints.
+- `watch-consumer-backlog --json` includes `next_commands[].probe_kind` (`json_contract` | `state_recheck`) to type post-execution probes.
+- `watch-consumer-backlog --json` includes `next_commands[].probe_timeout_ms` with recommended timeout for `success_probe`.
+- `watch-consumer-backlog --json` includes `next_commands[].failure_hint` with compact remediation guidance per step.
+- `watch-consumer-backlog` (modo humano) imprime `action_required_reasons=<...|none>`.
+- `watch-consumer-backlog` (modo humano) añade hint `--no-fail` cuando hay acción requerida.
+- `reconcile-consumer-backlog-issues` supports dry-run/apply and now reports mapping source (`none|json|markdown|merged`).
+- `reconcile-consumer-backlog-issues --json` includes heading sync metadata (`headingUpdated`, `headingChanges`) for section headings `### ✅/🚧/⏳/⛔ <ID>`.
+- `reconcile-consumer-backlog-issues --json` exposes `heading_changes_count` for lightweight consumers.
+- `reconcile-consumer-backlog-issues --json` exposes `classification_counts` (changes + summary counters) for dashboards.
+- `reconcile-consumer-backlog-issues --json` exposes `action_required_reasons` for pending deltas in dry-run/apply flows.
+- `reconcile-consumer-backlog-issues --json` exposes `next_command` when there are actionable deltas (`--json` + `--apply` sequence).
+- `reconcile-consumer-backlog-issues --json` exposes `next_command_reason` when `next_command` is present.
+- `reconcile-consumer-backlog-issues --json` exposes `next_commands[]` (ordered dry-run/apply steps) when action is required.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].id` (1-based stable order).
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].safety` (`read_only` | `mutating`) for orchestration safety.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].idempotent` for retry-safe orchestration.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].max_retries` (`2` for `dry_run`, `0` for `apply`) for bounded retries.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].retry_strategy` (`immediate` for `dry_run`, `manual` for `apply`) for retry policy semantics.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].estimated_duration_ms` for timeout/scheduling hints.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].requires_confirmation` for safe mutating-step execution.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].depends_on` for step sequencing (`null` for dry-run, `dry_run` for apply).
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].execution_group_id` to correlate all suggested steps in the same run.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].origin_tool` (`backlog-reconcile`) for multi-tool aggregation.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].origin_schema_version` to bind each step to the emitting schema contract.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].origin_contract_id` to bind each step to compatibility contract id.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].recommendation_type` (`reconcile_loop`) for recommendation classification.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].priority` (`high` for `dry_run`, `medium` for `apply`) for scheduling.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].description` for human-readable step guidance.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].expected_outcome` with success signal per step.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].success_criteria` with stable machine-readable success checks.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].success_probe` with deterministic post-execution verification hints.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].probe_kind` (`json_contract` | `state_recheck`) to type post-execution probes.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].probe_timeout_ms` with recommended timeout for `success_probe`.
+- `reconcile-consumer-backlog-issues --json` includes `next_commands[].failure_hint` with compact remediation guidance per step.
+- `reconcile-consumer-backlog-issues` (modo humano) muestra `heading_changes=<n>` y lista las líneas afectadas cuando hay drift en encabezados.
+- `reconcile-consumer-backlog-issues` (modo humano) imprime `action_required_reasons=<...|none>`.
+- `reconcile-consumer-backlog-issues` (modo humano) añade hint de flujo seguro cuando hay deltas: `--json` (dry-run) y luego `--apply`.
+<a id="backlog-reasons"></a>
+- Both commands build reasons through shared logic in `scripts/backlog-action-reasons-lib.ts` to keep JSON/human parity.
+
+Backlog tooling quick reference:
+
+| Command | Objective |
+|---|---|
+| `npm run -s test:backlog-tooling` | Ejecutar suite focal de regresión del tooling de backlog. |
+| `scripts/watch-consumer-backlog.ts --json` | Detectar drift accionable sin mutar archivos. |
+| `scripts/reconcile-consumer-backlog-issues.ts --json` | Simular reconciliación (dry-run) y revisar cambios planeados. |
+| `scripts/reconcile-consumer-backlog-issues.ts --apply` | Aplicar reconciliación sobre el backlog consumidor. |
+
+Backlog tooling quick nav (terminal):
+
+```bash
+rg -n "backlog-tooling|backlog-reasons" docs/USAGE.md README.md
+```
+
+Backlog tooling quick examples:
+
+```bash
+# focused local regression pack for backlog tooling
+npm run -s test:backlog-tooling
+
+# watch: canonical markdown source + explicit override + optional gh lookup
+npx --yes tsx@4.21.0 scripts/watch-consumer-backlog.ts \
+  --file=/abs/path/consumer/PUMUKI_BUGS_MEJORAS.md \
+  --repo=SwiftEnProfundidad/ast-intelligence-hooks \
+  --id-issue-map-from=/abs/path/canonical/pumuki-integration-feedback.md \
+  --id-issue-map=/abs/path/override.json \
+  --resolve-missing-via-gh \
+  --json
+
+# reconcile dry-run: same source chain
+npx --yes tsx@4.21.0 scripts/reconcile-consumer-backlog-issues.ts \
+  --file=/abs/path/consumer/PUMUKI_BUGS_MEJORAS.md \
+  --repo=SwiftEnProfundidad/ast-intelligence-hooks \
+  --id-issue-map-from=/abs/path/canonical/pumuki-integration-feedback.md \
+  --id-issue-map=/abs/path/override.json \
+  --resolve-missing-via-gh \
+  --json
+
+# reconcile apply: mutate backlog in-place once dry-run is clean
+npx --yes tsx@4.21.0 scripts/reconcile-consumer-backlog-issues.ts \
+  --file=/abs/path/consumer/PUMUKI_BUGS_MEJORAS.md \
+  --repo=SwiftEnProfundidad/ast-intelligence-hooks \
+  --id-issue-map-from=/abs/path/canonical/pumuki-integration-feedback.md \
+  --resolve-missing-via-gh \
+  --apply
+```
+
 OpenSpec integration behavior:
+- `pumuki bootstrap --enterprise --agent=<name>` orquesta `install + adapter wiring + doctor --deep` en un solo paso.
 - `pumuki install` auto-bootstraps OpenSpec (`@fission-ai/openspec`) when missing/incompatible and scaffolds `openspec/` project baseline when absent.
+- `pumuki install --with-mcp` adds adapter/MCP wiring bootstrap and prints MCP health summary on completion.
 - `pumuki update --latest` migrates legacy `openspec` package to `@fission-ai/openspec` before hook reinstall.
 
 Safety rule:
@@ -426,9 +572,14 @@ npm run validation:clean-artifacts -- --dry-run
 - Runs SDD pre-write guardrail and then AI Gate validation before continuing editing flow.
 - Requires OpenSpec installed, compatible, initialized, and valid active session.
 - AI Gate blocks on missing/invalid/stale evidence, blocked evidence gate status, or protected branch usage.
+- AI Gate applies early worktree hygiene for atomicity:
+  - warning code: `EVIDENCE_PREWRITE_WORKTREE_WARN`
+  - blocking code: `EVIDENCE_PREWRITE_WORKTREE_OVER_LIMIT`
+  - configurable via `PUMUKI_PREWRITE_WORKTREE_HYGIENE_ENABLED`, `PUMUKI_PREWRITE_WORKTREE_WARN_THRESHOLD`, `PUMUKI_PREWRITE_WORKTREE_BLOCK_THRESHOLD`
 - `pumuki sdd validate --stage=PRE_WRITE --json` returns an envelope with:
   - `sdd` (SDD decision payload)
   - `ai_gate` (AI Gate evaluation payload)
+  - `ai_gate.skills_contract` (mapping `scope -> required skills/rules -> coverage active/evaluated`)
   - `telemetry.chain = "pumuki->ai_gate->ai_evidence"`
 
 Resolver source: `integrations/git/resolveGitRefs.ts`.
@@ -481,6 +632,20 @@ PUMUKI_ENABLE_AST_HEURISTICS=true npx tsx integrations/git/prePushIOS.cli.ts
 
 Details: `docs/rule-packs/heuristics.md`.
 
+## AST Intelligence dual mode (comparación legacy vs AST)
+
+Activar modo dual:
+
+```bash
+PUMUKI_AST_INTELLIGENCE_DUAL_MODE=shadow npx --yes --package pumuki@latest pumuki-pre-commit
+```
+
+Modos soportados:
+
+- `off` (default): no ejecuta comparación dual.
+- `shadow`: añade señal informativa de divergencias sin bloquear.
+- `strict`: bloquea cuando hay divergencias entre legacy y AST por nodos.
+
 ## CI workflows
 
 - `.github/workflows/pumuki-gate-template.yml`
@@ -526,6 +691,23 @@ Set upstream once:
 git push --set-upstream origin <branch>
 ```
 
+### Fragile hook/adapter command resolution
+
+Use deep diagnostics to detect weak command wiring:
+
+```bash
+npx --yes pumuki doctor --deep --json
+```
+
+If `adapter-wiring` reports fragile resolution, regenerate adapter commands:
+
+```bash
+npx --yes pumuki adapter install --agent=codex
+```
+
+For repos whose absolute path includes `:`, avoid inline `PATH="...:$PATH"` wrappers in hooks/adapters.
+Use generated commands from `pumuki adapter install` to keep resolution deterministic.
+
 ### Empty evidence or PASS with no findings
 
 Confirm changed files match supported extensions and platform paths expected by detectors.

package/docs/registro-maestro-de-seguimiento.md

@@ -7,8 +7,8 @@
 ## Estado actual
 - Plan activo: `docs/seguimiento-activo-pumuki-saas-supermercados.md`
 - Estado del plan: EJECUCION
-- Última task cerrada (`✅`): PUMUKI-019 (hardening de diagnóstico para hooks versionados `core.hooksPath` con fallback robusto + cobertura de no-regresión).
-- Task activa (`🚧`): PUMUKI-020 (publicación del siguiente corte tras cierre de PUMUKI-019).
+- Última task cerrada (`✅`): PUMUKI-131 (issue `#716`, `next_commands[].probe_timeout_ms`).
+- Task activa (`🚧`): PUMUKI-132 (issue `#717`, `next_commands[].probe_kind`).
 - Nuevos pendientes añadidos (`⏳`): ninguno en este bloque inmediato.
 
 ## Historial resumido