@manhquy/flow-skill 0.1.0 → 0.2.1

package/skills/flow/harness/graph_ids.py

@@ -0,0 +1,35 @@
+"""Monotonic, lexicographically sortable ids for the graph executor (stdlib only).
+
+Format: 16 hex chars of a strictly-increasing nanosecond timestamp + 6 hex chars of
+random suffix, fixed width 22. Within one process ids are STRICTLY increasing (the
+timestamp is bumped past the last issued value, so two calls in the same nanosecond
+still order); across processes ordering follows wall clock at nanosecond grain and
+the random suffix keeps ids unique — the same guarantee LangGraph's UUID6 checkpoint
+ids provide, without a dependency. Fixed width makes string sort == numeric sort.
+"""
+
+import os
+import threading
+import time
+
+_lock = threading.Lock()
+_last_ns = 0
+
+
+def after(prev):
+    """An id strictly greater than `prev`. Used when the journal head was minted by a
+    process whose clock ran ahead of ours: ordering here is lexicographic, so a plain
+    timestamp id would silently sort BELOW the head and the write would be invisible."""
+    with _lock:
+        ts = int(prev[:16], 16) + 1
+    return "%016x%s" % (ts, os.urandom(3).hex())
+
+
+def new_id():
+    global _last_ns
+    with _lock:
+        ns = time.time_ns()
+        if ns <= _last_ns:
+            ns = _last_ns + 1
+        _last_ns = ns
+    return "%016x%s" % (ns, os.urandom(3).hex())

package/skills/flow/harness/graph_predicates.py

@@ -0,0 +1,48 @@
+"""Predicate registry + stage mapping for the graph executor (stdlib only).
+
+The registry is EXACTLY {always, review_green, review_red}: predicates read only
+durable artifacts (here, the recorded gate exit in a checkpoint manifest) - never
+LLMs, never the network. Debt-skips are NOT predicates: they are a plan_next
+traversal semantic keyed on each gate_check node's explicit `stage` field.
+"""
+
+# Keep in sync with flow.sh STAGES (flow.sh:122) - the closed set every planning
+# gate_check node's `stage` field must belong to. 05-contract is never skippable
+# (cmd_skip's primary guard), so the skippable set is STAGES minus the last.
+STAGES = ["00-idea", "01-research", "02-scope", "03-prd", "04-adr", "05-contract"]
+SKIPPABLE_STAGES = STAGES[:-1]
+
+
+def always(manifest):
+    return True
+
+
+def review_green(manifest):
+    gate = (manifest or {}).get("gate") or {}
+    return gate.get("exit") == 0
+
+
+def review_red(manifest):
+    gate = (manifest or {}).get("gate") or {}
+    return gate.get("exit") not in (None, 0)
+
+
+REGISTRY = {"always": always, "review_green": review_green, "review_red": review_red}
+
+
+def evaluate(name, manifest):
+    fn = REGISTRY.get(name)
+    if fn is None:
+        raise ValueError(f"unregistered predicate: {name}")
+    return fn(manifest)
+
+
+def stage_map(topo):
+    """node-id -> stage-name for every gate_check node carrying a `stage` field.
+    (Card-subgraph gate_check nodes MUST NOT declare `stage` - a stage on
+    card-review would make the review gate debt-skippable; lint enforces this.)"""
+    out = {}
+    for name, spec in topo.get("nodes", {}).items():
+        if spec.get("type") == "gate_check" and spec.get("stage"):
+            out[name] = spec["stage"]
+    return out

package/skills/flow/harness/pins/flow-topology.sha256

@@ -0,0 +1 @@
+493d4869516f2f7777b969580af145dece90be88b7c5a435edcce81f6446bad9  flow-topology.json

package/skills/flow/harness/schema/014-graph-executor.sql

@@ -0,0 +1,67 @@
+-- flow-owned schema - migration 014 (graph-executor band 014+)
+-- Graph executor foundation: execution journal, checkpoints (evidence manifests, never
+-- blobs), step writes, and operator interrupts. 013 stays reserved/absent (upstream
+-- changeset content sha); 014+ is flow-owned per the 2026-07-26 supersession of the
+-- work-graph red line (see GAP-MATRIX-0.1.17.md).
+
+CREATE TABLE graph_execution (
+    id               TEXT PRIMARY KEY,
+    project          TEXT NOT NULL,
+    kind             TEXT NOT NULL CHECK(kind IN ('auto_run','planning','card')),
+    topology_version INTEGER NOT NULL,
+    topology_hash    TEXT NOT NULL,
+    status           TEXT NOT NULL DEFAULT 'running'
+                     CHECK(status IN ('running','paused','done','failed','abandoned')),
+    outcome          TEXT,
+    story_id         TEXT REFERENCES story(id),
+    created_at       TEXT NOT NULL DEFAULT (datetime('now')),
+    updated_at       TEXT NOT NULL DEFAULT (datetime('now'))
+);
+
+CREATE INDEX idx_graph_execution_status ON graph_execution(status);
+
+CREATE TABLE graph_checkpoint (
+    execution_id         TEXT NOT NULL REFERENCES graph_execution(id) ON DELETE CASCADE,
+    ns                   TEXT NOT NULL DEFAULT '',
+    checkpoint_id        TEXT NOT NULL,
+    parent_checkpoint_id TEXT,
+    node                 TEXT NOT NULL,
+    manifest             TEXT NOT NULL,
+    versions             TEXT NOT NULL,
+    seen                 TEXT NOT NULL,
+    meta                 TEXT NOT NULL,
+    PRIMARY KEY (execution_id, ns, checkpoint_id)
+);
+
+CREATE INDEX idx_graph_checkpoint_parent ON graph_checkpoint(parent_checkpoint_id);
+
+CREATE TABLE graph_step_write (
+    execution_id  TEXT NOT NULL REFERENCES graph_execution(id) ON DELETE CASCADE,
+    ns            TEXT NOT NULL DEFAULT '',
+    checkpoint_id TEXT NOT NULL,
+    task_id       TEXT NOT NULL,
+    idx           INTEGER NOT NULL,
+    channel       TEXT NOT NULL,
+    value         TEXT NOT NULL,
+    PRIMARY KEY (execution_id, ns, checkpoint_id, task_id, idx)
+);
+
+CREATE TABLE graph_interrupt (
+    execution_id   TEXT NOT NULL REFERENCES graph_execution(id) ON DELETE CASCADE,
+    ns             TEXT NOT NULL DEFAULT '',
+    interrupt_id   TEXT NOT NULL,
+    node           TEXT NOT NULL,
+    prompt         TEXT NOT NULL,
+    security_class INTEGER NOT NULL DEFAULT 0,
+    resume_value   TEXT,
+    resolved_by    TEXT,
+    status         TEXT NOT NULL DEFAULT 'open' CHECK(status IN ('open','resolved','abandoned')),
+    created_at     TEXT NOT NULL DEFAULT (datetime('now')),
+    resolved_at    TEXT,
+    PRIMARY KEY (execution_id, ns, interrupt_id)
+);
+
+CREATE UNIQUE INDEX idx_graph_interrupt_one_open
+  ON graph_interrupt(execution_id, ns, node) WHERE status = 'open';
+
+INSERT INTO schema_version (version) VALUES (14);

package/skills/flow/references/auto-run.md

@@ -17,9 +17,14 @@ principles below. Operator chose: **Tier-A auto-merge green cards; halt at secur
 ```
 for each todo card in card-number order:
   0. tier-classify. If Tier-C -> HALT, write DEBT line, ask operator. Do not proceed.
+     [records: flow harness graph record --execution "$(flow.sh harness graph session)" \
+                 --ns card:C-NNN --node card-review --interrupt --security-class]
   1. spawn ONE scoped subagent (agent-stage-mapping.md) in its own worktree
-     git worktree add ../<project>-C-NNN -b card/C-NNN
+     /flow workspace add card/C-NNN --card C-NNN     [records: card-dispatch]
+     (a raw `git worktree add` records NOTHING — use the verb, or the journal has a hole)
   2. agent builds to contract, touches only allowed files, runs ## Verify for real
+     [no recording: the build is LLM work, and checkpoints only sit at deterministic
+      gate/step boundaries — the next `check` is what proves it]
   3. review the diff (code-reviewer or bmad-code-review 3-layer; see adversarial-review.md).
        On a security-class card, add a USABLE cross-vendor lens (Codex, and/or Antigravity/Gemini-3).
        red (strike 1) -> repair: spawn Task(subagent_type="debugger") with a SCOPED BRIEF
@@ -32,12 +37,34 @@ for each todo card in card-number order:
          USABLE, else escalate
        green -> continue
   4. flow.sh check C-NNN must PASS (mechanical) + gate-rules semantic check
+     [records: card-review, with the gate exit as the evidence]
   5. merge to main in card order; deploy; VERIFY ON LIVE URL (merge != shipped)
   6. paste world-state evidence into the card; status: done
+     [records: card-verify-live, via '/flow card done C-NNN' (evidence gate = the done boundary)]
   7. flow.sh harness story complete --id … --proof-source manual (or card_markdown_gate) + trace; log AUTO-LOG.md
-  8. remove worktree
+  8. remove worktree: /flow workspace remove card/C-NNN
+     [records: card-merge — the executor computes the ancestry proof itself and records
+      card-abandon instead if the branch was never merged — and ingests the worktree's
+      usage events into the main DB before the tree is gone]
 ```
 
+## Recording contract (graph executor, `FLOW_GRAPH_EXECUTOR=1`)
+Boundaries are recorded by the verbs above, which this loop already calls — nothing depends
+on the agent remembering an extra call. Only the Tier-C interrupt (step 0) is an explicit
+`graph record` invocation; `graph session` returns the project's running execution
+(minting one atomically if absent — one execution per project, shared by every worktree).
+The card path is dispatch (`workspace add`) → review (`check`) → merge (`workspace remove`),
+with an optional verify-live between review and merge when you close the card via
+`card done` rather than hand-editing `status:`; an unmerged teardown records card-abandon,
+and a RED review loops back to review (bounded by max_visits — two strikes, then escalate).
+Every one of those transitions is a declared topology edge, and
+`tests/test_flow_graph_parallel_cards.sh` drives a real lifecycle and fails if the runner
+ever emits a transition the topology does not declare. The executor never drives the loop: it records evidence, computes
+the next node from topology + journal, and reconciles against git (`graph resume` with no
+open interrupt prints a reconciliation report), so merged-but-unrecorded work is never
+re-dispatched. Ready/parallel decisions come from `flow harness graph cards`
+(deps-met parity with `/flow ready`, plus allowed-files overlap serialization).
+
 ## Hard stops (mandatory — see loop-harness-2026-principles.md in Phase 4)
 - Iteration cap per card (e.g. 2 repair attempts), token budget, wall-clock cap. Exceed any
   -> HALT + report. A loop with no cap is an antipattern.

package/skills/flow/references/command-dispatch.md

@@ -14,6 +14,7 @@ install dir; run from the project root so `flow/` and `cards/` resolve.
 | `/flow card start C-NNN` | `bash <skill>/runner/flow.sh card start C-NNN` | Optional: mark the card in flight (operator-visible in-progress, shown in `/flow status`). Portable `cards/.inflight` registry; does NOT touch the gated `status:` field. Coexists with hand-edit. |
 | `/flow card done C-NNN` | `bash <skill>/runner/flow.sh card done C-NNN` | Optional convenience: CLI-owned flip to `done`, gated by the SAME done-rules as `check` (reverts on fail — never a hollow done). Then still apply the semantic card review (diff-vs-scope, contract shapes, real evidence) as with `check`. |
 | `/flow check C-NNN` | `bash <skill>/runner/flow.sh check C-NNN` | If PASS mechanically: review diff-vs-scope, allowed-files drift, contract-shape match, DESIGN.md for UI, evidence = real world-state. |
+| `/flow gate <stage>` (or `--card C-NNN`) | `bash <skill>/runner/flow.sh gate <stage\|--card C-NNN>` | Read-only mechanical scan (unchecked boxes + `[FILL]`) with NO unlock, NO template copy, NO durable writes — the only flow.sh verb the graph executor runs from topology `cmd` position. Relay findings; `next`/`check` still own real progression + durable hooks. |
 | `/flow contract` | `bash <skill>/runner/flow.sh contract` | After the contract gate / before UI cards (web): flags client base-URL vs served-path prefix drift (double-`/api`, mixed-prefix) — the class spec-diff tools miss. Advisory; confirm on the running app. |
 | `/flow tokens` | `bash <skill>/runner/flow.sh tokens` | On/after UI cards: flags DESIGN.md tokens the CSS never uses + VALUE mismatches (same name, drifted value) + orphan CSS vars (info). Advisory; if the swap is intentional, record a dated DESIGN.md amendment. |
 | `/flow coherence` | `bash <skill>/runner/flow.sh coherence` | Flags version drift across declared version fields (package.json / pyproject / src app_version). The cheap doc-vs-code slice; semantic contradictions stay a human gate-challenge. |

package/skills/flow/references/concierge.md

@@ -48,6 +48,7 @@ SKILL.md's Forbidden list). When a brand-new user's ask requires you to draft so
 - design
 - doctor
 - ready
+- gate
 
 **Must-ask — confirm before running** (mutates state, costs money, or is
 operator-authority-only):

package/skills/flow/references/flow-topology.json

@@ -0,0 +1,146 @@
+{
+  "$comment": "flow topology (source of truth once FLOW_GRAPH_EXECUTOR defaults on). Trusted data: loads ONLY from the skill install dir, pin-verified against harness/pins/flow-topology.sha256 (canonical-JSON sha256; regenerate via the command in harness/README.md). cmd is an argv ARRAY (no shell) restricted to the read-only `gate` verb; mutating verbs are lint-banned. Debt-skips are a plan_next traversal semantic (skipped gate = accepted-with-debt) - NO bypass edges belong here. EVERY card edge below is a transition the runner actually emits: dispatch (workspace add) -> review (check) -> merge (workspace remove), with an optional verify-live between review and merge when the operator uses `card done` instead of hand-editing status (workspace remove, executor-proved ancestry). A RED review loops back to review - the agent repairs and re-runs check, which records another review - bounded by max_visits (two strikes, then escalate per auto-run.md). card-abandon is the unmerged-teardown terminal and can follow any card node, because `workspace remove` may happen at any point. There is deliberately no card-build node: the build is LLM work with no deterministic boundary. Edit checklist: run `graph lint`, regenerate the pin, bump topology_version for semantic changes.",
+  "topology_version": 1,
+  "entry": [
+    "stage-00",
+    "card-dispatch"
+  ],
+  "nodes": {
+    "stage-00": {
+      "type": "gate_check",
+      "stage": "00-idea",
+      "cmd": [
+        "flow.sh",
+        "gate",
+        "00-idea"
+      ]
+    },
+    "stage-01": {
+      "type": "gate_check",
+      "stage": "01-research",
+      "cmd": [
+        "flow.sh",
+        "gate",
+        "01-research"
+      ]
+    },
+    "stage-02": {
+      "type": "gate_check",
+      "stage": "02-scope",
+      "cmd": [
+        "flow.sh",
+        "gate",
+        "02-scope"
+      ]
+    },
+    "stage-03": {
+      "type": "gate_check",
+      "stage": "03-prd",
+      "cmd": [
+        "flow.sh",
+        "gate",
+        "03-prd"
+      ]
+    },
+    "stage-04": {
+      "type": "gate_check",
+      "stage": "04-adr",
+      "cmd": [
+        "flow.sh",
+        "gate",
+        "04-adr"
+      ]
+    },
+    "stage-05": {
+      "type": "gate_check",
+      "stage": "05-contract",
+      "cmd": [
+        "flow.sh",
+        "gate",
+        "05-contract"
+      ]
+    },
+    "card-dispatch": {
+      "type": "record_evidence"
+    },
+    "card-review": {
+      "type": "gate_check",
+      "cmd": [
+        "flow.sh",
+        "gate",
+        "--card",
+        "{card}"
+      ],
+      "max_visits": 3
+    },
+    "card-verify-live": {
+      "type": "record_evidence"
+    },
+    "card-merge": {
+      "type": "git_op"
+    },
+    "card-abandon": {
+      "type": "record_evidence"
+    }
+  },
+  "edges": [
+    {
+      "from": "stage-00",
+      "to": "stage-01"
+    },
+    {
+      "from": "stage-01",
+      "to": "stage-02"
+    },
+    {
+      "from": "stage-02",
+      "to": "stage-03"
+    },
+    {
+      "from": "stage-03",
+      "to": "stage-04"
+    },
+    {
+      "from": "stage-04",
+      "to": "stage-05"
+    },
+    {
+      "from": "card-dispatch",
+      "to": "card-review"
+    },
+    {
+      "from": "card-review",
+      "to": "card-verify-live",
+      "when": "review_green"
+    },
+    {
+      "from": "card-verify-live",
+      "to": "card-merge"
+    },
+    {
+      "from": "card-review",
+      "to": "card-review",
+      "when": "review_red"
+    },
+    {
+      "from": "card-dispatch",
+      "to": "card-abandon",
+      "when": "review_red"
+    },
+    {
+      "from": "card-review",
+      "to": "card-abandon",
+      "when": "review_red"
+    },
+    {
+      "from": "card-verify-live",
+      "to": "card-abandon",
+      "when": "review_red"
+    },
+    {
+      "from": "card-review",
+      "to": "card-merge",
+      "when": "review_green"
+    }
+  ]
+}