@orchestrator-claude/definitions 3.30.2 → 3.31.1

package/skills/project-management-enterprise/SKILL.md

@@ -0,0 +1,304 @@
+---
+name: project-management-enterprise
+description: PME workflow runtime playbook. Load when: "PME workflow", "consultoria", "consultoria externa", "consultoria interna", "software handoff", "cirurgico", "variant=consultoria-externa", or when starting/advancing a project_management_enterprise workflow. Provides variant selection guide, gate intensity tuning, persona pairing strategy, adversarial review iteration playbook, and phase lifecycle reference.
+allowed-tools: Read
+---
+
+# Skill: /project-management-enterprise (PME Workflow Runtime Playbook)
+
+> **Scope:** this skill is loaded by the orchestrator when a `project_management_enterprise` workflow is being started, advanced, or evaluated. It covers variant selection, gate intensity, persona pairing, and adversarial review iteration. Orchestrator runtime call signatures live in `/orchestrator`. Universal invariants live in `CLAUDE.md`. The variant mechanic is governed by **ADR-020** and implemented in **RFC-031**; this skill is the operator guide for the PME consumer defined in **RFC-032**.
+
+---
+
+## When to Use This Skill
+
+Load this skill when **any** of the following apply:
+
+- User requests a "PME workflow", "consultoria", "consultoria externa", "consultoria interna", or "engajamento externo"
+- User says "software handoff", "cirurgico", or "intervencao cirurgica"
+- A `startWorkflow` call includes `type: "project_management_enterprise"`
+- The prompt contains `variant=consultoria-externa`, `variant=consultoria-interna`, `variant=software-handoff`, or `variant=cirurgico`
+- The orchestrator is advancing any of the five PME phases: DISCOVERY, RESEARCH, FRAMEWORK, OPERATIONAL, DELIVER
+- The adversarial gate fires on the RESEARCH phase exit and guidance is needed on iteration protocol
+
+**Do NOT load for:**
+
+- `feature_development` workflows — use `/orchestrator` alone
+- `bug_fix`, `refactoring`, or `emergency_debug` workflows
+- Deliverable file generation — use `/artifact-generator` for xlsx/pdf/csv/docx output
+- Markdown spec/plan/task authoring — use `/artifact-production`
+
+---
+
+## Variant Selection Guide
+
+Use this section to choose the correct variant at `startWorkflow` time. The variant is immutable once set; pre-flight validation rejects unknown or empty variant names (RFC-032 §9 error code `VARIANT_NOT_FOUND` / `EMPTY_VARIANT_NAME`).
+
+### Variant Matrix
+
+| Situation | Variant | Why |
+|---|---|---|
+| External client, full consultoria engagement, all phases, adversarial gate mandatory | `consultoria-externa` | Gate cell `REQ` — defends against methodology defects before framework is built; appropriate where methodology errors have reputational or contractual consequences |
+| Internal team, methodology research EXECUTES (AMENDED S183 — research gate decision), adversarial gate optional | `consultoria-interna` | Research phase `EXEC`; gate cell `OPT` (default OFF); lighter path for teams with existing domain knowledge |
+| Existing project handed to a vendor or software team, needs structured handoff package | `software-handoff` | All phases `EXEC`; gate cell `OPT`; `deliver` phase fires a transition rule that seeds a `feature_development` workflow with `framework_doc` and `deliverables_list` as inherited artifacts |
+| Surgical scope fix, upstream framework already established, minimal artifact set | `cirurgico` | Discovery `EXEC`, Framework `SKIP`, Research `SKIP`, Operational `PARTIAL` (scope_brief + patch_summary), Deliver `EXEC`; gate `SKIP`; requires `framework` artifact_ref and `scope` file_ref at pre-flight |
+
+### Decision Tree
+
+Answer these four questions in order:
+
+```
+Q1. Is the primary audience external (client, regulator, board)?
+    YES --> Q2
+    NO  --> consultoria-interna  [lighter gate, research EXEC per S183]
+
+Q2. Is there an existing framework / prior PME run that covers the research layer?
+    YES --> Q3
+    NO  --> consultoria-externa  [full run, gate REQ]
+
+Q3. Will the final deliverable be handed off to a software team as a spec?
+    YES --> software-handoff  [all phases EXEC, transition rule fires after deliver]
+    NO  --> Q4
+
+Q4. Is the scope narrow enough to fit a single targeted patch/intervention?
+    YES --> cirurgico  [PARTIAL discovery + deliver, research SKIP, gate SKIP]
+    NO  --> consultoria-externa  [full run, gate REQ]
+```
+
+### Required Inputs by Variant
+
+| Variant | Required at startWorkflow |
+|---|---|
+| `consultoria-externa` | `client_name` (string), `project_brief` (string) |
+| `consultoria-interna` | `client_name` (string) |
+| `software-handoff` | `client_name` (string), `repo_url` (string) |
+| `cirurgico` | `framework` (artifact_ref), `scope` (file_ref) |
+
+Missing any required input raises `MISSING_REQUIRED_INPUT` at pre-flight before the first phase dispatches (RFC-032 §9).
+
+---
+
+## Gate Intensity Tuning
+
+The adversarial gate on the RESEARCH phase exit converges when `severity:high == 0` on the latest review artifact. This is the v1.0 default per **ADR-021 §3.2**. Adjust intensity by industry context:
+
+### Convergence Thresholds by Industry
+
+| Industry | Convergence Criterion | Notes |
+|---|---|---|
+| Default (all industries) | `severity:high == 0` after <= 3 iterations | Baseline per ADR-021 |
+| Finance / auditing | `severity:high == 0` AND `severity:medium == 0` | Tighter: regulatory standards require zero medium findings too |
+| Healthcare / compliance-heavy | `severity:high == 0` AND `severity:medium == 0` | Same as finance; compliance audit trail must be clean |
+| Marketing / brand | `severity:high <= 2` acceptable | Looser: subjective taste findings classified as high are common; threshold softened to avoid gate churn |
+| Technology / SaaS internal | `severity:high == 0` (default) | Standard threshold applies |
+
+**Architectural reference:** ADR-021 governs the gate-as-gate-not-phase principle. Per-gate configurability is a post-S183 follow-up (ADR-021 §3.2); these tuning rules are operator guidance until that follow-up lands.
+
+### Force-Pass Escape Hatch
+
+If `severity:high > 0` remains after 3 iterations, the workflow escalates to the user:
+
+- `--force-pass` — bypass gate, log the override in the `adversarial-review-log.md` artifact; workflow proceeds to FRAMEWORK
+- `--abort` — cancel the workflow; no further phases dispatch
+
+Force-pass is always logged. Never bypass silently. The 3-iteration HARD CAP is enforced by the gate runner; see Adversarial Review Iteration Playbook section below.
+
+---
+
+## Persona Pairing Strategy
+
+The adversarial-reviewer agent receives a `persona_id` from the persona library (see `.claude/personas/INDEX.md` for the full catalog; current seed: `cfo-conservador`, `diretor-cetico-fmcg`, `designer-perfeccionista`, `auditor-compliance`). Select the persona that matches the primary stakeholder who will scrutinise the phase output.
+
+### Pairing Guide by Phase
+
+**DISCOVERY phase**
+
+Match persona to the client's seniority and domain:
+
+| Client profile | Recommended persona |
+|---|---|
+| CFO / CEO / board-level | `cfo-conservador` or `diretor-cetico-fmcg` |
+| Brand / creative director | `designer-perfeccionista` |
+| Compliance / legal officer | `auditor-compliance` |
+| Engineering / CTO | `engenheiro-cetico-construcao` (if seeded) |
+
+**RESEARCH gate (adversarial-reviewer dispatch)**
+
+- Primary: same persona selected for DISCOVERY (continuity of lens)
+- Secondary (compliance-heavy industries): add `auditor-compliance` as a secondary reviewer in a second iteration pass to cover regulatory blind spots
+
+**DELIVER gate**
+
+Use the persona that matches the **actual stakeholder who signs off** on the deliverable, not the internal sponsor:
+
+- External board / investor sign-off: `cfo-conservador`
+- Brand committee sign-off: `designer-perfeccionista`
+- Regulatory sign-off: `auditor-compliance`
+
+### Persona Override
+
+The user may override persona selection at any phase via `--persona=<id>`. Record the override and rationale in `persona-selection-log.md` (operational phase artifact). Never silently ignore a user-specified persona.
+
+---
+
+## Adversarial Review Iteration Playbook
+
+The adversarial gate fires at the RESEARCH to FRAMEWORK boundary when the variant gate cell is `REQ` or `OPT` (with `--adversarial=true`). The gate runner dispatches the `adversarial-reviewer` agent in a loop with a HARD CAP of 3 iterations per **ADR-021**.
+
+### Iteration Protocol
+
+**Iteration 1 — Full critique**
+
+- Dispatch `adversarial-reviewer` with `persona_id` and the `research-report.md` artifact
+- Expect 5-10 findings across severity levels (`high`, `medium`, `low`)
+- Store iteration artifacts: `methodology-research-v1.md`, `adversarial-review-{persona}-v1.md`
+- If `severity:high == 0` on iteration 1 output, gate passes immediately (early exit)
+
+**Iteration 2 — Revised artifact, focused critique**
+
+- `methodology-researcher` revises research report addressing all `high` and `medium` findings
+- Re-dispatch `adversarial-reviewer` with revised artifact (`methodology-research-v2.md`)
+- Expect 1-3 findings remaining, concentrated on edge cases
+- Store: `methodology-research-v2.md`, `adversarial-review-{persona}-v2.md`
+- If `severity:high == 0`, gate passes (common exit point)
+
+**Iteration 3 — Final critique**
+
+- Second revision from `methodology-researcher` addressing remaining findings
+- Re-dispatch `adversarial-reviewer` for final pass
+- Store: `methodology-research-v3.md`, `adversarial-review-{persona}-v3.md`
+- If `severity:high > 0` after iteration 3: BLOCKED — do not proceed silently
+
+**BLOCKED state**
+
+Present user escalation:
+
+```
+Gate BLOCKED after 3 iterations.
+Remaining high-severity findings:
+  {list findings from adversarial-review-v3.md}
+
+Options:
+  --force-pass  Accept research report as-is; override logged in audit trail
+  --abort       Cancel workflow; no further phases dispatch
+```
+
+Wait for explicit user response. Never auto-select `--force-pass`.
+
+### Artifact Audit Trail
+
+Every iteration artifact is persisted in MinIO via `mcp__orchestrator-extended__artifactStore` before the next iteration begins:
+
+| Artifact | artifact_kind | When stored |
+|---|---|---|
+| `methodology-research-v{n}.md` | `phase-artifact` | After each revision |
+| `adversarial-review-{persona}-v{n}.md` | `adversarial_review` | After each reviewer dispatch |
+| `adversarial-review-log.md` | `gate-log` | At gate resolution (pass or force-pass) |
+
+The `adversarial-review-log.md` records all iterations, each finding's resolution, and the convergence outcome. It is omitted from the artifact set when the gate cell is `SKIP`.
+
+---
+
+## Workflow Lifecycle Reference
+
+PME executes five phases in strict order. No phase may be skipped outside a declared variant cell of `SKIP` or `PARTIAL`. Checkpoints are written at every phase exit to support multi-session resumption (RFC-032 §3.5).
+
+### Phase Sequence
+
+```
+DISCOVERY --> RESEARCH [+adversarial gate] --> FRAMEWORK --> OPERATIONAL --> DELIVER
+```
+
+### Per-Variant Phase Matrix (RFC-032 §5)
+
+| Phase / Gate | consultoria-externa | consultoria-interna | software-handoff | cirurgico |
+|---|---|---|---|---|
+| DISCOVERY | EXEC | EXEC | EXEC | EXEC |
+| RESEARCH | EXEC | EXEC <!-- AMENDED 2026-05-12 (S183) --> | EXEC | SKIP |
+| Gate: adversarial | REQ | OPT | OPT | SKIP |
+| FRAMEWORK | EXEC | EXEC | EXEC | SKIP |
+| OPERATIONAL | EXEC | EXEC | EXEC | PARTIAL (scope_brief + patch_summary) |
+| DELIVER | EXEC | EXEC | EXEC | EXEC |
+
+`REQ` = gate always runs; `OPT` = opt-in via `--adversarial=true` (default OFF); `SKIP` = gate bypassed.
+Source: RFC-032 §5 matrix. Variant mechanic: ADR-020 + RFC-031.
+
+### Canonical Artifacts by Phase (RFC-032 §8)
+
+| Phase | Primary artifacts |
+|---|---|
+| DISCOVERY | `discovery-brief.md`, `stakeholder-map.md`, `discovery-inputs.json` |
+| RESEARCH | `methodology-research.md`, `evidence-pack.md`, `sources.bib`, `adversarial-review-log.md` (when gate not SKIP) |
+| FRAMEWORK | `framework-doc.md`, `playbook.md`, `framework-summary.md`, `framework-exhibits/` |
+| OPERATIONAL | `operational-runbook.md`, `kpi-set.md`, `risk-register.md`, `implementation-checklist.md`, `persona-selection-log.md` |
+| DELIVER | `deliverables-list.md`, `final-deck.pdf`, `closure-report.md`, `handoff-brief.md` (software-handoff only) |
+
+All artifacts travel through `mcp__orchestrator-extended__artifactStore` / `artifactRetrieve`. Direct access to `.orchestrator/artifacts/*` is forbidden per Universal Charter §4.
+
+### Multi-Session Resumption
+
+PME workflows are long-lived by design. On session resume:
+
+1. Call `getStatus({ workflowId })` to read current phase, variant, and stored artifacts
+2. Retrieve previous phase artifacts via `artifactRetrieve` — do not require user to re-specify
+3. Continue from the current phase; the variant is immutable (do not re-run pre-flight)
+
+---
+
+## Common Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Choosing `consultoria-externa` for internal teams | Adversarial gate `REQ` creates unnecessary friction for teams with existing domain knowledge | Use `consultoria-interna`; gate is `OPT` and defaults OFF |
+| Skipping persona consultation | Research critique is generic, not stakeholder-lens-calibrated; findings lack specificity | Select persona from `.claude/personas/INDEX.md` before dispatching `adversarial-reviewer`; log selection in `persona-selection-log.md` |
+| Treating iteration 3 BLOCKED as failure | Operator abandons gate or bypasses silently | BLOCKED is a feature: it surfaces high-signal escalation points. Present user options (`--force-pass` or `--abort`), log the outcome, never auto-bypass |
+| Forgetting `cirurgico` PARTIAL artifact declarations | `PreFlightValidator` raises `PARTIAL_MISSING_ARTIFACTS` (RFC-032 §9); workflow does not start | `cirurgico` discovery produces only `scope_brief.md`; deliver produces only `patch_summary.md` — ensure variant definition lists these slugs in the `artifacts` cell |
+| Advancing FRAMEWORK before gate resolves | Research defects propagate into framework; methodology errors compound | Gate runner must receive explicit pass (convergence or `--force-pass`) before `advancePhase` is called on RESEARCH |
+| Re-running pre-flight on session resume | Fails because `framework` artifact_ref required by `cirurgico` was resolved in prior session | On resume, read current phase from `getStatus` and skip pre-flight; variant and inputs are stored in PostgreSQL |
+
+---
+
+## Audit Trail Requirements
+
+Every PME phase and gate interaction MUST be persisted. Missing MinIO records are not recoverable at container restart and break the workflow audit graph.
+
+### Required artifact_kind values
+
+| Event | artifact_kind | artifactStore call |
+|---|---|---|
+| Phase output (any phase) | `phase-artifact` | After phase agent completes, before `advancePhase` |
+| Adversarial reviewer dispatch | `adversarial_review` | After each reviewer iteration |
+| Gate resolution (pass or force-pass) | `gate-log` | At gate exit |
+| Final deliverable pack | `deliverable` | At DELIVER phase completion |
+
+### Call pattern (deferred-load, TD-098)
+
+```
+# Step 1: load schema if not yet available
+ToolSearch("select:mcp__orchestrator-extended__artifactStore")
+
+# Step 2: store artifact
+mcp__orchestrator-extended__artifactStore({
+  workflowId: "<workflow-id>",
+  phase: "<pme-phase-name>",   # discovery | research | framework | operational | deliver
+  type: "<artifact_kind>",
+  content: "<artifact content>",
+  metadata: {
+    artifact_kind: "<phase-artifact|adversarial_review|gate-log|deliverable>",
+    variant: "<active-variant>",
+    persona_id: "<persona if applicable>",
+    iteration: <iteration-number if applicable>
+  }
+})
+```
+
+---
+
+## Architectural References
+
+This skill operationalises three architectural decisions. When in doubt, consult the source:
+
+- **ADR-020** (`project-guidelines/adrs/ADR-020-WORKFLOW-MODE-PARAMETER-AS-UNIVERSAL-PATTERN.md`) — establishes `variant` as a first-class, universal workflow parameter; defines `EXEC / SKIP / PARTIAL / REQ / OPT` vocabulary
+- **ADR-021** (`project-guidelines/adrs/ADR-021-ADVERSARIAL-REVIEW-AS-GATE-NOT-PHASE.md`) — mandates adversarial review as a gate row (not a phase), defines the 3-iteration cap and `REQ / OPT / SKIP` gate cell semantics, and reserves the `--force-pass` escape hatch
+- **RFC-032** (`project-guidelines/rfcs/RFC-032-PROJECT-MANAGEMENT-ENTERPRISE-WORKFLOW.md`) — full PME workflow definition: 5 phases, 4 variants, variant matrix (§5), adversarial gate protocol (§6), agent stubs (§7), artifact lifecycle (§8), error codes (§9), and testing strategy (§10)
+- **RFC-031** (`project-guidelines/rfcs/RFC-031-WORKFLOW-MODE-PARAMETER-CONDITIONAL-PHASE-EXECUTION.md`) — framework-wide variant mechanic implementation (JSON Schema, runtime resolution, pre-flight validation, phase-skip enforcement) that PME consumes as a first-class consumer

package/skills/receiving-code-review/SKILL.md

@@ -0,0 +1,186 @@
+---
+name: receiving-code-review
+description: "Use when receiving code review feedback, before implementing suggestions — requires technical rigor and verification, not performative agreement or blind implementation."
+triggers:
+  - "When a PR reviewer leaves comments"
+  - "When the user asks you to address review feedback"
+  - "When external review feedback arrives"
+  - "Before implementing any review suggestion"
+---
+
+# Code Review Reception
+
+## Overview
+
+Code review requires technical evaluation, not emotional performance.
+
+**Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort.
+
+## The Response Pattern
+
+```
+WHEN receiving code review feedback:
+
+1. READ: Complete feedback without reacting
+2. UNDERSTAND: Restate requirement in own words (or ask)
+3. VERIFY: Check against codebase reality
+4. EVALUATE: Technically sound for THIS codebase?
+5. RESPOND: Technical acknowledgment or reasoned pushback
+6. IMPLEMENT: One item at a time, test each
+```
+
+## Forbidden Responses
+
+**NEVER:**
+- "You're absolutely right!" (explicit CLAUDE.md violation)
+- "Great point!" / "Excellent feedback!" (performative)
+- "Let me implement that now" (before verification)
+
+**INSTEAD:**
+- Restate the technical requirement
+- Ask clarifying questions
+- Push back with technical reasoning if wrong
+- Just start working (actions > words)
+
+## Handling Unclear Feedback
+
+```
+IF any item is unclear:
+  STOP - do not implement anything yet
+  ASK for clarification on unclear items
+
+WHY: Items may be related. Partial understanding = wrong implementation.
+```
+
+**Example:**
+```
+User: "Fix 1-6"
+You understand 1,2,3,6. Unclear on 4,5.
+
+WRONG: Implement 1,2,3,6 now, ask about 4,5 later
+RIGHT: "I understand items 1,2,3,6. Need clarification on 4 and 5 before proceeding."
+```
+
+## Source-Specific Handling
+
+### From the User (trusted)
+- **Trusted** — implement after understanding
+- **Still ask** if scope unclear
+- **No performative agreement**
+- **Skip to action** or technical acknowledgment
+
+### From External Reviewers
+```
+BEFORE implementing:
+  1. Check: Technically correct for THIS codebase?
+  2. Check: Breaks existing functionality?
+  3. Check: Reason for current implementation?
+  4. Check: Works on all platforms/versions?
+  5. Check: Does reviewer understand full context?
+
+IF suggestion seems wrong:
+  Push back with technical reasoning
+
+IF can't easily verify:
+  Say so: "I can't verify this without [X]. Should I [investigate/ask/proceed]?"
+
+IF conflicts with the user's prior architectural decisions:
+  Stop and discuss with the user first
+```
+
+**Rule:** "External feedback — be skeptical, but check carefully"
+
+## YAGNI Check for "Professional" Features
+
+```
+IF reviewer suggests "implementing properly":
+  grep codebase for actual usage
+
+  IF unused: "This endpoint isn't called. Remove it (YAGNI)?"
+  IF used: Then implement properly
+```
+
+**Rule:** "You and reviewer both report to me. If we don't need this feature, don't add it."
+
+## Implementation Order
+
+```
+FOR multi-item feedback:
+  1. Clarify anything unclear FIRST
+  2. Then implement in this order:
+     - Blocking issues (breaks, security)
+     - Simple fixes (typos, imports)
+     - Complex fixes (refactoring, logic)
+  3. Test each fix individually
+  4. Verify no regressions
+```
+
+## When To Push Back
+
+Push back when:
+- Suggestion breaks existing functionality
+- Reviewer lacks full context
+- Violates YAGNI (unused feature)
+- Technically incorrect for this stack
+- Legacy/compatibility reasons exist
+- Conflicts with the user's architectural decisions
+
+**How to push back:**
+- Use technical reasoning, not defensiveness
+- Ask specific questions
+- Reference working tests/code
+- Involve the user if architectural
+
+## Acknowledging Correct Feedback
+
+When feedback IS correct:
+```
+"Fixed. [Brief description of what changed]"
+"Good catch — [specific issue]. Fixed in [location]."
+[Just fix it and show in the code]
+
+NOT: "You're absolutely right!"
+NOT: "Great point!"
+NOT: "Thanks for catching that!"
+NOT: ANY gratitude expression
+```
+
+**Why no thanks:** Actions speak. Just fix it. The code itself shows you heard the feedback.
+
+## Gracefully Correcting Your Pushback
+
+If you pushed back and were wrong:
+```
+"You were right — I checked [X] and it does [Y]. Implementing now."
+"Verified this and you're correct. My initial understanding was wrong because [reason]. Fixing."
+
+NOT: Long apology
+NOT: Defending why you pushed back
+NOT: Over-explaining
+```
+
+State the correction factually and move on.
+
+## Common Mistakes
+
+| Mistake | Fix |
+|---------|-----|
+| Performative agreement | State requirement or just act |
+| Blind implementation | Verify against codebase first |
+| Batch without testing | One at a time, test each |
+| Assuming reviewer is right | Check if breaks things |
+| Avoiding pushback | Technical correctness > comfort |
+| Partial implementation | Clarify all items first |
+| Can't verify, proceed anyway | State limitation, ask for direction |
+
+## GitHub Thread Replies
+
+When replying to inline review comments on GitHub, reply in the comment thread (`gh api repos/{owner}/{repo}/pulls/{pr}/comments/{id}/replies`), not as a top-level PR comment.
+
+## The Bottom Line
+
+**External feedback = suggestions to evaluate, not orders to follow.**
+
+Verify. Question. Then implement.
+
+No performative agreement. Technical rigor always.

package/skills/release/SKILL.md

@@ -250,6 +250,46 @@ git commit -m "chore: sync definitions manifest checksums"
 
 **REGRA:** Nunca faca release com definitions alteradas sem manifest actualizado. Isso causa uma release extra desnecessaria (como aconteceu no v3.9.3 -> v3.9.4).
 
+## Secret Audit (Quarterly — TD-S188-003)
+
+Release CI/CD depende de 3 secrets em `.github/workflows/release.yml`:
+
+| Secret | Purpose | Notas |
+|---|---|---|
+| `NPM_TOKEN` | Publica `@orchestrator-claude/*` packages | type=Automation (bypassa 2FA em CI). 404 PUT durante publish = token issue, NÃO scope-missing (S186 hard rule). |
+| `DOCKER_PASSWORD` | Login Docker Hub (user `cmac01`) | NÃO confundir com `DOCKER_TOKEN`. S186 release quebrou porque release.yml linhas 40+83 referenciavam o nome errado. Cross-reference `grep DOCKER_ release.yml` antes de instruir user a regerar secret. |
+| `DOCKER_USERNAME` | Docker Hub user identifier | Raramente roda; muda só se conta migrar. |
+
+**Hard rule:** Antes de QUALQUER release, audite idade dos 3 secrets críticos. Se algum > 90 dias, **bloqueie release** e rotacione primeiro.
+
+### Comando de audit
+
+```bash
+# Lista timestamp + idade em dias dos 3 secrets críticos do release.yml
+gh secret list --json name,updatedAt | jq -r \
+  '.[] | select(.name | IN("NPM_TOKEN","DOCKER_PASSWORD","DOCKER_USERNAME")) |
+   "\(.name)\tupdated \(.updatedAt)\tage \(((now - (.updatedAt | fromdateiso8601)) / 86400 | floor))d"'
+```
+
+Output esperado (idade < 90d em todos):
+```
+DOCKER_PASSWORD updated 2026-02-10T...   age 92d   ← ROTACIONAR
+DOCKER_USERNAME updated 2025-08-15T...   age 271d  ← stable, mas confirme válido
+NPM_TOKEN       updated 2026-04-20T...   age 23d   ← OK
+```
+
+### Rotação de secret expirante
+
+1. **Pause release** — NÃO execute `release.sh`.
+2. Regere o secret na origem:
+   - `NPM_TOKEN`: https://www.npmjs.com/settings/<user>/tokens (Generate New → Automation type)
+   - `DOCKER_PASSWORD`: Docker Hub → Account Settings → Security → New Access Token
+3. Atualize no GitHub: `gh secret set <NAME> --body "<new-value>"` (executar do CWD repo)
+4. Re-rode comando de audit acima — confirmar `updatedAt` fresco (idade < 1d).
+5. Proceda com release.
+
+**Histórico:** S186 release pipeline broke porque DOCKER_PASSWORD estava ausente (incorretamente referenciado como `DOCKER_TOKEN` em `release.yml` linhas 40+83). Aprendizagem capturada em hard rules S185→S188 carryover (BACKLOG).
+
 ## Checklist Pre-Release
 
 - [ ] CHANGELOG.md atualizado com todas as mudancas
@@ -259,3 +299,4 @@ git commit -m "chore: sync definitions manifest checksums"
 - [ ] Na branch main
 - [ ] Dry-run executado e revisado
 - [ ] Definitions manifest sincronizado (se houve alteracao em definitions)
+- [ ] **Secret audit executado** — nenhum dos 3 secrets críticos (`NPM_TOKEN`, `DOCKER_PASSWORD`, `DOCKER_USERNAME`) > 90 dias (ver seção "Secret Audit")