@manhquy/flow-skill 0.1.0-rc.3 → 0.2.0

package/skills/flow/harness/flow_harness.py

@@ -20,6 +20,7 @@ import sys
 import _db
 import _domain as D
 import _presence as P
+import graph_executor as G
 
 
 def _flow_lineage_db(argv):
@@ -58,6 +59,23 @@ def _flow_lineage_db(argv):
 def _maybe_forward_to_rust(argv):
     if os.environ.get("FLOW_HARNESS_BACKEND", "python").lower() != "rust":
         return None
+    # graph verbs are flow-only (schema band 014+); the external harness-cli has no such
+    # surface, and on a FRESH db the lineage sniff below would not refuse yet — so the
+    # never-forward set must be explicit, not inferred from DB state. The verb is the
+    # first NON-OPTION token: `--db <path> graph run` must not slip past an argv[0] check.
+    verb, i = None, 0
+    while i < len(argv):
+        tok = argv[i]
+        if tok == "--db":
+            i += 2
+            continue
+        if tok.startswith("-"):
+            i += 1
+            continue
+        verb = tok
+        break
+    if verb == "graph":
+        return None
     conflict = _flow_lineage_db(argv)
     if conflict:
         sys.stderr.write(
@@ -160,6 +178,21 @@ def cmd_intake(con, a):
     return 0
 
 
+_PROOF_SOURCES = ("card_markdown_gate", "manual", "verify_command")
+_SECRET_RE = re.compile(
+    r"(?i)(token|secret|passwd|password|credential|api[_-]?key|bearer|authorization|-----begin)"
+)
+
+
+def _mask_evidence(text):
+    """Redact secret-shaped free text before durable store (trust-align RT)."""
+    if text is None:
+        return None
+    if _SECRET_RE.search(text):
+        return "***redacted***"
+    return text
+
+
 def cmd_story(con, a):
     if a.story_cmd == "add":
         if a.lane not in D.LANES:
@@ -169,11 +202,58 @@ def cmd_story(con, a):
         print(f"PASS: story {a.id} added (lane={a.lane})")
         return 0
     if a.story_cmd == "update":
+        # Trust boundary (US-101 spirit, flow-native): bare implemented is forbidden.
+        if a.status == "implemented":
+            print(
+                "FAIL: story update --status implemented is rejected.\n"
+                "  Use: story complete --id <id> --proof-source card_markdown_gate|manual|verify_command\n"
+                "  (honest proof provenance; never forge last_verified_result without story verify)"
+            )
+            return 1
         n = _db.update(con, "story", "id", a.id, status=a.status,
                        unit_proof=a.unit, integration_proof=a.integration,
-                       e2e_proof=a.e2e, platform_proof=a.platform, evidence=a.evidence)
+                       e2e_proof=a.e2e, platform_proof=a.platform,
+                       evidence=_mask_evidence(a.evidence))
         print(f"{'PASS' if n else 'FAIL'}: story {a.id} {'updated' if n else 'not found'}")
         return 0 if n else 1
+    if a.story_cmd == "complete":
+        s = _db.one(con, "SELECT * FROM story WHERE id=?", (a.id,))
+        if not s:
+            print(f"FAIL: story {a.id} not found"); return 1
+        src = (a.proof_source or "").strip()
+        if src not in _PROOF_SOURCES:
+            print(
+                "FAIL: --proof-source required: card_markdown_gate|manual|verify_command\n"
+                "  card_markdown_gate = /flow check markdown gate (does NOT set last_verified=pass)\n"
+                "  verify_command     = requires prior story verify pass"
+            )
+            return 1
+        if src == "verify_command":
+            if s.get("last_verified_result") != "pass":
+                print(
+                    f"FAIL: proof-source verify_command requires last_verified_result=pass "
+                    f"(got {s.get('last_verified_result')!r}). Run: story verify --id {a.id}"
+                )
+                return 1
+        # Honest provenance: card/manual never forge last_verified_result=pass
+        ev = _mask_evidence(a.evidence) or s.get("evidence") or ""
+        note = (s.get("notes") or "").strip()
+        prov = f"proof_source={src}"
+        if prov not in note:
+            note = (note + "\n" + prov).strip() if note else prov
+        if src == "card_markdown_gate" and "last_verified_result=pass" not in (note or ""):
+            # explicit honesty marker for auditors
+            note = note + "\nverify_stamp=not_shell"
+        fields = dict(status="implemented", notes=note)
+        if ev:
+            fields["evidence"] = ev
+        # only keep last_verified_* when real verify already passed
+        n = _db.update(con, "story", "id", a.id, **fields)
+        print(
+            f"PASS: story {a.id} complete (status=implemented, proof_source={src})"
+            + ("" if src == "verify_command" else " [no shell-verify stamp]")
+        )
+        return 0 if n else 1
     if a.story_cmd in ("verify", "verify-all"):
         if a.story_cmd == "verify":
             stories = [_db.one(con, "SELECT * FROM story WHERE id=?", (a.id,))]
@@ -594,6 +674,18 @@ def _events_path(a):
     return os.path.join(os.path.dirname(a._db_path), "events.jsonl")
 
 
+def _canon_sink(p):
+    """Spelling-independent name for a sink path, so 'same file' means 'same key'.
+
+    The same directory reaches us under several spellings: a macOS temp root arrives as
+    both /var/... and /private/var/..., and Windows hands back either an 8.3 short name
+    (C:/Users/RUNNER~1/...) or the long one depending on who resolved it. Keying rows on
+    the raw spelling silently splits one sink into two. realpath collapses the symlink and
+    short-name cases; normcase folds Windows separators and case.
+    """
+    return os.path.normcase(os.path.realpath(p))
+
+
 def _global_log_path():
     return os.path.join(os.path.expanduser("~"), ".claude", "flow", "usage.jsonl")
 
@@ -609,21 +701,33 @@ def _coerce_event(o):
 
 
 def cmd_rollup(con, a):
-    srcs = [_events_path(a)]
+    # (path, key) pairs: `path` is the file read; `key` is the rollup_cursor /
+    # UNIQUE(src,line_no) namespace. They differ only for --src ingests, where a
+    # lifecycle-unique key (--src-key-path + --src-key-tag) prevents a RECYCLED worktree
+    # path from silently swallowing lines 1..N of the next lifecycle's sink.
+    if getattr(a, "src", None):
+        kp = getattr(a, "src_key_path", None) or a.src
+        tag = getattr(a, "src_key_tag", None)
+        key = _canon_sink(kp) + ("#" + tag if tag else "")
+        pairs = [(a.src, key)]
+    else:
+        p = _events_path(a)
+        pairs = [(p, p)]
     if getattr(a, "global_", False):
-        srcs.append(_global_log_path())
+        g = _global_log_path()
+        pairs.append((g, g))
     rolled = skipped = 0
     cols = ["src", "line_no"] + list(USAGE_COLS)
     ph = ",".join("?" for _ in cols)
-    for src in srcs:
-        if not os.path.isfile(src):
+    for src_path, src in pairs:
+        if not os.path.isfile(src_path):
             continue
         cur = con.execute("SELECT last_line FROM rollup_cursor WHERE src=?", (src,)).fetchone()
         last = cur[0] if cur else 0
         # errors="replace": a single invalid byte anywhere in a shared, multi-writer log must
         # not abort the WHOLE rollup - it degrades to a per-line json.loads failure below
         # instead (one bad row skipped, not every row on the file).
-        with open(src, "r", encoding="utf-8", errors="replace") as fh:
+        with open(src_path, "r", encoding="utf-8", errors="replace") as fh:
             text = fh.read()
         lines = text.split("\n")
         lines = lines[:-1]  # drop trailing empty (after final \n) or a partial unterminated last line
@@ -668,15 +772,33 @@ def cmd_rollup(con, a):
     return 0
 
 
+def cmd_graph(con, a):
+    return {
+        "run": G.cmd_graph_run, "record": G.cmd_graph_record, "next": G.cmd_graph_next,
+        "resume": G.cmd_graph_resume, "status": G.cmd_graph_status,
+        "abandon": G.cmd_graph_abandon, "gc": G.cmd_graph_gc, "lint": G.cmd_graph_lint,
+        "cards": G.cmd_graph_cards, "root": G.cmd_graph_root,
+        "session": G.cmd_graph_session, "finish": G.cmd_graph_finish,
+    }[a.graph_cmd](con, a)
+
+
 def cmd_usage(con, a):
     src = _global_log_path() if getattr(a, "global_", False) else _events_path(a)
-    w = "WHERE src=?"
+    # `src=?` matches direct-sink rows; the LIKE arm matches lifecycle-keyed ingests
+    # (`rollup --src-key-path <this-sink> --src-key-tag <branch>#<created_at>` — worktree
+    # telemetry merged at
+    # workspace-remove time). Without it those rows would be write-only: invisible to
+    # usage and unreachable by prune.
+    w = "WHERE (src=? OR src LIKE ? || '#%')"
     # Default-exclude throwaway/test runs so the view reflects real builds. COALESCE handles old
     # rows (ephemeral NULL -> 0); the project-name fallback excludes legacy `tmp.*` runs that
     # predate the field (no log rewrite). `--include-ephemeral` shows everything.
     if not getattr(a, "include_ephemeral", False):
         w += " AND NOT (COALESCE(ephemeral,0)=1 OR project LIKE 'tmp.%')"
-    pr = (src,)
+    # Direct-sink rows are keyed by the path as this process spells it, so `src=?` keeps
+    # matching them verbatim; only the lifecycle arm compares canonically, because those
+    # keys are written by whoever called rollup and their spelling is not ours to choose.
+    pr = (src, _canon_sink(src))
     total = con.execute(f"SELECT COUNT(*) FROM usage_event {w}", pr).fetchone()[0]
     if not total:
         if not getattr(a, "summary", False):   # --summary stays silent on no data (recall appends nothing)
@@ -941,8 +1063,12 @@ def cmd_prune(con, a):
         os.replace(tmp, src)            # atomic on the same filesystem
         # line numbers changed -> the mirror + cursor for this sink are stale; reset so the next
         # rollup re-ingests the kept lines as line_no 1..K (UNIQUE(src,line_no) stays consistent).
-        con.execute("DELETE FROM usage_event WHERE src=?", (src,))
-        con.execute("DELETE FROM rollup_cursor WHERE src=?", (src,))
+        # Include lifecycle-keyed ingests for this sink (`<sink>#<branch>#<created_at>`):
+        # their line numbers are unrelated to the rewritten file, but the reset contract is
+        # "mirror rows for this sink are rebuilt from the kept lines", and orphaned keyed
+        # rows would be unreachable forever after.
+        con.execute("DELETE FROM usage_event WHERE src=? OR src LIKE ? || '#%'", (src, _canon_sink(src)))
+        con.execute("DELETE FROM rollup_cursor WHERE src=? OR src LIKE ? || '#%'", (src, _canon_sink(src)))
         con.commit()
         print(json.dumps({"sink": src, "kept": len(kept), "dropped": len(lines) - len(kept)}))
     if getattr(a, "global_", False):
@@ -983,6 +1109,13 @@ def build_parser():
     a2.add_argument("--evidence")
     a3 = pss.add_parser("verify"); a3.add_argument("--id", required=True)
     pss.add_parser("verify-all")
+    # flow-native complete (trust-align D7): not protocol-v1 positional parity
+    ac = pss.add_parser("complete", help="mark implemented with honest proof_source (not bare update)")
+    ac.add_argument("--id", required=True)
+    ac.add_argument("--proof-source", dest="proof_source",
+                    choices=("card_markdown_gate", "manual", "verify_command"),
+                    help="card_markdown_gate never forges last_verified=pass")
+    ac.add_argument("--evidence")
 
     pt = sub.add_parser("trace", help="record an agent task execution trace (auto-scored)")
     pt.add_argument("--summary", required=True); pt.add_argument("--intake", type=int); pt.add_argument("--story", "--card")
@@ -1044,6 +1177,20 @@ def build_parser():
 
     pr = sub.add_parser("rollup", help="ingest JSONL usage sinks into usage_event (idempotent)")
     pr.add_argument("--global", dest="global_", action="store_true", help="also roll up the device-global log")
+    pr.add_argument("--src", help="ingest this JSONL sink instead of the project sink")
+    # Path and tag are SEPARATE flags on purpose. A single pre-joined
+    # "<path>#<branch>#<created_at>" string is not a path, so the Git-Bash/MSYS argument
+    # translation that rewrites POSIX paths into native Windows ones leaves it alone — the
+    # key would then be spelled differently from the sink this python process resolves for
+    # itself, and the rows became write-only: invisible to usage, unreachable by prune.
+    pr.add_argument("--src-key-path", dest="src_key_path",
+                    help="DESTINATION project's events.jsonl path; canonicalized, then used as "
+                         "the cursor/dedupe key prefix so usage/prune group these rows with "
+                         "that project (default: the --src path itself)")
+    pr.add_argument("--src-key-tag", dest="src_key_tag",
+                    help="lifecycle discriminator appended as '#<tag>', e.g. "
+                         "'<branch>#<created_at>' — makes the key unique per worktree "
+                         "lifecycle so a RECYCLED path cannot swallow the next lifecycle's lines")
     pu = sub.add_parser("usage", help="print usage analytics from usage_event")
     pu.add_argument("--global", dest="global_", action="store_true", help="read the device-global log instead of this project")
     pu.add_argument("--json", action="store_true")
@@ -1055,6 +1202,79 @@ def build_parser():
     ppr = sub.add_parser("prune", help="cap each JSONL sink to its last N lines (crash-safe; resets the mirror for that sink)")
     ppr.add_argument("--keep", type=int, help="lines to keep (default 5000)")
     ppr.add_argument("--global", dest="global_", action="store_true", help="also prune the device-global log")
+
+    pg = sub.add_parser("graph", help="graph executor: record/advance journal (flow-owned band 014+)")
+    pgs = pg.add_subparsers(dest="graph_cmd", required=True)
+    g1 = pgs.add_parser("run", help="create an execution; prints its id")
+    g1.add_argument("--project"); g1.add_argument("--kind", required=True, choices=["auto_run", "planning", "card"])
+    g1.add_argument("--topology-version", dest="topology_version", type=int, default=1)
+    g1.add_argument("--topology-hash", dest="topology_hash", default="")
+    g1.add_argument("--story", help="story id tracking handle (TEXT, e.g. C-001)")
+    g2 = pgs.add_parser("record", help="record a step boundary: writes + checkpoint in ONE transaction; prints checkpoint id")
+    g2.add_argument("--execution", required=True); g2.add_argument("--ns", default="")
+    g2.add_argument("--node", required=True)
+    g2.add_argument("--manifest", help="JSON evidence object (parsed + duplicate-key rejected); "
+                                       "prefer the typed flags below so no caller concatenates JSON")
+    g2.add_argument("--gate-exit", dest="gate_exit", type=int, help="gate verdict exit code")
+    g2.add_argument("--gate-cmd", dest="gate_cmd", help="gate command that produced the verdict")
+    g2.add_argument("--card-status", dest="card_status", help="card status token at record time")
+    g2.add_argument("--worktree", help="worktree path (dispatch evidence)")
+    g2.add_argument("--vendor", help="agent vendor (dispatch evidence)")
+    g2.add_argument("--writes", help="JSON array of {task,channel,value} step writes")
+    g2.add_argument("--parent", help="parent checkpoint id (fork chain, e.g. two-strikes attempt 2)")
+    g2.add_argument("--source", default="loop", choices=["input", "loop", "update", "fork"])
+    g2.add_argument("--interrupt", action="store_true", help="open an operator interrupt and pause (exit 3)")
+    g2.add_argument("--prompt", help="interrupt prompt shown to the operator")
+    g2.add_argument("--security-class", dest="security_class", action="store_true")
+    g2.add_argument("--merge", action="store_true",
+                    help="record a merge boundary; the executor COMPUTES the ancestry proof "
+                         "(caller claims are ignored) and records card-abandon when unmerged")
+    g2.add_argument("--branch", help="branch to prove merged (with --merge)")
+    g2.add_argument("--base", help="merge base (default: origin/HEAD, else current branch)")
+    g3 = pgs.add_parser("next", help="next node per topology+journal (exit 3 = complete/paused)")
+    g3.add_argument("--execution", required=True); g3.add_argument("--ns", default="")
+    g3.add_argument("--topology", help="explicit topology JSON path (tests/fixtures; default: "
+                                       "the shipped pin-verified topology + hash policy)")
+    g3.add_argument("--force-retopology", dest="force_retopology", action="store_true",
+                    help="after a skill upgrade changed the topology: fork the chain onto "
+                         "the current topology instead of refusing")
+    g4 = pgs.add_parser("resume", help="resolve an open interrupt (guarded) and resume")
+    g4.add_argument("--execution", required=True)
+    g4.add_argument("--ns", default="", help="select the interrupt by namespace")
+    g4.add_argument("--interrupt-id", dest="interrupt_id",
+                    help="select the exact interrupt (required when several are open)")
+    g4.add_argument("--answer", help='JSON object with a non-empty string "reason"')
+    g4.add_argument("--actor", help="resolving actor id (stored as audit evidence)")
+    g4.add_argument("--target", help="closed-set target the DEBT line must name (C-NNN or NN-stage)")
+    g5 = pgs.add_parser("status", help="execution + latest checkpoint per ns + open interrupts (JSON)")
+    g5.add_argument("--execution", required=True)
+    g6 = pgs.add_parser("abandon", help="terminal-state an execution (kill-at-gate, stale cleanup)")
+    g6.add_argument("--execution", required=True); g6.add_argument("--outcome", help="e.g. killed")
+    gf = pgs.add_parser("finish", help="mark an execution done (lane closed) so the next "
+                                       "feature gets a fresh session and gc can reclaim")
+    gf.add_argument("--execution", required=True); gf.add_argument("--outcome")
+    gf.add_argument("--force", action="store_true", help="close despite open interrupts")
+    g7 = pgs.add_parser("gc", help="purge terminal executions for ONE project (cascade), then "
+                                   "--stale-days marks aged checkpoint-less running as abandoned "
+                                   "(deleted on the NEXT gc, so doctor can surface them first)")
+    g7.add_argument("--stale-days", dest="stale_days", type=int)
+    g7.add_argument("--project", help="project scope (default: basename of FLOW_PROJECT_ROOT)")
+    g9 = pgs.add_parser("cards", help="compile the card DAG: deps-met set + overlap-serialized "
+                                      "ready set + blocked reasons (JSON); rejects dep cycles")
+    g9.add_argument("--active-files", dest="active_files",
+                    help="space/comma list of allowed-file tokens already owned by live worktrees")
+    pgs.add_parser("root", help="print the directory owning this project's durable state "
+                                "(worktree-translated; the one main-tree scope)")
+    gse = pgs.add_parser("session", help="print the project's running auto_run execution, "
+                                         "minting one atomically if absent (no pin file)")
+    gse.add_argument("--project"); gse.add_argument("--no-create", dest="no_create",
+                                                    action="store_true",
+                                                    help="exit 3 instead of minting")
+    gse.add_argument("--kind", choices=["auto_run", "planning"], default="auto_run",
+                     help="session lane: shipping (auto_run) or planning")
+    g8 = pgs.add_parser("lint", help="validate a topology (default: the shipped one incl. pin)")
+    g8.add_argument("--topology", help="explicit topology path (fixtures; skips the pin unless --pin)")
+    g8.add_argument("--pin", help="explicit pin file to verify against")
     return p
 
 
@@ -1078,6 +1298,10 @@ def main(argv):
                 "see harness/README.md for the full contract.\n"
             )
         raise
+    if a.cmd == "graph" and getattr(a, "graph_cmd", "") == "lint":
+        # lint touches no table: skip connect() so CI/linting never mints a DB
+        # (or runs migrations) in the working tree.
+        return G.cmd_graph_lint(None, a) or 0
     con = _db.connect(db_path=a.db)
     a._db_path = a.db or _db.default_db_path()
     dispatch = {
@@ -1086,6 +1310,7 @@ def main(argv):
         "intervention": cmd_intervention, "query": cmd_query,
         "audit": cmd_audit, "propose": cmd_propose,
         "rollup": cmd_rollup, "usage": cmd_usage, "prune": cmd_prune,
+        "graph": cmd_graph,
     }
     try:
         return dispatch[a.cmd](con, a) or 0