arkaos 2.19.2 → 2.20.0-beta.1

package/VERSION

@@ -1 +1 @@
-2.19.2
+2.20.0-beta.1

package/arka/SKILL.md

@@ -12,10 +12,45 @@ allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
 > **The Operating System for AI Agent Teams**
 > 65 agents. 17 departments. 244+ skills. Multi-runtime. Dashboard. Knowledge RAG.
 
-## ⛔ Enforcement contract (read before responding)
+## ⛔ Mandatory 13-phase flow (NON-NEGOTIABLE)
 
-This overrides every default. If the UserPromptSubmit hook injected a
-`[ARKA:WORKFLOW-REQUIRED]` tag, you MUST, on the first line of your reply:
+Every non-trivial request runs the canonical flow. Full spec:
+`arka/skills/flow/SKILL.md`. Constitution rule: `mandatory-flow`.
+
+```
+1. Input (verbatim)
+2. Get context (profile, repo, git, cwd tag, session digests)
+3. Decide route -> emit [arka:routing] <dept> -> <lead>
+4. Call hierarchy (Tier 0 when strategic/cross-dept/security/financial)
+5. Research (Obsidian + vector DB, cite sources or declare gap)
+6. Call team (dispatch specialists via Agent tool)
+7. Plan with six parallel reviewers:
+     positive analyst / devil's advocate / Q&A / KB research /
+     best-solution validator / pessimistic analyst
+8. Present plan (save to Obsidian + vector DB + ~/.arkaos/plans/)
+9. Wait for EXPLICIT approval (silence is not approval)
+10. TODO list (atomic, ordered, independently verifiable)
+11. Per-todo loop:
+      team call -> complete -> QA (all tests, E2E, Playwright)
+      -> Security review -> Quality Gate (Marta+Eduardo+Francisca, Opus)
+      -> Document (Obsidian + vector DB)
+12. Loop until TODO is exhausted
+13. Detailed summary (what was done, where, how to verify, what is open)
+```
+
+Before every step, emit `[arka:phase:N] <label>` on its own line.
+
+**Trivial bypass** (the only bypass): single-file edit under 10 lines
+with an imperative verb. Emit `[arka:trivial] <reason>` as the first
+line and proceed directly.
+
+No task type, no context, no runtime setting overrides this flow.
+
+## Enforcement contract
+
+If the UserPromptSubmit hook injected `[ARKA:WORKFLOW-REQUIRED]`, or if
+the SessionStart systemMessage shows `[ARKA:MANDATORY-FLOW]`, the flow
+above is the contract. The first non-trivial line of your reply MUST be:
 
 ```
 [arka:routing] <department-slug> -> <lead-agent>

package/arka/skills/flow/SKILL.md

@@ -0,0 +1,160 @@
+---
+name: arka-flow
+description: >
+  ArkaOS canonical mandatory workflow. 13 phases. This is the default
+  execution contract for every user request inside an ArkaOS-managed
+  context. Not optional. Not overridable.
+allowed-tools: [Read, Write, Edit, Bash, Grep, Glob, Agent, WebFetch, WebSearch]
+---
+
+# ArkaOS — Mandatory Workflow
+
+> This flow runs on **every** user request inside an ArkaOS-managed context.
+> There is no "simple mode". There is no "skip the workflow this time".
+> The only exception is a single-file <10-line trivial edit, which may emit
+> `[arka:trivial] <reason>` and bypass. Everything else runs the 13 phases.
+
+## The 13 phases (strict sequence)
+
+### Phase 1 — Input
+Receive the user request verbatim. Do not paraphrase before Phase 2.
+
+### Phase 2 — Get context
+Read the active context. Sources, in order:
+- `~/.arkaos/profile.json` (who, what company, what language)
+- Current working directory + `.claude/CLAUDE.md` + `.claude/rules/`
+- Git branch and recent commits
+- `cwd-changed` tag from the hook (ecosystem, stack, descriptor)
+- Most recent `~/.arkaos/sessions/` digest if present
+
+### Phase 3 — Decide context and route
+State the target department explicitly:
+
+```
+[arka:routing] <department-slug> -> <lead-agent>
+```
+
+Mapping (full list in `arka/SKILL.md`): dev→Paulo, brand→Valentina,
+kb→Clara, mkt→Luna, content→Rafael, landing→Ines, ecom→Ricardo,
+saas→Tiago, sales→Miguel, pm→Carolina, ops→Daniel, strat→Tomas,
+fin→Helena, lead→Rodrigo, org→Sofia, community→Beatriz.
+
+### Phase 4 — Call hierarchy
+Escalate to Tier 0 (C-Suite) for review when the request is strategic,
+cross-department, security-sensitive, or financial. Tier 0 = Marco (CTO),
+Helena (CFO), Sofia (COO), Marta (CQO), Eduardo (Copy Director),
+Francisca (Tech & UX Director). Otherwise, squad lead owns.
+
+### Phase 5 — Understand and research the context
+Query the knowledge base:
+- `mcp__obsidian__search_notes` for prior work on the topic
+- Vector DB semantic search when installed
+- Prior session digests at `~/.arkaos/session-digests/`
+- Relevant Forge plans at `~/.arkaos/plans/`
+
+Cite the sources found. If the KB has nothing and the ask is non-trivial,
+state the gap explicitly and propose filling it.
+
+### Phase 6 — Call team
+Dispatch specialists via the `Agent` tool. The squad lead from Phase 3
+names them. Specialists run in parallel when work is independent.
+
+### Phase 7 — Plan and make the spec
+Run six parallel reviewers on the plan:
+
+| Reviewer | Question it owns |
+|---|---|
+| Positive analyst | Why this solution is the right one |
+| Devil's advocate | Strongest case against the chosen path |
+| Q&A / input collector | What is still unknown and must be answered |
+| Obsidian + DB researcher | What the knowledge base already says |
+| Best-solution validator | Is there a better option we have not tried |
+| Pessimistic analyst | What breaks, at what scale, in what scenario |
+
+Synthesise into a spec. Reference the Conclave (`arka-conclave`) or
+the Forge (`arka-forge`) when complexity warrants.
+
+### Phase 8 — Present the plan
+Save the spec to:
+- Obsidian (`docs/superpowers/specs/` or vault equivalent)
+- Vector DB (when available via cache or KB cache)
+- Session cache at `~/.arkaos/plans/`
+
+Print the plan inline for the user.
+
+### Phase 9 — Wait for approval
+Two branches:
+
+- **Approve** → Phase 10
+- **More input** → loop to Phase 7
+
+Approval must be explicit. Silence is not approval.
+
+### Phase 10 — TODO list
+Break the approved plan into atomic, ordered items. Persist to the
+task tracker. Each item must be independently verifiable.
+
+### Phase 11 — Per-todo loop
+For each item, in order:
+
+1. Organise a call with all team members relevant to that item.
+2. Complete the todo.
+3. **QA** — all tests, end-to-end, Playwright browser tests when the
+   item touches UI, report saved to Obsidian + vector DB + cache.
+   - Fail → back to the todo. Do not advance.
+4. **Security review** — Tier 0 security specialist checks for flaws,
+   injection, missing auth, data exposure.
+   - Fail → back to the todo.
+5. **Quality Gate** — Marta (CQO) orchestrates the right specialists
+   for the area. If a specialist is missing, stop and advise the user
+   to create one via `/arka personas` + provide the knowledge.
+   - Fail → back to the todo.
+6. Document — save the completed work to Obsidian + vector DB.
+7. Next todo.
+
+### Phase 12 — Loop until TODO list is fully done
+Do not skip items. Do not batch QA or Security across multiple
+items — each item runs the full gate chain.
+
+### Phase 13 — Detailed summary
+When the TODO list is exhausted, emit a final summary: what was done,
+where it lives, how to verify, what is open for next time.
+
+## Visibility requirements
+
+Every phase MUST emit a visibility tag the user can see:
+
+```
+[arka:phase:2] get-context
+[arka:phase:3] route -> dev -> Paulo
+[arka:phase:7] plan+6-reviewers
+[arka:phase:11.3] qa -> all pass
+[arka:phase:11.5] quality-gate -> approved
+```
+
+No silent phases. No compound steps.
+
+## Hard no-go list
+
+- No Write / Edit before Phase 7 completes for the affected item.
+- No Agent dispatch before Phase 6.
+- No "pushing to master" without passing Phase 11.4 and 11.5 on every
+  changed item.
+- No `[arka:trivial]` claim when the change spans more than one file or
+  exceeds 10 lines in total.
+- No skipping Phase 9 (approval). The user is the gate, not a hint.
+
+## Related skills
+
+- `/arka-forge` — complexity-aware planning when the request is large.
+- `/arka-conclave` — 20-advisor deliberation for strategic decisions.
+- `/arka-spec` — spec gate for Phase 7.
+- `/arka-quality` — Quality Gate orchestration for Phase 11.5.
+
+## Non-negotiable
+
+The UserPromptSubmit hook classifies every turn. When it injects
+`[ARKA:WORKFLOW-REQUIRED]`, this flow is the contract. The session-start
+hook embeds it as `systemMessage` so it sits at system-prompt priority
+from turn 1. CLAUDE.md references it. Constitution rule
+`mandatory-flow` codifies it. There is no override.

package/config/constitution.yaml

@@ -66,6 +66,24 @@ enforcement_levels:
         rule: "Forge plans must pass critic validation and governance check before approval"
         enforcement: "Plan Critic validates constitution compliance; PostToolUse monitors execution"
 
+      - id: mandatory-flow
+        rule: "Every non-trivial request executes the 13-phase canonical flow defined in arka/skills/flow/SKILL.md. No task type, no context, no runtime setting can opt out. The only bypass is [arka:trivial] for single-file edits under 10 lines."
+        enforcement: "UserPromptSubmit hook classifies the turn; SessionStart systemMessage embeds the flow at system-prompt priority; arka/SKILL.md references it as default; violation is a constitution breach, not a style issue."
+        phases:
+          - "1. Input (verbatim)"
+          - "2. Get context (profile, repo, KB, session digests)"
+          - "3. Decide context and route ([arka:routing] tag)"
+          - "4. Call hierarchy (Tier 0 when strategic/cross-dept)"
+          - "5. Understand and research (Obsidian + vector DB)"
+          - "6. Call team (squad + specialists via Agent)"
+          - "7. Plan with six parallel reviewers"
+          - "8. Present plan (save to Obsidian + vector DB + cache)"
+          - "9. Wait for explicit approval"
+          - "10. TODO list"
+          - "11. Per-todo loop: team call -> complete -> QA -> Security -> Quality Gate -> Document"
+          - "12. Loop until TODO exhausted"
+          - "13. Detailed summary"
+
   quality_gate:
     description: "Mandatory pre-delivery review. Nothing ships without APPROVED verdict."
     trigger: "After the last execution phase, before delivery to user"

package/config/hooks/_lib/workflow-classifier.sh

@@ -0,0 +1,95 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS v2 — Shared Workflow Classifier
+#
+# Decides whether a user prompt triggers the mandatory 13-phase flow.
+# Used by: user-prompt-submit.sh, pre-tool-use.sh, stop.sh.
+#
+# Contract:
+#   arka_wf_classify "<prompt text>"  → echoes "true" or "false", exits 0.
+#   arka_wf_mark_required "<session_id>"  → writes marker file.
+#   arka_wf_is_required "<session_id>"  → exits 0 if required, 1 otherwise.
+#   arka_wf_clear_required "<session_id>"  → removes marker file.
+#
+# Markers live under /tmp/arkaos-wf-required/<session_id>.
+# Python path for mark/clear: delegates to flow_enforcer.py when available,
+# otherwise falls back to touching the marker file directly.
+# ============================================================================
+
+ARKA_WF_REQUIRED_DIR="${ARKA_WF_REQUIRED_DIR:-/tmp/arkaos-wf-required}"
+
+# Reject any session_id outside [A-Za-z0-9._-]{1,128}. Protects the marker
+# directory from path-traversal writes (CWE-22). Must stay in sync with
+# core/workflow/flow_enforcer.py::_safe_session_id.
+arka_wf_safe_session_id() {
+  local session_id="${1:-}"
+  [ -z "$session_id" ] && return 1
+  [ ${#session_id} -gt 128 ] && return 1
+  case "$session_id" in
+    *[!A-Za-z0-9._-]*) return 1 ;;
+  esac
+  return 0
+}
+
+# Verb + noun patterns shared with the original inline classifier in
+# user-prompt-submit.sh. Keep in sync when adding new intent verbs.
+ARKA_WF_VERB_PATTERN='(criar?|crie[ms]?|cria[mr]?|adicionar?|adiciona[mr]?|implementar?|implementa[mr]?|desenvolver?|desenvolve[mr]?|construir?|constru[ií]a?[mr]?|fazer?|faz[ae][mr]?|refactor(izar?)?|corrigir?|corrige[mr]?|consertar?|conserta[mr]?|create[sd]?|creating|build(s|ing)?|add(s|ed|ing)?|implement(s|ed|ing)?|develop(s|ed|ing)?|fix(es|ed|ing)?|refactor(s|ed|ing)?|make[sd]?|making)'
+
+# Classify: returns "true" if the prompt looks like a creation/
+# implementation/modification request, "false" otherwise.
+# Skips: explicit slash commands (already routed) and bang shells.
+arka_wf_classify() {
+  local text="${1:-}"
+  [ -z "$text" ] && { echo "false"; return 0; }
+
+  local first_char
+  first_char=$(printf '%s' "$text" | head -c 1)
+  if [ "$first_char" = "/" ] || [ "$first_char" = "!" ]; then
+    echo "false"
+    return 0
+  fi
+
+  if echo "$text" | grep -qiE "\b${ARKA_WF_VERB_PATTERN}\b"; then
+    echo "true"
+  else
+    echo "false"
+  fi
+}
+
+# Mark that the flow is required for this session. Safe no-op if session_id
+# is empty or fails the allowlist check.
+arka_wf_mark_required() {
+  local session_id="${1:-}"
+  arka_wf_safe_session_id "$session_id" || return 0
+  mkdir -p "$ARKA_WF_REQUIRED_DIR" 2>/dev/null
+  date -u +"%Y-%m-%dT%H:%M:%SZ" > "$ARKA_WF_REQUIRED_DIR/$session_id" 2>/dev/null
+}
+
+# Test whether flow is required. Exit code 0 = required, 1 = not required.
+arka_wf_is_required() {
+  local session_id="${1:-}"
+  arka_wf_safe_session_id "$session_id" || return 1
+  [ -f "$ARKA_WF_REQUIRED_DIR/$session_id" ]
+}
+
+# Clear the requirement marker. Safe no-op if absent or unsafe.
+arka_wf_clear_required() {
+  local session_id="${1:-}"
+  arka_wf_safe_session_id "$session_id" || return 0
+  rm -f "$ARKA_WF_REQUIRED_DIR/$session_id" 2>/dev/null
+  return 0
+}
+
+# When invoked directly (not sourced), expose a simple CLI for ad-hoc use.
+if [ "${BASH_SOURCE[0]}" = "${0}" ]; then
+  case "${1:-}" in
+    classify)   arka_wf_classify "${2:-}" ;;
+    mark)       arka_wf_mark_required "${2:-}" ;;
+    is-required) arka_wf_is_required "${2:-}" && echo "true" || echo "false" ;;
+    clear)      arka_wf_clear_required "${2:-}" ;;
+    *)
+      echo "Usage: $0 {classify <text>|mark <session_id>|is-required <session_id>|clear <session_id>}" >&2
+      exit 64
+      ;;
+  esac
+fi

package/config/hooks/pre-tool-use.ps1

@@ -0,0 +1,117 @@
+# ============================================================================
+# ArkaOS v2 — PreToolUse Hook (Windows PowerShell)
+#
+# Parity with config/hooks/pre-tool-use.sh. Blocks Write/Edit/MultiEdit when
+# the mandatory 13-phase flow is required for the session AND the assistant
+# has not emitted a flow marker in its last 3 messages of the transcript.
+#
+# Delegates the decision to core/workflow/flow_enforcer.py.
+#
+# Exit 0 = allow (silent). Exit 2 = deny + structured hookSpecificOutput JSON.
+# ============================================================================
+
+$ErrorActionPreference = "SilentlyContinue"
+
+# --- Read stdin JSON ---
+$inputJson = [Console]::In.ReadToEnd()
+if ([string]::IsNullOrWhiteSpace($inputJson)) { exit 0 }
+
+try {
+    $inp = $inputJson | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+$toolName = [string]$inp.tool_name
+$transcriptPath = [string]$inp.transcript_path
+$sessionId = [string]$inp.session_id
+$cwd = [string]$inp.cwd
+
+# --- Fast allow: not a gated tool ---
+if ($toolName -ne "Write" -and $toolName -ne "Edit" -and $toolName -ne "MultiEdit") {
+    exit 0
+}
+
+# --- Resolve ARKAOS_ROOT ---
+if ([string]::IsNullOrWhiteSpace($env:ARKAOS_ROOT)) {
+    $repoPathFile = Join-Path $HOME ".arkaos/.repo-path"
+    if (Test-Path $repoPathFile) {
+        $env:ARKAOS_ROOT = (Get-Content $repoPathFile -Raw).Trim()
+    } elseif (Test-Path (Join-Path $HOME ".arkaos")) {
+        $env:ARKAOS_ROOT = (Join-Path $HOME ".arkaos")
+    } else {
+        $env:ARKAOS_ROOT = if ($env:ARKA_OS) { $env:ARKA_OS } else { Join-Path $HOME ".claude/skills/arkaos" }
+    }
+}
+
+$enforcerPy = Join-Path $env:ARKAOS_ROOT "core/workflow/flow_enforcer.py"
+if (-not (Test-Path $enforcerPy)) { exit 0 }
+
+$python = Get-Command python3 -ErrorAction SilentlyContinue
+if (-not $python) { $python = Get-Command python -ErrorAction SilentlyContinue }
+if (-not $python) { exit 0 }
+
+# --- Delegate to Python enforcer ---
+$env:TOOL_NAME = $toolName
+$env:TRANSCRIPT_PATH = $transcriptPath
+$env:SESSION_ID = $sessionId
+$env:CWD = $cwd
+
+$pyScript = @'
+import json
+import os
+import sys
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.flow_enforcer import evaluate, record_telemetry
+except Exception:
+    print(json.dumps({"allow": True, "reason": "enforcer-import-failed"}))
+    sys.exit(0)
+
+decision = evaluate(
+    tool_name=os.environ.get("TOOL_NAME", ""),
+    transcript_path=os.environ.get("TRANSCRIPT_PATH", ""),
+    session_id=os.environ.get("SESSION_ID", ""),
+    cwd=os.environ.get("CWD", ""),
+)
+try:
+    record_telemetry(
+        session_id=os.environ.get("SESSION_ID", ""),
+        tool=os.environ.get("TOOL_NAME", ""),
+        decision=decision,
+        cwd=os.environ.get("CWD", ""),
+    )
+except Exception:
+    pass
+print(json.dumps({
+    "allow": decision.allow,
+    "reason": decision.reason,
+    "stderr_msg": decision.to_stderr_message(),
+}))
+'@
+
+$decisionJson = $pyScript | & $python.Source -
+if ([string]::IsNullOrWhiteSpace($decisionJson)) { exit 0 }
+
+try {
+    $decision = $decisionJson | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+if ($decision.allow) { exit 0 }
+
+# --- Deny path ---
+[Console]::Error.WriteLine($decision.stderr_msg)
+
+$denyOut = @{
+    hookSpecificOutput = @{
+        hookEventName = "PreToolUse"
+        permissionDecision = "deny"
+        permissionDecisionReason = $decision.stderr_msg
+    }
+} | ConvertTo-Json -Compress -Depth 5
+
+Write-Output $denyOut
+exit 2

package/config/hooks/pre-tool-use.sh

@@ -0,0 +1,135 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS v2 — PreToolUse Hook (Flow Enforcement Gate)
+#
+# Blocks Write/Edit/MultiEdit when the mandatory 13-phase flow is required
+# for the session AND the assistant has not emitted a flow marker
+# (`[arka:routing]`, `[arka:trivial]`, or `[arka:phase:`) in its last
+# 3 messages of the transcript.
+#
+# Delegates the decision to core/workflow/flow_enforcer.py (single source
+# of truth, pytest-covered). This shell script is a thin wrapper — anti
+# pattern `duplicated-security-logic` compliance.
+#
+# Timeout: 10s.
+# Allow semantics: no stdout, exit 0.
+# Deny semantics: hookSpecificOutput.permissionDecision=deny JSON on stdout,
+# `[ARKA:ENFORCEMENT] ...` on stderr, exit 2.
+# ============================================================================
+
+input=$(cat)
+
+# ─── Extract fields (docs: session_id, transcript_path, cwd, tool_name)
+TOOL_NAME=""
+TRANSCRIPT_PATH=""
+SESSION_ID=""
+CWD=""
+if command -v jq &>/dev/null; then
+  TOOL_NAME=$(echo "$input" | jq -r '.tool_name // ""' 2>/dev/null)
+  TRANSCRIPT_PATH=$(echo "$input" | jq -r '.transcript_path // ""' 2>/dev/null)
+  SESSION_ID=$(echo "$input" | jq -r '.session_id // ""' 2>/dev/null)
+  CWD=$(echo "$input" | jq -r '.cwd // ""' 2>/dev/null)
+fi
+
+# ─── Fast allow: not a gated tool
+case "$TOOL_NAME" in
+  Write|Edit|MultiEdit) ;;
+  *) exit 0 ;;
+esac
+
+# ─── Resolve ARKAOS_ROOT (same rules as user-prompt-submit.sh) ──────────
+if [ -z "${ARKAOS_ROOT:-}" ]; then
+  if [ -f "$HOME/.arkaos/.repo-path" ]; then
+    ARKAOS_ROOT=$(cat "$HOME/.arkaos/.repo-path")
+  elif [ -d "$HOME/.arkaos" ]; then
+    ARKAOS_ROOT="$HOME/.arkaos"
+  else
+    ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+  fi
+fi
+
+# ─── Degrade gracefully if Python or module is unavailable ──────────────
+if ! command -v python3 &>/dev/null; then
+  exit 0
+fi
+if [ ! -f "$ARKAOS_ROOT/core/workflow/flow_enforcer.py" ]; then
+  exit 0
+fi
+
+# ─── Delegate to Python enforcer ────────────────────────────────────────
+DECISION_JSON=$(TOOL_NAME="$TOOL_NAME" \
+                TRANSCRIPT_PATH="$TRANSCRIPT_PATH" \
+                SESSION_ID="$SESSION_ID" \
+                CWD="$CWD" \
+                ARKAOS_ROOT="$ARKAOS_ROOT" \
+                python3 - <<'PY' 2>/dev/null
+import json
+import os
+import sys
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.flow_enforcer import evaluate, record_telemetry
+except Exception:
+    print(json.dumps({"allow": True, "reason": "enforcer-import-failed"}))
+    sys.exit(0)
+
+decision = evaluate(
+    tool_name=os.environ.get("TOOL_NAME", ""),
+    transcript_path=os.environ.get("TRANSCRIPT_PATH", ""),
+    session_id=os.environ.get("SESSION_ID", ""),
+    cwd=os.environ.get("CWD", ""),
+)
+try:
+    record_telemetry(
+        session_id=os.environ.get("SESSION_ID", ""),
+        tool=os.environ.get("TOOL_NAME", ""),
+        decision=decision,
+        cwd=os.environ.get("CWD", ""),
+    )
+except Exception:
+    pass
+print(json.dumps({
+    "allow": decision.allow,
+    "reason": decision.reason,
+    "stderr_msg": decision.to_stderr_message(),
+}))
+PY
+)
+
+if [ -z "$DECISION_JSON" ]; then
+  exit 0
+fi
+
+ALLOW=$(echo "$DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('allow', True))" 2>/dev/null)
+
+if [ "$ALLOW" = "True" ] || [ "$ALLOW" = "true" ]; then
+  exit 0
+fi
+
+# ─── Deny path: structured hookSpecificOutput + stderr fallback ─────────
+REASON=$(echo "$DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('reason',''))" 2>/dev/null)
+STDERR_MSG=$(echo "$DECISION_JSON" | python3 -c "import json,sys; print(json.load(sys.stdin).get('stderr_msg',''))" 2>/dev/null)
+
+# Emit stderr (visible to the model per Claude Code hook spec) ─────────
+echo "$STDERR_MSG" >&2
+
+# Emit structured deny JSON (preferred path when runtime understands it).
+# STDERR_MSG is passed via env var and read inside a single-quoted heredoc
+# so no shell interpolation occurs inside the Python source — this closes
+# the command-injection surface flagged by Francisca's tech review.
+STDERR_MSG="$STDERR_MSG" python3 - <<'PY'
+import json
+import os
+
+out = {
+    "hookSpecificOutput": {
+        "hookEventName": "PreToolUse",
+        "permissionDecision": "deny",
+        "permissionDecisionReason": os.environ.get("STDERR_MSG", ""),
+    }
+}
+print(json.dumps(out))
+PY
+
+exit 2

package/config/hooks/session-start.sh

@@ -89,6 +89,17 @@ MSG+="ArkaOS v${VERSION} | 65 agents | 17 departments | 244+ skills"
 [ -n "$_FORGE_LINE" ] && MSG+="\\n${_FORGE_LINE}"
 MSG+="${DRIFT}"
 
+# ─── Mandatory Flow Contract (top-of-session, highest priority) ─────────
+MSG+="\\n\\n[ARKA:MANDATORY-FLOW] NON-NEGOTIABLE. Every non-trivial request runs the 13-phase canonical flow (constitution rule mandatory-flow; source arka/skills/flow/SKILL.md):"
+MSG+="\\n  1.Input  2.Get-context  3.Route ([arka:routing] <dept> -> <lead>)  4.Call-hierarchy"
+MSG+="\\n  5.Research (Obsidian+vector DB, cite or declare gap)  6.Call-team (Agent tool)"
+MSG+="\\n  7.Plan with 6 parallel reviewers (positive / devils-advocate / Q&A / KB-research / best-solution / pessimistic)"
+MSG+="\\n  8.Present+save (Obsidian + vector DB + ~/.arkaos/plans/)  9.Wait-approval (silence != approval)"
+MSG+="\\n 10.TODO list  11.Per-todo: team-call -> complete -> QA -> Security -> Quality Gate (Marta+Eduardo+Francisca Opus) -> Document"
+MSG+="\\n 12.Loop until TODO exhausted  13.Detailed summary"
+MSG+="\\nEmit [arka:phase:N] before each step. Bypass ONLY via [arka:trivial] <reason> for single-file edits under 10 lines."
+MSG+="\\nNo runtime setting, no user convenience, no task type can opt out. This contract overrides generic-assistant defaults."
+
 # --- Session Memory Resume Context ---
 if command -v python3 &>/dev/null && [ -n "$REPO" ]; then
   _SESSION_CTX=$(cd "$REPO" && python3 -c "

package/config/hooks/stop.ps1

@@ -0,0 +1,112 @@
+# ============================================================================
+# ArkaOS v2 — Stop Hook (Windows PowerShell, WARN mode v1)
+#
+# Parity with config/hooks/stop.sh. Observes whether a flow-required session
+# closed with [arka:phase:13] or [arka:trivial]. Logs to telemetry; never
+# blocks in v1.
+# ============================================================================
+
+$ErrorActionPreference = "SilentlyContinue"
+
+$inputJson = [Console]::In.ReadToEnd()
+if ([string]::IsNullOrWhiteSpace($inputJson)) { exit 0 }
+
+try {
+    $inp = $inputJson | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+$sessionId = [string]$inp.session_id
+$transcriptPath = [string]$inp.transcript_path
+$stopHookActive = [string]$inp.stop_hook_active
+$cwd = [string]$inp.cwd
+
+if ($stopHookActive -eq "true") { exit 0 }
+
+$wfMarker = Join-Path "/tmp/arkaos-wf-required" $sessionId
+if ([string]::IsNullOrWhiteSpace($sessionId) -or -not (Test-Path $wfMarker)) {
+    exit 0
+}
+
+if ([string]::IsNullOrWhiteSpace($env:ARKAOS_ROOT)) {
+    $repoPathFile = Join-Path $HOME ".arkaos/.repo-path"
+    if (Test-Path $repoPathFile) {
+        $env:ARKAOS_ROOT = (Get-Content $repoPathFile -Raw).Trim()
+    } elseif (Test-Path (Join-Path $HOME ".arkaos")) {
+        $env:ARKAOS_ROOT = (Join-Path $HOME ".arkaos")
+    } else {
+        $env:ARKAOS_ROOT = if ($env:ARKA_OS) { $env:ARKA_OS } else { Join-Path $HOME ".claude/skills/arkaos" }
+    }
+}
+
+$enforcerPy = Join-Path $env:ARKAOS_ROOT "core/workflow/flow_enforcer.py"
+if (-not (Test-Path $enforcerPy)) { exit 0 }
+
+$python = Get-Command python3 -ErrorAction SilentlyContinue
+if (-not $python) { $python = Get-Command python -ErrorAction SilentlyContinue }
+if (-not $python) { exit 0 }
+
+$env:SESSION_ID_VAL = $sessionId
+$env:TRANSCRIPT_PATH_VAL = $transcriptPath
+$env:CWD_VAL = $cwd
+
+$pyScript = @'
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT"])
+try:
+    from core.workflow.flow_enforcer import (
+        _load_last_assistant_messages,
+        TELEMETRY_PATH,
+        clear_flow_required,
+    )
+except Exception:
+    sys.exit(0)
+
+session_id = os.environ.get("SESSION_ID_VAL", "")
+transcript_path = os.environ.get("TRANSCRIPT_PATH_VAL", "")
+cwd = os.environ.get("CWD_VAL", "")
+
+messages = _load_last_assistant_messages(transcript_path, n=1)
+last = messages[-1] if messages else ""
+
+phase13 = bool(re.search(r"\[arka:phase:13\]", last, re.IGNORECASE))
+trivial = bool(re.search(r"\[arka:trivial\]", last, re.IGNORECASE))
+
+entry = {
+    "ts": datetime.now(timezone.utc).isoformat(),
+    "session_id": session_id,
+    "cwd": cwd,
+    "event": "stop-hook-flow-check",
+    "closing_marker_found": phase13 or trivial,
+    "phase13": phase13,
+    "trivial": trivial,
+    "mode": "warn",
+}
+
+try:
+    TELEMETRY_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with TELEMETRY_PATH.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry) + "\n")
+except Exception:
+    pass
+
+try:
+    clear_flow_required(session_id)
+except Exception:
+    pass
+'@
+
+$pyScript | & $python.Source - | Out-Null
+
+# Belt-and-braces marker cleanup (safe even if the Python block crashed).
+if ($sessionId -match '^[A-Za-z0-9._-]{1,128}$') {
+    Remove-Item -LiteralPath $wfMarker -ErrorAction SilentlyContinue
+}
+
+exit 0

package/config/hooks/stop.sh

@@ -0,0 +1,127 @@
+#!/usr/bin/env bash
+# ============================================================================
+# ArkaOS v2 — Stop Hook (Flow Completion Validator, WARN mode v1)
+#
+# When the classifier marked the session as flow-required, this hook checks
+# whether the final assistant message contains [arka:phase:13] or
+# [arka:trivial]. If absent, a structured warning is appended to
+# ~/.arkaos/telemetry/enforcement.jsonl. The hook NEVER blocks in v1.
+#
+# Promotion to strict mode is planned for v2.21.0 after ≥ 2 weeks of clean
+# telemetry. Until then, this hook is observation only.
+#
+# Timeout: 5s | Always exit 0.
+# ============================================================================
+
+input=$(cat)
+
+SESSION_ID=""
+TRANSCRIPT_PATH=""
+STOP_HOOK_ACTIVE=""
+CWD=""
+if command -v jq &>/dev/null; then
+  SESSION_ID=$(echo "$input" | jq -r '.session_id // ""' 2>/dev/null)
+  TRANSCRIPT_PATH=$(echo "$input" | jq -r '.transcript_path // ""' 2>/dev/null)
+  STOP_HOOK_ACTIVE=$(echo "$input" | jq -r '.stop_hook_active // ""' 2>/dev/null)
+  CWD=$(echo "$input" | jq -r '.cwd // ""' 2>/dev/null)
+fi
+
+# Prevent infinite loops when Stop hook was triggered by its own decision.
+if [ "$STOP_HOOK_ACTIVE" = "true" ]; then
+  exit 0
+fi
+
+# Only evaluate sessions where the classifier flagged a creation intent.
+WF_MARKER="/tmp/arkaos-wf-required/$SESSION_ID"
+if [ -z "$SESSION_ID" ] || [ ! -f "$WF_MARKER" ]; then
+  exit 0
+fi
+
+# Resolve ARKAOS_ROOT
+if [ -z "${ARKAOS_ROOT:-}" ]; then
+  if [ -f "$HOME/.arkaos/.repo-path" ]; then
+    ARKAOS_ROOT=$(cat "$HOME/.arkaos/.repo-path")
+  elif [ -d "$HOME/.arkaos" ]; then
+    ARKAOS_ROOT="$HOME/.arkaos"
+  else
+    ARKAOS_ROOT="${ARKA_OS:-$HOME/.claude/skills/arkaos}"
+  fi
+fi
+
+if ! command -v python3 &>/dev/null; then
+  exit 0
+fi
+if [ ! -f "$ARKAOS_ROOT/core/workflow/flow_enforcer.py" ]; then
+  exit 0
+fi
+
+# Reuse the last-messages reader to check for a closing phase marker.
+SESSION_ID_VAL="$SESSION_ID" \
+TRANSCRIPT_PATH_VAL="$TRANSCRIPT_PATH" \
+CWD_VAL="$CWD" \
+ARKAOS_ROOT_VAL="$ARKAOS_ROOT" \
+python3 - <<'PY' 2>/dev/null
+import json
+import os
+import re
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+sys.path.insert(0, os.environ["ARKAOS_ROOT_VAL"])
+try:
+    from core.workflow.flow_enforcer import (
+        _load_last_assistant_messages,
+        TELEMETRY_PATH,
+        clear_flow_required,
+    )
+except Exception:
+    sys.exit(0)
+
+session_id = os.environ.get("SESSION_ID_VAL", "")
+transcript_path = os.environ.get("TRANSCRIPT_PATH_VAL", "")
+cwd = os.environ.get("CWD_VAL", "")
+
+# Only inspect the very last assistant message for closing markers.
+messages = _load_last_assistant_messages(transcript_path, n=1)
+last = messages[-1] if messages else ""
+
+phase13 = bool(re.search(r"\[arka:phase:13\]", last, re.IGNORECASE))
+trivial = bool(re.search(r"\[arka:trivial\]", last, re.IGNORECASE))
+closing_ok = phase13 or trivial
+
+entry = {
+    "ts": datetime.now(timezone.utc).isoformat(),
+    "session_id": session_id,
+    "cwd": cwd,
+    "event": "stop-hook-flow-check",
+    "closing_marker_found": closing_ok,
+    "phase13": phase13,
+    "trivial": trivial,
+    "mode": "warn",
+}
+
+try:
+    TELEMETRY_PATH.parent.mkdir(parents=True, exist_ok=True)
+    with TELEMETRY_PATH.open("a", encoding="utf-8") as fh:
+        fh.write(json.dumps(entry) + "\n")
+except Exception:
+    pass
+
+# Clean up the session marker once Stop has evaluated.
+try:
+    clear_flow_required(session_id)
+except Exception:
+    pass
+PY
+
+# Belt-and-braces: remove the marker at shell level in case the Python
+# block above crashed before reaching clear_flow_required(). Session_id
+# is already validated by the Python helper; this shell remove is scoped
+# to the exact marker path and is idempotent.
+case "$SESSION_ID" in
+  *[!A-Za-z0-9._-]*|"") ;;  # reject unsafe/empty session ids
+  *) rm -f "$WF_MARKER" 2>/dev/null ;;
+esac
+
+exit 0

package/config/hooks/user-prompt-submit.sh

@@ -83,14 +83,23 @@ mkdir -p "$CACHE_DIR" 2>/dev/null
 
 # ─── Extract user input from hook JSON ───────────────────────────────────
 user_input=""
+SESSION_ID=""
 if command -v jq &>/dev/null; then
   user_input=$(echo "$input" | jq -r '.userInput // .message // ""' 2>/dev/null)
+  SESSION_ID=$(echo "$input" | jq -r '.session_id // ""' 2>/dev/null)
 fi
 # Fallback: try to get the raw text
 if [ -z "$user_input" ]; then
   user_input=$(echo "$input" | head -c 2000)
 fi
 
+# ─── Load shared workflow classifier ─────────────────────────────────────
+_CLASSIFIER_LIB="$(dirname "$0")/_lib/workflow-classifier.sh"
+if [ -f "$_CLASSIFIER_LIB" ]; then
+  # shellcheck disable=SC1090
+  . "$_CLASSIFIER_LIB"
+fi
+
 # ─── Try Python Synapse bridge first ────────────────────────────────────
 python_result=""
 BRIDGE_SCRIPT="${ARKAOS_ROOT}/scripts/synapse-bridge.py"
@@ -276,35 +285,50 @@ When [knowledge:N chunks] is present, cite at least one source.
 If [knowledge:N chunks] is absent on a non-trivial ArkaOS topic, query Obsidian first."
 
 # ─── Workflow Classifier (hard enforcement for creation/implementation) ──
-# Classifies the user prompt. If it looks like a creation/implementation/
-# modification request that is NOT already routed with an explicit /prefix,
-# emits a directive that the agent MUST acknowledge with [arka:routing]
-# BEFORE using any write tool. Trivial quick questions pass through
-# untouched. Explicit slash commands pass through untouched.
+# Uses the shared _lib/workflow-classifier.sh. When a creation/implementation
+# verb is detected, the session is marked as flow-required so PreToolUse
+# can block Write/Edit/MultiEdit until the agent emits [arka:routing] or
+# [arka:trivial]. Explicit slash commands and bang shells pass through.
 _WORKFLOW_DIRECTIVE=""
-if [ -n "$user_input" ]; then
-  # Skip: explicit slash command (already routed)
-  _FIRST_CHAR=$(echo "$user_input" | head -c 1)
-  if [ "$_FIRST_CHAR" != "/" ] && [ "$_FIRST_CHAR" != "!" ]; then
-    # Match creation/implementation verbs in EN and PT (case-insensitive).
-    _VERB_PATTERN='(criar?|crie[ms]?|cria[mr]?|adicionar?|adiciona[mr]?|implementar?|implementa[mr]?|desenvolver?|desenvolve[mr]?|construir?|constru[ií]a?[mr]?|fazer?|faz[ae][mr]?|refactor(izar?)?|corrigir?|corrige[mr]?|consertar?|conserta[mr]?|create[sd]?|creating|build(s|ing)?|add(s|ed|ing)?|implement(s|ed|ing)?|develop(s|ed|ing)?|fix(es|ed|ing)?|refactor(s|ed|ing)?|make[sd]?|making)'
-    _NOUN_PATTERN='(feature|funcionalidade|skill|squad|agent[e]?|workflow|endpoint|api|component[e]?|module|m[oó]dulo|page|p[aá]gina|hook|pipeline|integration|integra[cç][aã]o|dashboard|report|report[eó]|script|test[es]?)'
-    if echo "$user_input" | grep -qiE "\b${_VERB_PATTERN}\b"; then
-      _WORKFLOW_DIRECTIVE="
-[ARKA:WORKFLOW-REQUIRED] Your user request matched a CREATION/IMPLEMENTATION pattern.
-You MUST, before using any Write, Edit, Bash with side-effects, or Agent tool:
-  1. Output on the first line: [arka:routing] <department-slug> -> <lead-agent>
-     (e.g. [arka:routing] dev -> Paulo, [arka:routing] brand -> Valentina,
-      [arka:routing] kb -> Clara, [arka:routing] mkt -> Luna)
-  2. State the workflow name and phase count in one short sentence.
-  3. Begin phase 1 (spec or plan) BEFORE any code is written.
-  4. Run the Quality Gate (Marta + Eduardo + Francisca, Opus) before claiming done.
-Trivial override: if the request is a single-file edit under 10 lines AND the user
-used an imperative like 'rename X', 'fix typo', you MAY emit [arka:trivial] <reason>
-and proceed directly. Anything else requires routing. This is enforced, not advisory.
-Skipping routing violates constitution rules squad-routing, arka-supremacy,
-spec-driven, mandatory-qa, sequential-validation."
+if [ -n "$user_input" ] && command -v arka_wf_classify &>/dev/null; then
+  if [ "$(arka_wf_classify "$user_input")" = "true" ]; then
+    # Mark session as flow-required (consumed by pre-tool-use.sh and stop.sh)
+    if command -v arka_wf_mark_required &>/dev/null; then
+      arka_wf_mark_required "$SESSION_ID"
     fi
+    _WORKFLOW_DIRECTIVE="
+[ARKA:WORKFLOW-REQUIRED] Your user request matched a CREATION/IMPLEMENTATION pattern.
+The ArkaOS mandatory 13-phase flow applies. It is NON-NEGOTIABLE (constitution rule
+mandatory-flow). You MUST walk every phase, in order, emitting a [arka:phase:N] tag
+before each:
+  1. Input — restate the request verbatim.
+  2. Get context — profile, repo, git, cwd tag, session digests.
+  3. Decide route — emit [arka:routing] <dept> -> <lead>.
+  4. Call hierarchy — escalate to Tier 0 if strategic/cross-dept/security/financial.
+  5. Research — query Obsidian + vector DB, cite sources or declare the gap.
+  6. Call team — dispatch specialists via Agent tool.
+  7. Plan — run six parallel reviewers: positive, devil's advocate, Q&A, KB research,
+     best-solution validator, pessimistic. Synthesise into a spec.
+  8. Present plan — save to Obsidian + vector DB + ~/.arkaos/plans/, print inline.
+  9. Wait approval — EXPLICIT user go. Silence is NOT approval.
+ 10. TODO list — atomic, ordered, independently verifiable.
+ 11. Per-todo loop — team call -> complete -> QA (all tests, E2E, Playwright) ->
+     Security review -> Quality Gate (Marta + Eduardo + Francisca, Opus) -> Document.
+     Each step loops back on fail. No compound gates.
+ 12. Loop until TODO is exhausted.
+ 13. Detailed summary — what was done, where, how to verify, what is still open.
+
+No Write, Edit, Bash-with-side-effects, or Agent dispatch before Phase 7 completes
+for the affected item. No advancing a todo until QA AND Security AND Quality Gate
+all pass for it. Phase 5 and Phase 8 require Obsidian/KB writes, not just reads.
+
+Trivial override: single-file edit under 10 lines with imperative verb
+(rename X, fix typo in Y). Emit [arka:trivial] <reason> as first line and proceed.
+Anything else runs the full 13 phases. Source: arka/skills/flow/SKILL.md.
+
+This is enforced by the hook and the session-start systemMessage, not by convention.
+Skipping violates: mandatory-flow, squad-routing, spec-driven, mandatory-qa,
+sequential-validation, full-visibility, arka-supremacy."
   fi
 fi
 

package/core/workflow/flow_enforcer.py

@@ -0,0 +1,272 @@
+"""Mandatory 13-phase flow enforcement for write-mutation tools.
+
+Invoked by the Claude Code `PreToolUse` hook. Decides whether a `Write`,
+`Edit`, or `MultiEdit` tool call may proceed, based on markers observed
+in the last N assistant messages of the session transcript.
+
+Design contract:
+- Stateless transcript parse (no /tmp state for decisions).
+- Side effects limited to reading the transcript path supplied by the hook.
+- Signals permission when the assistant has emitted one of the flow markers:
+  `[arka:routing]`, `[arka:trivial]`, or `[arka:phase:`.
+- Respects `ARKA_BYPASS_FLOW=1` env var (installer/`/arka update` internal).
+- Honors feature flag `hooks.hardEnforcement` in `~/.arkaos/config.json`.
+- Gated tool list is closed: anything outside it is always allowed.
+"""
+
+import json
+import os
+import re
+from contextlib import contextmanager
+from dataclasses import asdict, dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+
+try:
+    import fcntl  # POSIX only
+    _HAS_FLOCK = True
+except ImportError:
+    _HAS_FLOCK = False
+
+
+@contextmanager
+def _locked_append(path: Path):
+    """Append to `path` under an exclusive advisory lock (POSIX flock).
+
+    On Windows or any platform without fcntl, falls back to a plain append
+    (single-process writers remain safe; cross-process interleaving is
+    mitigated by `O_APPEND` atomicity for writes up to PIPE_BUF).
+    """
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fh = path.open("a", encoding="utf-8")
+    try:
+        if _HAS_FLOCK:
+            fcntl.flock(fh.fileno(), fcntl.LOCK_EX)
+        yield fh
+    finally:
+        if _HAS_FLOCK:
+            try:
+                fcntl.flock(fh.fileno(), fcntl.LOCK_UN)
+            except OSError:
+                pass
+        fh.close()
+
+GATED_TOOLS: frozenset[str] = frozenset({"Write", "Edit", "MultiEdit"})
+
+ROUTING_RE = re.compile(r"\[arka:routing\]\s*[\w-]+\s*->\s*\w+", re.IGNORECASE)
+TRIVIAL_RE = re.compile(r"\[arka:trivial\]\s*\S+", re.IGNORECASE)
+PHASE_RE = re.compile(r"\[arka:phase:\d+\]", re.IGNORECASE)
+SAFE_SESSION_ID_RE = re.compile(r"^[A-Za-z0-9._-]{1,128}$")
+
+ASSISTANT_WINDOW = 3
+CONFIG_PATH = Path.home() / ".arkaos" / "config.json"
+BYPASS_AUDIT_PATH = Path.home() / ".arkaos" / "audit" / "bypass.log"
+TELEMETRY_PATH = Path.home() / ".arkaos" / "telemetry" / "enforcement.jsonl"
+FLOW_REQUIRED_DIR = Path("/tmp/arkaos-wf-required")
+
+
+def _safe_session_id(session_id: str) -> str | None:
+    """Validate session_id against a strict allowlist (prevents path traversal).
+
+    Returns the id if safe, or None if it contains path separators, dots-dots,
+    or characters outside `[A-Za-z0-9._-]`. Callers MUST treat None as reject.
+    """
+    if not session_id or not isinstance(session_id, str):
+        return None
+    if not SAFE_SESSION_ID_RE.match(session_id):
+        return None
+    return session_id
+
+
+@dataclass
+class Decision:
+    """Outcome of enforcement evaluation for a single tool call."""
+
+    allow: bool
+    reason: str
+    marker_found: str | None = None
+    phase_observed: str | None = None
+    bypass_used: bool = False
+
+    def to_stderr_message(self) -> str:
+        if self.allow:
+            return ""
+        return (
+            f"[ARKA:ENFORCEMENT] Flow marker missing. "
+            f"Emit `[arka:routing] <dept> -> <lead>` or `[arka:trivial] <reason>` "
+            f"before any Write/Edit/MultiEdit. Reason: {self.reason}"
+        )
+
+
+def _feature_flag_on() -> bool:
+    if not CONFIG_PATH.exists():
+        return False
+    try:
+        data = json.loads(CONFIG_PATH.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return False
+    return bool(data.get("hooks", {}).get("hardEnforcement", False))
+
+
+def _bypass_env_active() -> bool:
+    return os.environ.get("ARKA_BYPASS_FLOW", "").strip() == "1"
+
+
+def _audit_bypass(session_id: str, tool: str, cwd: str) -> None:
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "session_id": session_id,
+        "tool": tool,
+        "cwd": cwd,
+        "reason": os.environ.get("ARKA_BYPASS_REASON", ""),
+    }
+    with _locked_append(BYPASS_AUDIT_PATH) as fh:
+        fh.write(json.dumps(entry) + "\n")
+
+
+def record_telemetry(
+    session_id: str, tool: str, decision: Decision, cwd: str
+) -> None:
+    """Append a structured record to the enforcement telemetry log."""
+    entry = {
+        "ts": datetime.now(timezone.utc).isoformat(),
+        "session_id": session_id,
+        "tool": tool,
+        "cwd": cwd,
+        **asdict(decision),
+    }
+    with _locked_append(TELEMETRY_PATH) as fh:
+        fh.write(json.dumps(entry) + "\n")
+
+
+def _flow_required_for_session(session_id: str) -> bool:
+    """Check whether the UserPromptSubmit classifier flagged this session."""
+    safe = _safe_session_id(session_id)
+    if safe is None:
+        return False
+    marker = FLOW_REQUIRED_DIR / safe
+    return marker.exists()
+
+
+def _extract_text(content: object) -> str:
+    """Flatten Claude transcript message content into a single string."""
+    if isinstance(content, str):
+        return content
+    if isinstance(content, list):
+        parts: list[str] = []
+        for item in content:
+            if isinstance(item, dict):
+                if "text" in item:
+                    parts.append(str(item["text"]))
+                elif item.get("type") == "tool_use":
+                    parts.append(f"<tool_use:{item.get('name', '')}>")
+            elif isinstance(item, str):
+                parts.append(item)
+        return "\n".join(parts)
+    return ""
+
+
+def _load_last_assistant_messages(transcript_path: str, n: int) -> list[str]:
+    """Read the last `n` assistant messages from a JSONL transcript."""
+    path = Path(transcript_path) if transcript_path else None
+    if path is None or not path.exists():
+        return []
+    messages: list[str] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        if not line.strip():
+            continue
+        try:
+            record = json.loads(line)
+        except json.JSONDecodeError:
+            continue
+        role = record.get("role") or record.get("message", {}).get("role")
+        if role != "assistant":
+            continue
+        content = record.get("content")
+        if content is None:
+            content = record.get("message", {}).get("content")
+        text = _extract_text(content)
+        if text:
+            messages.append(text)
+    return messages[-n:]
+
+
+def _scan_markers(messages: list[str]) -> tuple[str | None, str | None]:
+    """Return (marker_found, phase_observed) across the given messages."""
+    marker_found: str | None = None
+    phase_observed: str | None = None
+    for text in messages:
+        if phase_observed is None:
+            phase_match = PHASE_RE.search(text)
+            if phase_match:
+                phase_observed = phase_match.group(0)
+        if marker_found is None:
+            if ROUTING_RE.search(text):
+                marker_found = "routing"
+            elif TRIVIAL_RE.search(text):
+                marker_found = "trivial"
+            elif PHASE_RE.search(text):
+                marker_found = "phase"
+    return marker_found, phase_observed
+
+
+def evaluate(
+    tool_name: str,
+    transcript_path: str,
+    session_id: str = "",
+    cwd: str = "",
+) -> Decision:
+    """Decide whether a tool call may proceed.
+
+    Returns a Decision. Caller is responsible for translating `allow=False`
+    into the appropriate hook exit code or permissionDecision output.
+    """
+    if tool_name not in GATED_TOOLS:
+        return Decision(allow=True, reason="tool-not-gated")
+
+    if not _feature_flag_on():
+        return Decision(allow=True, reason="feature-flag-off")
+
+    if _bypass_env_active():
+        _audit_bypass(session_id, tool_name, cwd)
+        return Decision(allow=True, reason="env-bypass", bypass_used=True)
+
+    if not _flow_required_for_session(session_id):
+        return Decision(allow=True, reason="classifier-did-not-match")
+
+    messages = _load_last_assistant_messages(transcript_path, ASSISTANT_WINDOW)
+    marker_found, phase_observed = _scan_markers(messages)
+
+    if marker_found is None:
+        return Decision(
+            allow=False,
+            reason="no-flow-marker-in-last-3-assistant-messages",
+            phase_observed=phase_observed,
+        )
+
+    return Decision(
+        allow=True,
+        reason=f"marker-found:{marker_found}",
+        marker_found=marker_found,
+        phase_observed=phase_observed,
+    )
+
+
+def mark_flow_required(session_id: str) -> None:
+    """Invoked by UserPromptSubmit when classifier matches creation intent."""
+    safe = _safe_session_id(session_id)
+    if safe is None:
+        return
+    FLOW_REQUIRED_DIR.mkdir(parents=True, exist_ok=True)
+    marker = FLOW_REQUIRED_DIR / safe
+    marker.write_text(datetime.now(timezone.utc).isoformat(), encoding="utf-8")
+
+
+def clear_flow_required(session_id: str) -> None:
+    """Clear the flow-required marker (end of session / rollout tooling)."""
+    safe = _safe_session_id(session_id)
+    if safe is None:
+        return
+    marker = FLOW_REQUIRED_DIR / safe
+    if marker.exists():
+        marker.unlink()

package/installer/adapters/claude-code.js

@@ -94,6 +94,19 @@ export default {
       { hooks: [hookEntry(hooksDir, "post-tool-use", 5)] },
     ];
 
+    // PreToolUse — Flow enforcement gate (gated by hooks.hardEnforcement
+    // feature flag in ~/.arkaos/config.json; no-op when flag is false).
+    settings.hooks.PreToolUse = [
+      { hooks: [hookEntry(hooksDir, "pre-tool-use", 10)] },
+    ];
+
+    // Stop — Flow completion validator (WARN mode in v2.20.0; promotion
+    // to STRICT mode is gated on ≥ 2 weeks of clean telemetry per ADR
+    // 2026-04-17-binding-flow-enforcement).
+    settings.hooks.Stop = [
+      { hooks: [hookEntry(hooksDir, "stop", 5)] },
+    ];
+
     // PreCompact — Session digest
     settings.hooks.PreCompact = [
       { hooks: [hookEntry(hooksDir, "pre-compact", 30)] },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.19.2",
+  "version": "2.20.0-beta.1",
   "description": "The Operating System for AI Agent Teams",
   "type": "module",
   "bin": {

package/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "arkaos-core"
-version = "2.19.2"
+version = "2.20.0-beta.1"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}