@orchestrator-claude/definitions 3.33.0 → 3.34.0

package/skills/orchestrator/SKILL.md

@@ -63,6 +63,20 @@ If no variant is set (or variant resolves to `"full"`), all phases execute norma
 | implement | `implementer` | code + tests |
 | review | `reviewer` | review feedback |
 
+#### 2c.0 Branch-Before-Dispatch precondition (TD-171) — MANDATORY before dispatching a committing agent
+
+Before dispatching **any committing agent** (one whose tool list holds `mcp__orchestrator-tools__createCheckpoint` — see §2c.1 for the exact set), the orchestrator MUST first ensure the working tree is on a **non-protected feature branch**:
+
+```
+current=$(git rev-parse --abbrev-ref HEAD)
+# if current is main/master → create/switch to a feature branch FIRST
+git checkout -b <type>-<sN>-<slug>   # e.g. fix-s290-foo, td-171-branch-before-dispatch
+```
+
+**Why (root cause of the S289 breach `4f1f4f37`):** committing agents may make **local** checkpoint commits for granular revertability. `agent-git-guard` (TD-169) blocks push/merge but intentionally **allows** local commit — so if the orchestrator dispatches while sitting on `main`, the agent's local commit lands **directly on the protected branch**. Branch-before-dispatch contains those commits on a feature branch; only the orchestrator pushes, and only **after** its independent assert.
+
+**Enforcement backstop:** the `pre-agent-dispatch` hook (PreToolUse[Agent]) emits a non-blocking `[BRANCH-BEFORE-DISPATCH][TD-171]` alert when a committing agent is dispatched on a protected branch. The alert is a reminder, not a guarantee — **the orchestrator owns the branch decision**. Single branch authority = orchestrator; dispatched agents do NOT open their own branch (and cannot push — agent-git-guard).
+
 **Dispatch template:**
 
 ```
@@ -83,22 +97,58 @@ Sub-agents MUST persist artifacts to MinIO via `artifactStore` (universal rule,
 
 <!-- TODO S182 (OQ-4): per-phase agent override (.phases[n].agent) deferred — S182 will resolve permissive vs registry-validated vs KnownAgent-enum strategy after agent list complete -->
 
-#### 2c.1 Implementer-specific dispatch addenda (TD-S188-002)
+#### 2c.1 Checkpoint + Commit Policy dispatch addenda (TD-S188-002 + TD-S192-003)
+
+**Scope (TD-S192-003 amendment; set re-verified TD-171/S290):** this block applies to **any agent whose tool list includes `mcp__orchestrator-tools__createCheckpoint`**. As of **S290 the ground-truth set (grep `createCheckpoint` over `.claude/agents/*.md`) is the 7 agents**: `implementer`, `azure-devops-engineer`, `presentation-engineer`, `operational-artifact-builder`, `cicd-platform-engineer`, `python-data-engineer`, `frontend-engineer`. (The earlier S195 list was stale — it named `methodology-researcher`, which no longer holds the tool, and omitted `cicd-platform-engineer` / `python-data-engineer` / `frontend-engineer`, added later.) **Keep this set in sync with `COMMITTING_AGENTS` in `.claude/hooks/pre-agent-dispatch.ts`** (the branch-before-dispatch hook, §2c.0) — both derive from the same `createCheckpoint`-holder ground truth; when an agent gains/loses `createCheckpoint`, update both. The earlier version of this section was implementer-only; subsequent sessions (S192 PME phase 2, S194 bug_fix, S195 lint sweep) confirmed the same `createCheckpoint=git-commit` conflation appears across other agents that hold the tool — making the rule agent-agnostic from S195 forward.
+
+When dispatching any of those agents, the generic template above is **insufficient**. The S188 implement phase originally surfaced the ambiguity: the implementer interpreted `createCheckpoint` as requiring a git commit beforehand, producing 4 unsolicited commits per dispatch (commit prefix also leaked from BACKLOG context: `feat(s186)` instead of `feat(s188)`). Empirical evidence preserved across sessions:
 
-When dispatching `implementer` (phase=`implement`), the generic template above is **insufficient**. The S188 implement phase surfaced an ambiguity: the implementer interpreted `createCheckpoint` as requiring a git commit beforehand, producing 4 unsolicited commits per dispatch (commit prefix also leaked from BACKLOG context: `feat(s186)` instead of `feat(s188)`). To prevent recurrence, append the following **commit policy block** to every implementer dispatch prompt:
+- **S188** (`feat(s186)` leak in implementer commits)
+- **S192 phase 2** (methodology-researcher + operational-artifact-builder both invoked createCheckpoint inferring git-commit requirement; see memory `subagent_path_fallback_artifactretrieve_gap_s192phase2`)
+- **S194** commit `e5635f71` `[orchestrator] tasks: Auto-checkpoint after tasks phase` — auto-commit hook fired AFTER `advancePhase("implement")`, captured implement-phase work, but commit msg said `tasks phase` (hard rule (s): hook reads `currentPhase` post-advance → drifts one phase ahead of captured work). See memory `createcheckpoint_hook_phase_label_drift_s194`.
+- **S195** commit `106347d5` `[orchestrator] tasks: Auto-checkpoint after tasks phase` — SAME phase-label drift; commit captured implementer's S195 sweep deletions but msg labels it "tasks". Confirms hard rule (s) is recurring.
+
+To prevent recurrence, append the following **commit policy block** to every dispatch prompt targeting an agent with `createCheckpoint` in its tool list:
 
 ```
 [Commit Policy]
-- createCheckpoint (mcp__orchestrator-tools__createCheckpoint) is a PostgreSQL state snapshot per RFC-012. It is INDEPENDENT of git. You do NOT need to commit before calling it. Calling createCheckpoint with no uncommitted changes is the normal path.
+- createCheckpoint (mcp__orchestrator-tools__createCheckpoint) is a PostgreSQL state snapshot per RFC-012. It is INDEPENDENT of git. You do NOT need to commit before calling it. Calling createCheckpoint with no uncommitted changes is the normal path. createCheckpoint may also trigger an auto-commit hook on the orchestrator side — that hook's commit message is NOT authoritative for phase attribution (hard rule (s) S194/S195: hook reads currentPhase post-advance, drifts one phase ahead). Trust explicit authored commits (`feat|fix|refactor|docs(sN): subject`) for phase attribution in audit/blame archaeology.
 - Commit policy for this dispatch: <one of>
     a) "DO NOT commit — orchestrator owns the closure commit at review gate."
-    b) "Commit per-phase using prefix `<feat|fix|refactor>(s<N>): <subject>` — confirm prefix before commit." (use when implement phase exceeds 80k tokens or spans multiple fases)
-- If you commit, the prefix MUST be: `<feat|fix|refactor>(s<CURRENT_SESSION>):` — do NOT infer from BACKLOG examples or previous session context.
+    b) "Local commit per-phase is OK (granular revertability) using prefix `<feat|fix|refactor>(s<N>): <subject>` — confirm prefix before commit. You are on a dedicated feature branch (the orchestrator branched before dispatching you, §2c.0); commit LOCALLY only." (use when implement/framework/operational/deliver phase exceeds 80k tokens or spans multiple sub-fases)
+- **Push policy (local-commit-YES / push-NO, TD-171):** NEVER `git push`, `git merge`, or `gh pr merge`. Push/merge to a remote is owned EXCLUSIVELY by the main orchestrator, performed only AFTER its independent assert. This is enforced — `agent-git-guard` (TD-169) hard-denies sub-agent push/merge; your local commits are contained on the feature branch the orchestrator prepared (§2c.0). Return your work in your report; the orchestrator reviews, then pushes.
+- If you commit, the prefix MUST be: `<feat|fix|refactor|docs>(s<CURRENT_SESSION>):` — do NOT infer from BACKLOG examples or previous session context.
+```
+
+Substitute `<CURRENT_SESSION>` with the active session number (e.g., `s195`) and pick **exactly one** of (a) or (b) — never leave both options visible. The block goes **after** `[Task]` and **before** the artifactStore instruction.
+
+If the orchestrator (main) wants to own all commits, prefer option (a) + call `createCheckpoint` itself after the phase completes — do NOT delegate that call to the dispatched agent.
+
+#### 2c.2 Verify-Before-Assert dispatch addenda (TD-S192-003)
+
+A second cross-cutting concern surfaced from S192 + S193 + S194 + S195 dispatches: sub-agents assert scope coverage from upstream artifact references (file paths, line numbers, persona IDs, artifact IDs) **without verifying empirically**, producing false-positives that cost downstream cycles.
+
+Documented instances:
+- **S192 phase 2** — sub-agent path-fallback gap (TD-S192-002): methodology-researcher cited `.claude/personas/cfo-conservador.md` from BACKLOG context but never confirmed file existed in working tree at dispatch time; persona was actually present but the assumption pattern was visible. See memory `subagent_path_fallback_artifactretrieve_gap_s192phase2`.
+- **S193** — `persona_cfo_conservador_file_absent_s191b` memory documents an instance where the assumption *did* break (persona referenced but file absent in workflow context).
+- **S194** — line range estimates from BACKLOG (`part2.test.ts:40-95`) were off by 13 lines (actual block ended at line 82, not 95); implementer caught this via Read empirically.
+- **S195** — implementer applied verify-before-assert correctly on TD-S191-005: BACKLOG estimated 10 lint errors, real count was 352. Implementer stopped + deferred to TD-S195-001 rather than improvise. **Canonical positive example.**
+
+To prevent recurrence, append the following **verify-before-assert block** to every dispatch prompt:
+
 ```
+[Verify-Before-Assert]
+Before asserting any file path, line range, persona ID, artifact ID, or other concrete entity cited in upstream context (BACKLOG, previous artifact, session memory), VERIFY empirically:
+- File path → confirm via Read or Glob that the file exists with expected content
+- Line range → READ the file, confirm structure matches (e.g., describe block boundaries)
+- Persona ID → load `.claude/personas/<id>.md` and confirm the file is present + contains expected fields
+- Artifact ID → call artifactRetrieve and confirm payload structure
+- Lint/test counts → run the actual command (`bun lint`, `bun test`) — do not trust BACKLOG estimates
 
-Substitute `<CURRENT_SESSION>` with the active session number (e.g., `s189`) and pick **exactly one** of (a) or (b) — never leave both options visible. The block goes **after** `[Task]` and **before** the artifactStore instruction.
+If empirical verification diverges from the cited assumption (e.g., line range off, file absent, count larger than estimated), STOP and report the divergence in the implementation-report (or equivalent artifact for non-implementer agents). DO NOT improvise to fit the cited assumption — divergence is signal, not noise. Better to defer scope via a new TD than to silently violate the dispatch contract.
+```
 
-If the orchestrator (main) wants to own all commits, prefer option (a) + call `createCheckpoint` itself after the implement phase completes — do NOT delegate that call to implementer.
+The block goes **after** `[Task]` and **before** `[Commit Policy]`. It applies to every agent dispatch, not just those with `createCheckpoint`.
 
 ### 2d. Gate Check
 
@@ -123,6 +173,22 @@ mcp__orchestrator-tools__advancePhase({ workflowId: "..." })
 
 Loop back to 2a for the next phase.
 
+### 2d.1 Post-Implement Signal → docs-guardian dispatch (RFC-034 / System A)
+
+When you `advancePhase` out of `implement` (the workflow enters `review`), the `post-implement.ts` hook fires on `PostToolUse[mcp__orchestrator-tools__advancePhase]` and injects an orchestrator signal:
+
+```
+[ORCHESTRATOR] IMPLEMENT completed for <workflowId> — dispatch the docs-guardian sub-agent before proceeding past the IMPLEMENT gate.
+```
+
+On seeing that signal, dispatch `docs-guardian` (documentation compliance vs `DOCS-CONSTITUTION`) **before** running the review gate / closing the workflow:
+
+```
+Agent(subagent_type: "docs-guardian", prompt: "[Workflow] ... Review documentation compliance for the changes just implemented; report deltas + archival candidates vs DOCS-CONSTITUTION.")
+```
+
+**Why a signal, not direct hook action:** a hook (a node/bash script) cannot spawn a Claude sub-agent in the main-as-orchestrator model (RFC-022) — `post-implement.ts` is a *deterministic trigger* that emits the signal; **the orchestrator owns the dispatch**. The detection is deterministic: the hook reads the live workflow state and emits only when the post-advance `currentPhase === 'review'` (review is reached only by leaving `implement`). Fail-open: if the API is down or env is unset the hook emits nothing — so if you expected the signal and it is absent, dispatch `docs-guardian` anyway as part of review. Skin: MUST rule #5.
+
 ## Step 3 — Complete Workflow
 
 After all phases are done:
@@ -150,6 +216,26 @@ Load these for phase-specific guidance when needed:
 | `/project-conventions` | Before implementation (stack-agnostic; stack-specific context via StackContextBuilder) |
 | `/checkpoint-protocol` | After completing task groups |
 
+## Convergence & Quality Instrumentation (orchestrator self-direction)
+
+Quando uma **assinatura de falha recorrente** aparece, **não repita o caminho que já falhou** — leia o sinal e escolha a alavanca. Tudo aqui é pure-use e preserva `main-as-baton` (RFC-022/ADR-019). A CI crônica (TD-143) é **só mais uma linha**.
+
+| Sinal que você observa | Leitura provável | Alavanca (não repita cego) |
+|---|---|---|
+| **Sub-agent não converge** — specifier/planner re-despachado 2–3× sem passar o gate; adversarial review não baixa `severity:high` | A ambiguidade costuma ser **upstream** (input/requisito), não o agente. Convergência é **limitada**: máx 3 iterações (`feedback_adversarial_reviewer_3_iteration_hard_cap_s183`). | Na 3ª sem convergir, **muda a abordagem**: reframe o input · `/effort xhigh` na re-tentativa · fan-out de N tentativas independentes + síntese (judge-panel) · pivot cirúrgico do main (`m2_pivot_orchestrator_surgical_edit_on_socket_failure_s227`, `bounded_pivot_in_workflow_instead_of_abort_s227e`) · gate ao user. |
+| **"Green" suspeito do implementer** — stub/`expect(true).toBe(true)`, `tsc --noEmit` false-green, comment afirma fix sem guard-code, contagem self-report inflada | Self-report **não é ground-truth**; o gate confiou no relato. (`feedback_trc_frontend_self_report_test_counts_unreliable`, `tsc_noemit_false_green_and_required_field_cascade_seam_s247`, `verify_coverage_metric_independently_not_subagent_selfreport_s233`, `code_comment_claims_fix_without_guard_code_s252`) | **Re-rode os gates você mesmo** (tsc real, `npm run lint` real, vitest com escopo) + reviewer re-roda independente. Contagem = alegação a verificar. Divergência "inflada-mas-verde" também é finding. |
+| **Review acha medium/high DEPOIS da implementação**, recorrente numa área | Defeito caro pego tarde — gate de qualidade só no fim. (`feedback_plan_gate_scope_expansion`, `feedback_staged_dispatch_per_gate_storybook_loop_s268`, `canary_first_gate_for_deck_design_iterations_s267`) | **Shift-left**: front-load adversarial review no gate de plan/spec; staged dispatch por gate; canary-first numa fatia antes do lote. |
+| **CI crônica vermelha / convergência longa** (TD-143) | Problema de **convergência/diagnóstico, não de cobertura** (FEATURE-MATRIX §2); e a premissa do TD pode ser falsa (`feedback_td_premise_can_be_false_positive_verify_before_fixing_s243`). | `/goal "<critério verde>"` como condição de saída + background Bash + Monitor; fan-out workflow read-only **só se** o diagnóstico for amplo; verificar a premissa antes de "consertar". |
+
+### Alavancas (toolbox que a tabela referencia)
+
+- **`/goal`** — condição de saída explícita; **só no main-loop** (nunca sub-agent/workflow-interno; lá dentro `while`/loop-until-dry em JS).
+- **background Bash + Monitor** — comando longo (`gh run watch`, suites) sem travar a sessão (stream, não poll).
+- **Dynamic Workflow fan-out** — N perspectivas/root-causes em paralelo → gate de consenso. Read-only é livre; sub-agent que escreve `src/` ainda bate no `workflow-guard` (Invariante #1). Despachar via `opts.agentType` (honra `model` do frontmatter — probe `wf_b6ec4bc1`); `model` explícito = cinto-de-segurança. **Nunca** `CLAUDE_CODE_SUBAGENT_MODEL` global (sobrescreve frontmatter, quebra a FinOps Matrix).
+- **Agent View `--json`** — poll determinístico de sessions bg (`state`/`waitingFor`/PR-status; coluna PR destaca CI vermelha).
+- **`/effort` (xhigh/ultracode)** — bump de raciocínio na re-tentativa de diagnóstico difícil.
+- **270s heartbeat** — cadência cache-warm pra `/loop`/`ScheduleWakeup` (TTL do prompt-cache = 300s; estudo RUFLO #6).
+
 ## Error Recovery
 
 - **Sub-agent fails** → read the error, fix the issue, re-dispatch.

package/skills/persona-library/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: persona-library
-description: Catalog navigation for `.claude/personas/`. Load when: "find persona", "list personas", "select reviewer persona", "persona by industry", "persona for X industry", "create new persona", or when methodology-researcher / adversarial-reviewer / operational-artifact-builder need persona selection guidance. Provides search/filter/select-for-review primitives + scaffold for new persona authoring.
+description: 'Catalog navigation for `.claude/personas/`. Load when: "find persona", "list personas", "select reviewer persona", "persona by industry", "persona for X industry", "create new persona", or when methodology-researcher / adversarial-reviewer / operational-artifact-builder need persona selection guidance. Provides search/filter/select-for-review primitives + scaffold for new persona authoring.'
 allowed-tools: Read, Grep, Glob, Write
 ---
 

package/skills/project-conventions/SKILL.md

@@ -1,34 +1,57 @@
 ---
 name: project-conventions
-description: Project-wide conventions, patterns, and known gotchas. Loaded by all agents to ensure consistency.
+description: Project patterns, conventions, and known gotchas. Stack-specific conventions are injected via StackContextBuilder at dispatch time.
 ---
 
-## Architecture
-- Clean Architecture: domain → application → infrastructure → presentation
-- TypeScript strict mode (exactOptionalPropertyTypes: true)
-- Vitest for testing, TDD discipline
-- PostgreSQL (OLTP) + Neo4j (Graph) + MinIO (Object Storage)
-
-## DI Patterns (CRITICAL)
-- 'ProjectRepositoryNew' = direct PostgreSQL (returns Project | null)
-- ServiceNames.ProjectRepository = adapter with Result<T> wrapping
-- ALWAYS use 'ProjectRepositoryNew' when consumer expects IProjectRepository
-- Register new services in src/infrastructure/di/container.ts
-
-## Code Patterns
-- Use conditional spread in toDomain() for optional properties
-- KBDocument: mapper inline in repository (no separate Mapper class)
-- Entities generate own IDs via crypto.randomUUID()
-- Definitions are global (no project_id on agent_definitions table)
-
-## Testing
-- Add context: { projectId } to request mocks
-- Set process.env.ENABLE_OBJECT_STORAGE = 'true' for MinIO tests
-- Use describe.skipIf for external service tests (Neo4j, PostgreSQL)
-- UUID IDs: entities generate own — don't pass id to constructors
-
-## What NOT to Do
-- NEVER edit .orchestrator/orchestrator-index.json (deprecated since RFC-012)
-- NEVER store artifacts on filesystem (use MinIO via MCP)
-- NEVER bump versions manually (use /release skill)
-- NEVER read/write orchestrator-index.json for workflow state
+# Project Conventions
+
+## Stack Context
+
+Stack-specific conventions (commands, patterns, architecture rules) are provided in the `[Stack Context]` section of your prompt — injected automatically by the orchestrator based on the detected workspace stack.
+
+If you need deeper guidance on a specific convention topic, use:
+```
+getStackConventions({ pack: "<pack-id-from-context>", topic: "<topic>" })
+```
+
+## Universal Conventions (Stack-Agnostic)
+
+These apply to ALL projects regardless of stack:
+
+### Quality Standards
+- TDD: Write tests BEFORE implementation
+- Coverage: Minimum 80% test coverage
+- SOLID principles: Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, Dependency Inversion
+- Clean Code: Meaningful names, small functions, no magic numbers
+
+### Lint gate scope
+
+When task plans specify a lint verification gate (ruff, eslint, etc.), the default scope MUST cover **both `src/` and `tests/`** (or equivalent test directories) — not src-only.
+
+```bash
+# Python (ruff)
+ruff check src/ tests/
+
+# TypeScript (eslint)
+npx eslint src/ tests/
+```
+
+**Rationale:** src-only scoping masks lint debt landing in test files; subsequent CI runs / next contributors discover it as a fix-up commit window. Origin: S226 wave-3c TD-S226-003 fix-up commit (`8bad8d2`). Promoted from TD-S226-005.
+
+If a task-generator template emits a lint gate, it MUST default to broader scope. Optionally promote to `pre-commit` hook in target repo.
+
+### Git Conventions
+- Conventional Commits: feat/fix/refactor/test/docs/chore prefix
+- Co-Authored-By trailer for AI-assisted commits
+- Atomic commits: one logical change per commit
+
+### Architecture Principles
+- Dependencies point inward (presentation → application → domain)
+- Domain layer has zero external dependencies
+- Ports in application layer, adapters in infrastructure
+- No business logic in presentation layer
+
+### Documentation
+- Code should be self-documenting; comments explain "why" not "what"
+- Public APIs need JSDoc/docstrings
+- Architecture decisions in ADRs

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

@@ -1,6 +1,6 @@
 ---
 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.
+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
 ---