arkaos 2.19.2 → 2.20.0

package/VERSION

@@ -1 +1 @@
-2.19.2
+2.20.0

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/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/user-prompt-submit.sh

@@ -292,18 +292,37 @@ if [ -n "$user_input" ]; then
     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."
+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
 fi

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "arkaos",
-  "version": "2.19.2",
+  "version": "2.20.0",
   "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"
 description = "Core engine for ArkaOS — The Operating System for AI Agent Teams"
 readme = "README.md"
 license = {text = "MIT"}