okstra 0.108.0 → 0.109.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.108.0",
+  "version": "0.109.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.108.0",
-  "builtAt": "2026-07-02T01:43:53.766Z",
+  "package": "0.109.0",
+  "builtAt": "2026-07-02T07:00:18.587Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/prompts/profiles/_common-contract.md

@@ -16,7 +16,7 @@ profile document.
   - **Phase 4 / 5 (independent analysis)**: analyser workers (`claude`, `codex`, `antigravity` when opted in) produce findings independently and have no access to one another's outputs. `report-writer` does not analyse.
   - **Phase 5.5 (convergence — peer review by workers)**: the lead replays each analyser's findings to the *other* analysers and collects `AGREE` / `DISAGREE` / `SUPPLEMENT` verdicts across up to `effectiveMaxRounds` rounds. Workers act as peer reviewers of each other's findings in this phase; the lead mediates but does not vote. See `prompts/lead/convergence.md` for the round protocol, queue invariants, and final classification (`full-consensus` / `partial-consensus` / `contested` / `worker-unique`). For `requirements-discovery`, `error-analysis`, and `implementation-planning` this phase runs in **adversarial mode** (`convergence.adversarial=true`): verifiers try to refute each finding against its cited evidence and the burden of proof sits on the claim — see that skill's §"Adversarial Verification Mode".
   - Do NOT conclude "no peer review happens" from the roster alone — every profile that lists ≥2 analyser workers runs convergence by default (`convergence.enabled=true` in `task-manifest.json`).
-  - **Pane-budget fallback (tolerance).** If a worker dispatch is rejected with `no room for another tmux split` (or an equivalent teammate-pane creation failure), the lead retries that worker in-process without `run_in_background`; if it was an external CLI worker, the lead instead **substitutes** an in-process `claude` analysis. Either way the lead records the substitution as provider unavailable in the run log and the convergence notes. Completed external-CLI worker trace panes are reclaimed automatically by the `SubagentStop` hook, but okstra cannot directly reclaim the teammate panes the harness creates, so this fallback is the last line of defence against pane-budget exhaustion. (This is a prompt instruction, not a code-enforced gate.)
+  - **provider-unavailable fallback (tolerance).** A worker dispatch can fail to produce a result for two distinct reasons, and both take the same recovery path. (1) **Pane budget:** the dispatch is rejected with `no room for another tmux split` (or an equivalent teammate-pane creation failure). (2) **Sandbox CLI-start failure (non-tmux path):** an external CLI worker wrapper exits non-zero within seconds with empty stdout and its live-log shows `operation not permitted` (e.g. `agy`'s `listen tcp 127.0.0.1:0: bind` under a seatbelt sandbox around a non-tmux subagent's Bash tool). In either case the lead retries that worker in-process without `run_in_background`; if it was an external CLI worker, the lead instead **substitutes** an in-process `claude` analysis. Either way the lead records the substitution as provider unavailable in the run log and the convergence notes. Completed external-CLI worker trace panes are reclaimed automatically by the `SubagentStop` hook, but okstra cannot directly reclaim the teammate panes the harness creates, so this fallback is the last line of defence against pane-budget exhaustion and sandbox-blocked CLI workers. (This is a prompt instruction, not a code-enforced gate.)
 - Tooling — read-only MCP availability (shared):
   - MCP is not implicit okstra context. Query an MCP server only when the task brief explicitly lists it as source material for this run. Any MCP-derived finding MUST cite server, table, and the SELECT used. MCP MUST NEVER be used as a write path — schema/data mutations go through repository migration files reviewed by humans.
 - Resource boundary (shared — artifact-home rule):

package/runtime/python/okstra_ctl/graphify_cmd.py

@@ -0,0 +1,225 @@
+"""okstra-graphify 스코프 래퍼 — resolve_scope + assemble + main 디스패치.
+
+입력은 항상 ``<project_root>/.okstra`` 로, 출력은 ``<project_root>/.okstra/graph``
+로 고정한다. resolve_scope 가 corpus·output 경로의 유일 정의점이며,
+assemble 이 추출 청크를 그래프·리포트로 병합하고, main 이 query/path/explain/
+mcp/wiki 서브커맨드를 디스패치한다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+import okstra_vendor  # noqa: F401  (registers vendored graphify/networkx)
+
+OUT_DIRNAME = "graph"
+
+
+@dataclass(frozen=True)
+class ScopePaths:
+    corpus: Path
+    out_dir: Path
+
+
+def resolve_scope(project_root: Path) -> ScopePaths:
+    root = Path(project_root).resolve()
+    okstra = root / ".okstra"
+    return ScopePaths(corpus=okstra, out_dir=okstra / OUT_DIRNAME)
+
+
+def assemble(project_root: Path) -> Path:
+    sp = resolve_scope(project_root)
+    chunk_dir = sp.out_dir / ".chunks"
+    chunks = sorted(chunk_dir.glob("*.json")) if chunk_dir.is_dir() else []
+    if not chunks:
+        raise FileNotFoundError(f"no extraction chunks under {chunk_dir}")
+
+    merged = {"nodes": [], "edges": []}
+    for c in chunks:
+        data = json.loads(c.read_text(encoding="utf-8"))
+        merged["nodes"].extend(data.get("nodes", []))
+        merged["edges"].extend(data.get("edges", []))
+
+    from graphify.build import build_from_json
+    from graphify.cluster import cluster, score_all
+    from graphify.analyze import god_nodes, surprising_connections, suggest_questions
+    from graphify.report import generate
+    from graphify.export import to_json, to_html
+
+    sp.out_dir.mkdir(parents=True, exist_ok=True)
+    G = build_from_json(merged)
+    communities = cluster(G)
+    cohesion = score_all(G, communities)
+    gods = god_nodes(G)
+    surprises = surprising_connections(G, communities)
+    labels = {cid: f"Community {cid}" for cid in communities}
+    questions = suggest_questions(G, communities, labels)
+    tokens = {"input": 0, "output": 0}
+    report = generate(
+        G, communities, cohesion, labels, gods, surprises,
+        {"warning": "okstra-graphify: .okstra scope"},
+        tokens, str(sp.corpus), suggested_questions=questions,
+    )
+    (sp.out_dir / "GRAPH_REPORT.md").write_text(report, encoding="utf-8")
+    to_json(G, communities, str(sp.out_dir / "graph.json"))
+    to_html(G, communities, str(sp.out_dir / "graph.html"), community_labels=labels or None)
+    return sp.out_dir
+
+
+def _graph_path(project_root: Path) -> Path:
+    return resolve_scope(project_root).out_dir / "graph.json"
+
+
+def _require_graph(project_root: Path) -> Path:
+    gp = _graph_path(project_root)
+    if not gp.exists():
+        raise SystemExit(
+            f"okstra-graphify: no graph at {gp}. Run `okstra graphify build` first."
+        )
+    return gp
+
+
+def _load_graph(graph_path: Path):
+    from networkx.readwrite import json_graph
+    raw = json.loads(Path(graph_path).read_text(encoding="utf-8"))
+    try:
+        return json_graph.node_link_graph(raw, edges="links")
+    except TypeError:
+        return json_graph.node_link_graph(raw)
+
+
+def _run_query(graph_path: Path, question: str, *, budget: int = 2000, use_dfs: bool = False) -> None:
+    # 벤더 __main__.py query 핸들러(1092–1149) 미러: 그래프 경로만 스코프로 교체.
+    from graphify.serve import _score_nodes, _bfs, _dfs, _subgraph_to_text
+    G = _load_graph(graph_path)
+    terms = [t.lower() for t in question.split() if len(t) > 2]
+    scored = _score_nodes(G, terms)
+    if not scored:
+        print("No matching nodes found.")
+        return
+    start = [nid for _, nid in scored[:5]]
+    nodes, edges = (_dfs if use_dfs else _bfs)(G, start, depth=2)
+    print(_subgraph_to_text(G, nodes, edges, token_budget=budget))
+
+
+def _run_path(graph_path: Path, source_label: str, target_label: str) -> None:
+    # 벤더 __main__.py path 핸들러(1169–1217) 미러.
+    from graphify.serve import _score_nodes
+    import networkx as nx
+    G = _load_graph(graph_path)
+    src_scored = _score_nodes(G, [t.lower() for t in source_label.split()])
+    tgt_scored = _score_nodes(G, [t.lower() for t in target_label.split()])
+    if not src_scored:
+        print(f"No node matching '{source_label}' found.")
+        return
+    if not tgt_scored:
+        print(f"No node matching '{target_label}' found.")
+        return
+    src_nid, tgt_nid = src_scored[0][1], tgt_scored[0][1]
+    try:
+        path_nodes = nx.shortest_path(G, src_nid, tgt_nid)
+    except (nx.NetworkXNoPath, nx.NodeNotFound):
+        print(f"No path found between '{source_label}' and '{target_label}'.")
+        return
+    hops = len(path_nodes) - 1
+    segments = []
+    for i in range(len(path_nodes) - 1):
+        u, v = path_nodes[i], path_nodes[i + 1]
+        edata = G.edges[u, v]
+        rel = edata.get("relation", "")
+        conf = edata.get("confidence", "")
+        conf_str = f" [{conf}]" if conf else ""
+        if i == 0:
+            segments.append(G.nodes[u].get("label", u))
+        segments.append(f"--{rel}{conf_str}--> {G.nodes[v].get('label', v)}")
+    print(f"Shortest path ({hops} hops):\n  " + " ".join(segments))
+
+
+def _run_explain(graph_path: Path, label: str) -> None:
+    # 벤더 __main__.py explain 핸들러(1219–1261) 미러.
+    from graphify.serve import _find_node
+    G = _load_graph(graph_path)
+    matches = _find_node(G, label)
+    if not matches:
+        print(f"No node matching '{label}' found.")
+        return
+    nid = matches[0]
+    d = G.nodes[nid]
+    print(f"Node: {d.get('label', nid)}")
+    print(f"  ID:        {nid}")
+    print(f"  Source:    {d.get('source_file', '')} {d.get('source_location', '')}".rstrip())
+    print(f"  Type:      {d.get('file_type', '')}")
+    print(f"  Community: {d.get('community', '')}")
+    print(f"  Degree:    {G.degree(nid)}")
+    neighbors = list(G.neighbors(nid))
+    if neighbors:
+        print(f"\nConnections ({len(neighbors)}):")
+        for nb in sorted(neighbors, key=lambda n: G.degree(n), reverse=True)[:20]:
+            edata = G.edges[nid, nb]
+            rel = edata.get("relation", "")
+            conf = edata.get("confidence", "")
+            print(f"  --> {G.nodes[nb].get('label', nb)} [{rel}] [{conf}]")
+        if len(neighbors) > 20:
+            print(f"  ... and {len(neighbors) - 20} more")
+
+
+def _run_wiki(project_root: Path) -> int:
+    # 벤더 wiki.to_wiki(wiki.py:168) 미러 — 그래프에서 커뮤니티/라벨/god-node 를
+    # 재구성해 <out_dir>/wiki/ 로 기록한다. assemble 과 동일한 재클러스터 경로.
+    from graphify.build import build_from_json
+    from graphify.cluster import cluster, score_all
+    from graphify.analyze import god_nodes
+    from graphify.wiki import to_wiki
+    sp = resolve_scope(project_root)
+    raw = json.loads((sp.out_dir / "graph.json").read_text(encoding="utf-8"))
+    G = build_from_json(raw)
+    communities = cluster(G)
+    cohesion = score_all(G, communities)
+    gods = god_nodes(G)
+    labels = {cid: f"Community {cid}" for cid in communities}
+    return to_wiki(
+        G, communities, str(sp.out_dir / "wiki"),
+        community_labels=labels or None, cohesion=cohesion, god_nodes_data=gods,
+    )
+
+
+def main(argv: list[str]) -> int:
+    parser = argparse.ArgumentParser(prog="okstra graphify")
+    parser.add_argument(
+        "subcmd",
+        choices=["build", "query", "path", "explain", "mcp", "wiki"],
+    )
+    parser.add_argument("rest", nargs="*")
+    parser.add_argument("--project-root", required=True, type=Path)
+    ns = parser.parse_args(argv)
+    root = ns.project_root
+
+    if ns.subcmd == "build":
+        assemble(root)
+        return 0
+    if ns.subcmd == "mcp":
+        from graphify.serve import serve
+        serve(str(_require_graph(root)))
+        return 0
+    if ns.subcmd == "wiki":
+        _require_graph(root)
+        _run_wiki(root)
+        return 0
+
+    gp = _require_graph(root)
+    if ns.subcmd == "query":
+        _run_query(gp, " ".join(ns.rest))
+    elif ns.subcmd == "path":
+        if len(ns.rest) < 2:
+            raise SystemExit("usage: okstra graphify path <ConceptA> <ConceptB> --project-root <dir>")
+        _run_path(gp, ns.rest[0], ns.rest[1])
+    elif ns.subcmd == "explain":
+        _run_explain(gp, " ".join(ns.rest))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/resolve_task_key.py

@@ -1,8 +1,9 @@
-"""bare task-id → task-catalog.json 후보 entry 목록(skill 공용 해석기).
+"""bare token(task-id 또는 task-group) → task-catalog.json 후보 entry 목록.
 
-skill markdown 이 복제하던 "catalog 를 읽어 taskId 를 case-insensitive 매칭 →
-0/1/N 분기" 를 단일 CLI 진입점으로 수렴시킨다. okstra_project.resolve_task_id
-가 SSOT 이고, 이 모듈은 project-root 해석 + JSON 정형화만 한다.
+skill markdown 이 복제하던 "catalog 를 읽어 case-insensitive 매칭 → 0/1/N 분기" 를
+단일 CLI 진입점으로 수렴시킨다. okstra_project.resolve_task_reference 가 SSOT 이고,
+이 모듈은 project-root 해석 + JSON 정형화만 한다. token 은 task-id 와 task-group
+두 축으로 매칭돼 합집합이 나온다(각 entry 의 _matchedVia 로 구분).
 """
 from __future__ import annotations
 
@@ -14,16 +15,21 @@ from okstra_project import (
     ResolverError,
     StateError,
     resolve_project_root,
-    resolve_task_id,
+    resolve_task_reference,
 )
 
 
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(
-        description="Resolve a bare task-id to candidate task-keys from the catalog."
+        description="Resolve a bare token (task-id or task-group) to candidate "
+        "task-keys from the catalog."
+    )
+    parser.add_argument(
+        "task_id", help="bare token: task-id or task-group (case-insensitive)"
+    )
+    parser.add_argument(
+        "--task-group", default="", help="scope the task-id match to this task-group"
     )
-    parser.add_argument("task_id", help="bare task-id (case-insensitive)")
-    parser.add_argument("--task-group", default="", help="scope match to this task-group")
     parser.add_argument("--project-root", default="", help="project root for catalog lookup")
     parser.add_argument("--cwd", default=".", help="cwd for project root resolution")
     parser.add_argument("--json", action="store_true", help="emit JSON (always on)")
@@ -36,7 +42,7 @@ def main(argv: list[str] | None = None) -> int:
         return 2
 
     try:
-        matches = resolve_task_id(
+        matches = resolve_task_reference(
             project_root, args.task_id, task_group=args.task_group or None
         )
     except StateError as exc:

package/runtime/python/okstra_project/__init__.py

@@ -36,6 +36,7 @@ from .state import (
     read_task_manifest,
     resolve_task_id,
     resolve_task_identity,
+    resolve_task_reference,
     slugify,
 )
 
@@ -61,6 +62,7 @@ __all__ = [
     "resolve_project_root",
     "resolve_task_id",
     "resolve_task_identity",
+    "resolve_task_reference",
     "slugify",
     "tasks_root",
     "upsert_project_json",

package/runtime/python/okstra_project/state.py

@@ -187,6 +187,42 @@ def resolve_task_id(
     return matches
 
 
+def resolve_task_reference(
+    project_root: Path,
+    token: str,
+    *,
+    task_group: Optional[str] = None,
+) -> list[dict]:
+    """bare token 을 task-id 또는 task-group 으로 매칭한 후보 목록을 돌려준다.
+
+    resolve_task_id 는 token 을 task-id 로만 봤다. 여기서는 같은 token 을 (a) task-id
+    (선택 task_group 스코프 유지) 와 (b) task-group 두 축으로 매칭해 합집합을 낸다.
+    task-group 매칭은 그 group 의 모든 멤버 task 로 펼쳐진다. 두 축 모두에 걸리면
+    양쪽 후보를 모두 담는다(taskKey 로 dedup). 각 entry 에 어느 축으로 걸렸는지
+    `_matchedVia`("taskId" | "taskGroup") 를 덧붙여 호출자가 picker 에서 구분한다.
+    """
+    wanted = (token or "").strip().lower()
+    if not wanted:
+        return []
+    out: list[dict] = []
+    seen: set[str] = set()
+
+    def _add(entry: dict, matched_via: str) -> None:
+        key = entry.get("taskKey")
+        if not isinstance(key, str) or not key or key in seen:
+            return
+        seen.add(key)
+        out.append({**entry, "_matchedVia": matched_via})
+
+    for entry in resolve_task_id(project_root, token, task_group=task_group):
+        _add(entry, "taskId")
+    for entry in read_task_catalog(Path(project_root)):
+        entry_group = entry.get("taskGroup")
+        if isinstance(entry_group, str) and entry_group.lower() == wanted:
+            _add(entry, "taskGroup")
+    return out
+
+
 def list_project_tasks(
     project_root: Path,
     *,

package/runtime/python/okstra_vendor/__init__.py

@@ -11,6 +11,9 @@ Currently vendored:
   - markupsafe 3.0.3 (BSD-3-Clause) — jinja2 dependency. C extension
     (`_speedups.c` / `_speedups.pyi`) is stripped; the pure-python
     `_native` fallback is used at import time.
+  - networkx (BSD-3-Clause) — graph model + community detection for okstra-graphify.
+  - graphify 0.4.23 (MIT) — knowledge-graph pipeline for okstra-graphify. tree-sitter
+    native bindings are NOT vendored; okstra-graphify only indexes .okstra/ docs.
 
 Source provenance and licenses are preserved verbatim under each
 sub-package. Do not edit vendored files in place — re-vendor from PyPI
@@ -22,8 +25,21 @@ re-routing, those would either fail (no system install) or resolve to
 unrelated user-installed copies. We register the vendored copies in
 `sys.modules` under their canonical top-level names so jinja2's internal
 imports find them deterministically.
+
+networkx and graphify need a stronger mechanism than jinja2/markupsafe.
+Both use *self-referential* absolute imports (networkx's `__init__` does
+`from networkx.lazy_imports import ...`; graphify submodules do `import
+networkx`). Those fire while the package body is still executing, before a
+post-hoc `sys.modules.setdefault` could run — so on a machine that also has
+these libraries pip-installed globally, the self-import would resolve to the
+global copy and cache it under the canonical name. `_vendor_as_toplevel`
+registers the module in `sys.modules` under its canonical name *before*
+executing its body, so every self-referential import resolves back into the
+vendored tree deterministically. networkx is loaded before graphify because
+graphify's cluster/export/serve modules import networkx at module-load time.
 """
 
+import importlib.util as _importlib_util
 import sys as _sys
 
 # Register markupsafe alias BEFORE importing jinja2 — jinja2's __init__
@@ -35,3 +51,28 @@ _sys.modules.setdefault("markupsafe", _markupsafe)
 
 from . import jinja2 as _jinja2  # noqa: E402
 _sys.modules.setdefault("jinja2", _jinja2)
+
+
+def _vendor_as_toplevel(top_name, vendored_name):
+    """Load a vendored sub-package under its canonical top-level name.
+
+    Registers the module in ``sys.modules`` before executing its body so
+    that self-referential absolute imports inside the package resolve to the
+    vendored copy rather than a globally pip-installed one.
+    """
+    if top_name in _sys.modules:
+        return _sys.modules[top_name]
+    vendored_spec = _importlib_util.find_spec(vendored_name)
+    top_spec = _importlib_util.spec_from_file_location(
+        top_name,
+        vendored_spec.origin,
+        submodule_search_locations=list(vendored_spec.submodule_search_locations),
+    )
+    module = _importlib_util.module_from_spec(top_spec)
+    _sys.modules[top_name] = module
+    top_spec.loader.exec_module(module)
+    return module
+
+
+_networkx = _vendor_as_toplevel("networkx", __name__ + ".networkx")
+_graphify = _vendor_as_toplevel("graphify", __name__ + ".graphify")

package/runtime/python/okstra_vendor/graphify/.vendored-version

@@ -0,0 +1 @@
+0.4.23

package/runtime/python/okstra_vendor/graphify/__init__.py

@@ -0,0 +1,28 @@
+"""graphify - extract · build · cluster · analyze · report."""
+
+
+def __getattr__(name):
+    # Lazy imports so `graphify install` works before heavy deps are in place.
+    _map = {
+        "extract": ("graphify.extract", "extract"),
+        "collect_files": ("graphify.extract", "collect_files"),
+        "build_from_json": ("graphify.build", "build_from_json"),
+        "cluster": ("graphify.cluster", "cluster"),
+        "score_all": ("graphify.cluster", "score_all"),
+        "cohesion_score": ("graphify.cluster", "cohesion_score"),
+        "god_nodes": ("graphify.analyze", "god_nodes"),
+        "surprising_connections": ("graphify.analyze", "surprising_connections"),
+        "suggest_questions": ("graphify.analyze", "suggest_questions"),
+        "generate": ("graphify.report", "generate"),
+        "to_json": ("graphify.export", "to_json"),
+        "to_html": ("graphify.export", "to_html"),
+        "to_svg": ("graphify.export", "to_svg"),
+        "to_canvas": ("graphify.export", "to_canvas"),
+        "to_wiki": ("graphify.wiki", "to_wiki"),
+    }
+    if name in _map:
+        import importlib
+        mod_name, attr = _map[name]
+        mod = importlib.import_module(mod_name)
+        return getattr(mod, attr)
+    raise AttributeError(f"module 'graphify' has no attribute {name!r}")