@orchestrator-claude/definitions 3.31.2 → 3.32.0

package/agents/docs-guardian.md

@@ -137,7 +137,7 @@ The Documentation Guardian is a specialized agent responsible for maintaining do
 ```
 
 **When to Use**:
-- As post-IMPLEMENT hook (triggered automatically)
+- As the post-IMPLEMENT step (orchestrator-dispatched on the System-A post-implement signal — RFC-034)
 - For immediate execution when changes are trusted
 - In CI/CD pipelines for automatic documentation updates
 
@@ -248,82 +248,21 @@ The agent uses the `DocsGuardianSkill` which orchestrates:
 - **MisplacedDocsChecker**: Finds docs in wrong locations
 - **ArchiveCandidatesChecker**: Identifies docs to archive
 
-### Post-IMPLEMENT Hook Integration
+### Post-IMPLEMENT Hook Integration (System A — RFC-034)
 
-The docs-guardian agent is automatically triggered after the IMPLEMENT phase completes:
+docs-guardian is dispatched by the **orchestrator** after the IMPLEMENT phase completes, via the System-A hook-signal mechanism — **not** an application-internal executor.
 
-**Configuration** (in PostgreSQL):
-```json
-{
-  "defaultHooks": {
-    "postImplement": {
-      "agent": "docs-guardian",
-      "mode": "auto",
-      "blocking": false,
-      "enabled": true,
-      "scope": "all"
-    }
-  }
-}
-```
-
-**Hook Execution Flow**:
-1. IMPLEMENT phase completes
-2. `WorkflowStateService.advancePhase()` detects transition from "implement"
-3. `HookExecutor.executePostImplementHook()` invoked
-4. Hook configuration loaded from index
-5. Skip conditions evaluated
-6. If enabled and not skipped:
-   - SDKAgentExecutor invokes docs-guardian in auto mode
-   - Checkpoint created
-   - Actions executed
-   - Execution tracked in index
-7. Workflow continues (non-blocking)
-
-**Hook Execution Tracking**:
-```json
-{
-  "hookExecutions": [
-    {
-      "hookType": "postImplement",
-      "workflowId": "wf_123",
-      "timestamp": "2026-01-17T10:00:00Z",
-      "duration": 3500,
-      "status": "success",
-      "result": {
-        "actionsExecuted": 5,
-        "actionsSucceeded": 5,
-        "actionsFailed": 0
-      }
-    }
-  ]
-}
-```
+**Mechanism (RFC-034 / TD-102):**
+1. IMPLEMENT phase completes; the orchestrator calls `advancePhase` and the workflow enters `review`.
+2. The OS-level hook `.claude/hooks/post-implement.ts` fires on `PostToolUse[mcp__orchestrator-tools__advancePhase]`, reads the live workflow state, and — when the post-advance `currentPhase === 'review'` (reached only by leaving `implement`) — emits the orchestrator signal:
+   `[ORCHESTRATOR] IMPLEMENT completed for <workflowId> — dispatch the docs-guardian sub-agent…`
+3. The **orchestrator** (main-as-orchestrator) reads the signal and dispatches docs-guardian as part of the review phase, before closing the workflow.
 
-**Customizing Hook Behavior**:
+**Why the orchestrator dispatches, not the hook:** 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 sub-agent dispatch. The dispatch rule lives in the orchestrator Skin (`.claude/agents/orchestrator.md`, MUST rule #5) and the `/orchestrator` SKILL (§2d.1).
 
-Disable for specific workflow:
-```json
-{
-  "workflows": [{
-    "id": "wf_123",
-    "hooks": {
-      "postImplement": { "enabled": false }
-    }
-  }]
-}
-```
+**Fail-open:** if the API is unavailable or env is unset, the hook emits nothing and never blocks the advance. The orchestrator dispatches docs-guardian during review regardless, so coverage does not depend on the signal firing.
 
-Skip based on conditions:
-```json
-{
-  "workflows": [{
-    "id": "wf_123",
-    "metadata": { "docsImpact": false }
-  }]
-}
-```
-(Hook will be skipped if `skipConditions: ["no-docs-impact"]` is configured)
+> **Historical note (S306, RFC-034 Decision 2):** prior versions documented an application-internal auto-invoke flow — `WorkflowStateService.advancePhase()` → `HookExecutor.executePostImplementHook()` → `SDKAgentExecutor invokes docs-guardian`. That "System B" subsystem was dead code (registered-but-never-resolved, stub-backed: `getHookConfig:()=>null` + a mock agent executor) and was removed completely in S306. The live mechanism is System A as described above.
 
 ## Error Handling
 
@@ -484,9 +423,10 @@ Archive specs/plans/RFCs promptly after implementation
 - **v1.2.1** (RFC-003 Phase 2): Added sync mode with action plan generation
 - **v1.2.2** (RFC-003 Phase 3): Added auto mode and post-IMPLEMENT hook integration
 - **v1.3.0**: Added AGENT-PROMPT-STANDARDS compliance (RFC 2119, severity classification)
+- **v1.4.0** (RFC-034 / TD-102, S307): Post-IMPLEMENT integration migrated from the removed System-B auto-invoke (`HookExecutor`/`WorkflowStateService`) to the System-A hook-signal + orchestrator-dispatch mechanism.
 
 ---
 
 **Generated by**: RFC-003 Phase 3 Implementation
 **Standards Compliance**: AGENT-PROMPT-STANDARDS v1.0
-**Last Updated**: 2026-01-23
+**Last Updated**: 2026-06-25

package/hooks/post-implement.ts

@@ -0,0 +1,88 @@
+/**
+ * post-implement.ts — PostToolUse[mcp__orchestrator-tools__advancePhase] hook
+ * (RFC-034 §5 / TD-102, System-A vehicle)
+ *
+ * Purpose: emit a deterministic orchestrator signal the moment the IMPLEMENT phase
+ * has been completed, so the main-as-orchestrator dispatches the docs-guardian
+ * sub-agent before proceeding past the IMPLEMENT gate. A hook cannot itself spawn a
+ * Claude sub-agent in the main-as-orchestrator model (RFC-022) — it can only signal;
+ * the orchestrator owns the dispatch (see the orchestrator Skin / SKILL dispatch rule).
+ *
+ * Detection rationale (verify-before-assert, S307):
+ *   The MCP advancePhase tool RESPONSE is only `{ success, workflowId }`
+ *   (AdvancePhaseHandler.ts) — it discards the REST controller's `currentPhase` and
+ *   carries NO from/previous phase. At PostToolUse time the advance has already
+ *   committed, so the live workflow's currentPhase is the NEW phase. In the standard
+ *   dev workflow sequence (… -> implement -> review -> complete), 'review' is reached
+ *   ONLY by leaving 'implement'. So post-advance currentPhase === 'review' is the
+ *   available, deterministic proxy for "IMPLEMENT just completed". It fires exactly
+ *   once (a later review -> complete advance lands on 'complete', not 'review').
+ *
+ * Fail-open: any missing env / API error / parse failure -> emit nothing, never throw.
+ * PostToolUse cannot block the tool; emitting no context is the safe no-op.
+ */
+
+import {
+  readStdin,
+  getField,
+  getActiveWorkflow,
+  getWorkflowStatus,
+  outputContext,
+  log,
+} from './lib/api-client.js';
+
+const HOOK = 'POST-IMPLEMENT';
+
+/** The phase entered upon completing IMPLEMENT in the standard dev workflow sequence. */
+const POST_IMPLEMENT_PHASE = 'review';
+
+/**
+ * True when the post-advance phase indicates IMPLEMENT was just completed.
+ * Case-insensitive; empty/unknown phases return false (fail-safe — no signal).
+ */
+function isImplementCompleted(currentPhase: string | null | undefined): boolean {
+  return (currentPhase ?? '').toLowerCase() === POST_IMPLEMENT_PHASE;
+}
+
+/** Builds the orchestrator dispatch signal for a completed IMPLEMENT phase. */
+function buildPostImplementSignal(workflowId: string): string {
+  return [
+    `[ORCHESTRATOR] IMPLEMENT completed for ${workflowId} — dispatch the docs-guardian sub-agent before proceeding past the IMPLEMENT gate.`,
+    `(RFC-034 System-A post-implement signal: docs-guardian checks documentation compliance against the DOCS-CONSTITUTION after implementation.)`,
+  ].join('\n');
+}
+
+async function main(): Promise<void> {
+  const stdin = await readStdin();
+
+  // Defensive: only act on advancePhase (the settings.json matcher already scopes this).
+  const toolName = getField(stdin, 'tool_name') || getField(stdin, 'tool');
+  if (toolName && !toolName.includes('advancePhase')) {
+    return;
+  }
+
+  // Resolve the workflow id: prefer the tool input, else the active workflow.
+  const wfId = getField(stdin, 'tool_input.workflowId') || (await getActiveWorkflow())?.id || '';
+  if (!wfId) {
+    log(HOOK, 'no workflow id resolvable — skip (fail-open)');
+    return;
+  }
+
+  const status = await getWorkflowStatus(wfId);
+  if (!status) {
+    log(HOOK, `no status for workflow ${wfId} — skip (fail-open)`);
+    return;
+  }
+
+  const phase = (status.currentPhase || '').toLowerCase();
+  log(HOOK, `workflow=${wfId} post-advance currentPhase=${phase}`);
+
+  if (!isImplementCompleted(phase)) {
+    return; // not the implement -> review transition
+  }
+
+  log(HOOK, `IMPLEMENT completed for ${wfId} — emitting docs-guardian dispatch signal`);
+  outputContext('PostToolUse', buildPostImplementSignal(wfId));
+}
+
+main().catch(() => process.exit(0));

package/manifest.json

@@ -1,8 +1,8 @@
 {
   "schema": "orchestrator-definitions/v1",
   "namespace": "orchestrator",
-  "version": "3.31.2",
-  "generatedAt": "2026-06-25T14:31:07.105Z",
+  "version": "3.32.0",
+  "generatedAt": "2026-06-25T19:16:00.614Z",
   "definitions": {
     "agents": [
       {
@@ -65,7 +65,7 @@
         "slug": "docs-guardian",
         "file": "agents/docs-guardian.md",
         "version": "1.0.0",
-        "checksum": "sha256:26ace0b39cc85221186bc89cc5041394309f3831021d60ec600afe63dcb883b2",
+        "checksum": "sha256:b9d5b1a102a56f7927d43ccf3cb64332789c61a8c53ad1395bf1d6211d617c01",
         "supersedes": null,
         "metadata": {}
       },
@@ -497,6 +497,14 @@
         "supersedes": null,
         "metadata": {}
       },
+      {
+        "slug": "post-implement",
+        "file": "hooks/post-implement.ts",
+        "version": "1.0.0",
+        "checksum": "sha256:132c474d4e31ff76abaff10032b4389e015b6fe6e44d03becbe98a87bb89bbbd",
+        "supersedes": null,
+        "metadata": {}
+      },
       {
         "slug": "session-start",
         "file": "hooks/session-start.ts",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@orchestrator-claude/definitions",
-  "version": "3.31.2",
+  "version": "3.32.0",
   "description": "Built-in definitions (agents, skills, hooks, workflows, KB seeds) for the Orchestrator ecosystem",
   "type": "module",
   "main": "dist/index.js",