okstra 0.107.2 → 0.109.0

package/runtime/python/okstra_vendor/networkx/utils/tests/test_rcm.py

@@ -0,0 +1,63 @@
+import networkx as nx
+from networkx.utils import reverse_cuthill_mckee_ordering
+
+
+def test_reverse_cuthill_mckee():
+    # example graph from
+    # http://www.boost.org/doc/libs/1_37_0/libs/graph/example/cuthill_mckee_ordering.cpp
+    G = nx.Graph(
+        [
+            (0, 3),
+            (0, 5),
+            (1, 2),
+            (1, 4),
+            (1, 6),
+            (1, 9),
+            (2, 3),
+            (2, 4),
+            (3, 5),
+            (3, 8),
+            (4, 6),
+            (5, 6),
+            (5, 7),
+            (6, 7),
+        ]
+    )
+    rcm = list(reverse_cuthill_mckee_ordering(G))
+    assert rcm in [[0, 8, 5, 7, 3, 6, 2, 4, 1, 9], [0, 8, 5, 7, 3, 6, 4, 2, 1, 9]]
+
+
+def test_rcm_alternate_heuristic():
+    # example from
+    G = nx.Graph(
+        [
+            (0, 0),
+            (0, 4),
+            (1, 1),
+            (1, 2),
+            (1, 5),
+            (1, 7),
+            (2, 2),
+            (2, 4),
+            (3, 3),
+            (3, 6),
+            (4, 4),
+            (5, 5),
+            (5, 7),
+            (6, 6),
+            (7, 7),
+        ]
+    )
+
+    answers = [
+        [6, 3, 5, 7, 1, 2, 4, 0],
+        [6, 3, 7, 5, 1, 2, 4, 0],
+        [7, 5, 1, 2, 4, 0, 6, 3],
+    ]
+
+    def smallest_degree(G):
+        deg, node = min((d, n) for n, d in G.degree())
+        return node
+
+    rcm = list(reverse_cuthill_mckee_ordering(G, heuristic=smallest_degree))
+    assert rcm in answers

package/runtime/python/okstra_vendor/networkx/utils/tests/test_unionfind.py

@@ -0,0 +1,55 @@
+import networkx as nx
+
+
+def test_unionfind():
+    # Fixed by: 2cddd5958689bdecdcd89b91ac9aaf6ce0e4f6b8
+    # Previously (in 2.x), the UnionFind class could handle mixed types.
+    # But in Python 3.x, this causes a TypeError such as:
+    #   TypeError: unorderable types: str() > int()
+    #
+    # Now we just make sure that no exception is raised.
+    x = nx.utils.UnionFind()
+    x.union(0, "a")
+
+
+def test_subtree_union():
+    # See https://github.com/networkx/networkx/pull/3224
+    # (35db1b551ee65780794a357794f521d8768d5049).
+    # Test if subtree unions hare handled correctly by to_sets().
+    uf = nx.utils.UnionFind()
+    uf.union(1, 2)
+    uf.union(3, 4)
+    uf.union(4, 5)
+    uf.union(1, 5)
+    assert list(uf.to_sets()) == [{1, 2, 3, 4, 5}]
+
+
+def test_unionfind_weights():
+    # Tests if weights are computed correctly with unions of many elements
+    uf = nx.utils.UnionFind()
+    uf.union(1, 4, 7)
+    uf.union(2, 5, 8)
+    uf.union(3, 6, 9)
+    uf.union(1, 2, 3, 4, 5, 6, 7, 8, 9)
+    assert uf.weights[uf[1]] == 9
+
+
+def test_unbalanced_merge_weights():
+    # Tests if the largest set's root is used as the new root when merging
+    uf = nx.utils.UnionFind()
+    uf.union(1, 2, 3)
+    uf.union(4, 5, 6, 7, 8, 9)
+    assert uf.weights[uf[1]] == 3
+    assert uf.weights[uf[4]] == 6
+    largest_root = uf[4]
+    uf.union(1, 4)
+    assert uf[1] == largest_root
+    assert uf.weights[largest_root] == 9
+
+
+def test_empty_union():
+    # Tests if a null-union does nothing.
+    uf = nx.utils.UnionFind((0, 1))
+    uf.union()
+    assert uf[0] == 0
+    assert uf[1] == 1

package/runtime/python/okstra_vendor/networkx/utils/union_find.py

@@ -0,0 +1,106 @@
+"""
+Union-find data structure.
+"""
+
+from networkx.utils import groups
+
+
+class UnionFind:
+    """Union-find data structure.
+
+    Each unionFind instance X maintains a family of disjoint sets of
+    hashable objects, supporting the following two methods:
+
+    - X[item] returns a name for the set containing the given item.
+      Each set is named by an arbitrarily-chosen one of its members; as
+      long as the set remains unchanged it will keep the same name. If
+      the item is not yet part of a set in X, a new singleton set is
+      created for it.
+
+    - X.union(item1, item2, ...) merges the sets containing each item
+      into a single larger set.  If any item is not yet part of a set
+      in X, it is added to X as one of the members of the merged set.
+
+      Union-find data structure. Based on Josiah Carlson's code,
+      https://code.activestate.com/recipes/215912/
+      with significant additional changes by D. Eppstein.
+      http://www.ics.uci.edu/~eppstein/PADS/UnionFind.py
+
+    """
+
+    def __init__(self, elements=None):
+        """Create a new empty union-find structure.
+
+        If *elements* is an iterable, this structure will be initialized
+        with the discrete partition on the given set of elements.
+
+        """
+        if elements is None:
+            elements = ()
+        self.parents = {}
+        self.weights = {}
+        for x in elements:
+            self.weights[x] = 1
+            self.parents[x] = x
+
+    def __getitem__(self, object):
+        """Find and return the name of the set containing the object."""
+
+        # check for previously unknown object
+        if object not in self.parents:
+            self.parents[object] = object
+            self.weights[object] = 1
+            return object
+
+        # find path of objects leading to the root
+        path = []
+        root = self.parents[object]
+        while root != object:
+            path.append(object)
+            object = root
+            root = self.parents[object]
+
+        # compress the path and return
+        for ancestor in path:
+            self.parents[ancestor] = root
+        return root
+
+    def __iter__(self):
+        """Iterate through all items ever found or unioned by this structure."""
+        return iter(self.parents)
+
+    def to_sets(self):
+        """Iterates over the sets stored in this structure.
+
+        For example::
+
+            >>> partition = UnionFind("xyz")
+            >>> sorted(map(sorted, partition.to_sets()))
+            [['x'], ['y'], ['z']]
+            >>> partition.union("x", "y")
+            >>> sorted(map(sorted, partition.to_sets()))
+            [['x', 'y'], ['z']]
+
+        """
+        # Ensure fully pruned paths
+        for x in self.parents:
+            _ = self[x]  # Evaluated for side-effect only
+
+        yield from groups(self.parents).values()
+
+    def union(self, *objects):
+        """Find the sets containing the objects and merge them all."""
+        # Find the heaviest root according to its weight.
+        roots = iter(
+            sorted(
+                {self[x] for x in objects}, key=lambda r: self.weights[r], reverse=True
+            )
+        )
+        try:
+            root = next(roots)
+        except StopIteration:
+            return
+
+        for r in roots:
+            self.weights[root] += self.weights[r]
+            self.parents[r] = root

package/runtime/skills/okstra-graphify/SKILL.md

@@ -0,0 +1,161 @@
+---
+name: okstra-graphify
+description: >-
+  Use when the user wants to build, query, or navigate a knowledge graph over an okstra project's own `.okstra/` memory — its reports, decision records, and glossary. Turns that docs corpus into a persistent graph with community detection and an honest EXTRACTED/INFERRED/AMBIGUOUS audit trail, then answers cross-document questions the flat files can't. Trigger phrases include "okstra graphify", "graph the .okstra docs", "build okstra knowledge graph", "query okstra graph", "what connects to X in the okstra docs", "okstra graph 만들어", "결정 레코드 그래프". NOT for graphing arbitrary code or non-okstra folders (that is the standalone /graphify), and NOT for single-task inspection (okstra-inspect) or rollups (okstra-rollup).
+trigger: /okstra-graphify
+---
+
+# OKSTRA Graphify
+
+Build and query a knowledge graph over the project's own okstra memory. The corpus is **fixed** to `<projectRoot>/.okstra` and the outputs land at `<projectRoot>/.okstra/graph/` — the `okstra graphify` CLI enforces both, so this skill never takes a user path argument and never touches files outside `.okstra/`.
+
+Only `.okstra/**/*.md` (final reports, `decisions/*.md`, `glossary.md`, briefs) are indexed. This is docs-only — there is no code AST extraction here (that lives in the standalone `/graphify`).
+
+| Sub-command | What it does |
+|---|---|
+| `build` | Extract entities/relationships from `.okstra` docs (subagent dispatch), then assemble the graph + report + HTML. |
+| `query` | BFS/DFS traversal to answer a broad question over the graph. |
+| `path` | Shortest path between two named concepts. |
+| `explain` | Plain-language explanation of one node and its connections. |
+| `wiki` | Agent-crawlable wiki (`index.md` + one article per community). |
+| `mcp` | Start a stdio MCP server exposing the graph to other agents (opt-in — additionally needs `pip install mcp`). |
+
+## Step 0: Verify okstra runtime + project setup (shared)
+
+Before any sub-command, run each command below as a **separate Bash tool call**. Each starts with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, `&&`, and do **not** introduce an `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — leading tokens defeat the permission match. You (the LLM) inspect each command's output and decide the next step in natural language, never in shell.
+
+1. `okstra ensure-installed --runtime claude-code`
+   If this exits non-zero, tell the user: "okstra not installed — run `/okstra-setup` first." Then stop. Do **not** try `npx -y okstra@latest ...` as a fallback.
+
+2. `okstra check-project --json`
+   Resolves PROJECT_ROOT from the Bash call's cwd, looks for `.okstra/project.json`, and prints `{ok, projectRoot, projectJsonPath, projectId}` (plus a `stage` on failure). Parse the JSON from stdout.
+   - `ok: true` → carry `projectRoot` as a literal string; it is the `--project-root` value for every sub-command below.
+   - `ok: false` → before concluding "no setup", ask whether the user pointed at a specific project directory. If so, re-run `okstra check-project --cwd <that-dir> --json` (the leading `okstra` token keeps the permission match). Only if this **also** returns `ok:false` do you tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
+
+Every `okstra graphify` call below passes `--project-root <projectRoot>` — `--project-root` is REQUIRED and there is no cwd injection; a bare `okstra graphify build` fails with a usage error.
+
+## Step 1: Dispatch by intent
+
+Classify the request into one sub-command using the table above. If ambiguous ("okstra graph 보여줘"), ask which — enumerate the full sub-command table as a numbered text list and let the user pick. `build` is the prerequisite for `query`/`path`/`explain`/`wiki`/`mcp`; if the user asks to query before a graph exists, the CLI will fail cleanly with `no graph … Run \`okstra graphify build\` first` — run `build` first.
+
+---
+
+## build
+
+Two parts: **semantic extraction** (subagents read `.okstra` docs and write chunk JSON), then **assemble** (the CLI clusters and generates outputs).
+
+### build.1 — Detect the corpus
+
+The corpus is fixed to `<projectRoot>/.okstra`. Glob the doc files yourself:
+
+```bash
+find <projectRoot>/.okstra -type f -name '*.md' -not -path '*/graph/*'
+```
+
+Present a clean summary — `Corpus: N markdown files under <projectRoot>/.okstra` (reports, decisions, glossary, briefs). If zero files, stop with "No `.okstra` docs found — run some okstra tasks first, then graph them." The CLI disables graphify's filename-based sensitive-file skip inside `.okstra` (it is okstra's own generated memory, not a secrets store), so do not drop files whose names contain `token`/`secret`.
+
+### build.2 — Semantic extraction (parallel subagents)
+
+**MANDATORY: use the Agent tool.** Reading files one-by-one yourself is forbidden — it is far slower.
+
+1. Split the doc list into chunks of 20-25 files. Group files from the same directory (e.g. all `decisions/`) together so cross-file relationships surface. Print a one-line estimate: `Semantic extraction: ~N files → X agents`.
+2. Call the Agent tool **once per chunk, all in a single response** so they run in parallel. **`subagent_type="general-purpose"`** always — never `Explore` (it is read-only and cannot write chunk files, silently dropping results).
+3. Each subagent writes its fragment to `<projectRoot>/.okstra/graph/.chunks/chunk-NN.json`.
+
+Each subagent receives this exact prompt (substitute FILE_LIST, CHUNK_NUM, TOTAL_CHUNKS, OUT_PATH = `<projectRoot>/.okstra/graph/.chunks/chunk-<NN>.json`):
+
+```
+You are an okstra-graphify extraction subagent over an okstra project's `.okstra` docs
+(final reports, decision records, glossary, briefs). Read the files listed and extract a
+knowledge-graph fragment. Write ONLY valid JSON (schema below) to OUT_PATH — mkdir -p its
+parent first. No explanation, no markdown fences.
+
+Files (chunk CHUNK_NUM of TOTAL_CHUNKS):
+FILE_LIST
+
+Rules:
+- EXTRACTED: relationship explicit in source (a report cites a decision, "see DEC-0003", a task references another task-key).
+- INFERRED: reasonable inference (two reports discuss the same subsystem; a glossary term used in a decision).
+- AMBIGUOUS: uncertain — flag, do not omit.
+Extract named concepts, task-keys, decision ids, glossary terms, subsystems, and rationale
+(sections explaining WHY a decision was made) as nodes; link them with the relations below.
+Add a `semantically_similar_to` INFERRED edge (confidence_score 0.6-0.95) when two concepts in
+this chunk address the same problem without any explicit link. Only when genuinely non-obvious.
+
+confidence_score is REQUIRED on every edge:
+- EXTRACTED → 1.0 always
+- INFERRED → 0.6-0.9 (0.8-0.9 with clear evidence, 0.6-0.7 with some uncertainty)
+- AMBIGUOUS → 0.1-0.3
+
+Node ID: lowercase `[a-z0-9_]` only. Format `{stem}_{entity}` — filename stem + symbol,
+both normalized (non-alphanumeric → `_`).
+
+Output exactly this JSON to OUT_PATH:
+{"nodes":[{"id":"dec_0003_stage_isolation","label":"Human Readable Name","file_type":"document","source_file":"relative/path","source_location":null}],"edges":[{"source":"node_id","target":"node_id","relation":"references|cites|conceptually_related_to|shares_data_with|semantically_similar_to|rationale_for","confidence":"EXTRACTED|INFERRED|AMBIGUOUS","confidence_score":1.0,"source_file":"relative/path","weight":1.0}]}
+```
+
+After all subagents finish, confirm each `chunk-NN.json` exists on disk (the success signal). If a file is missing, warn — the subagent may have been read-only — and re-dispatch with `general-purpose`. If more than half the chunks are missing, stop and tell the user to re-run.
+
+### build.3 — Assemble
+
+```bash
+okstra graphify build --project-root <projectRoot>
+```
+
+This merges every `graph/.chunks/*.json` (`nodes` + `edges`), builds the graph, runs community detection, and writes to `<projectRoot>/.okstra/graph/`:
+- `graph.json` — raw graph data
+- `GRAPH_REPORT.md` — audit report (god nodes, surprising connections, suggested questions, token/confidence audit)
+- `graph.html` — interactive graph, open in any browser
+
+If the CLI errors with `no extraction chunks`, the subagents in build.2 did not write their files — re-dispatch them. After a successful build, paste the God Nodes / Surprising Connections / Suggested Questions sections from `GRAPH_REPORT.md` (not the whole file), then offer to trace the single most interesting suggested question via `query`.
+
+---
+
+## query
+
+```bash
+okstra graphify query "<question>" --project-root <projectRoot>
+```
+
+BFS traversal over the graph; prints the relevant subgraph (nodes, edge relations, confidence tags, source locations). Answer using **only** what the subgraph contains — quote `source_file`/`source_location` when citing a fact, and say so plainly if the graph lacks the information rather than inventing edges.
+
+## path
+
+```bash
+okstra graphify path "<ConceptA>" "<ConceptB>" --project-root <projectRoot>
+```
+
+Prints the shortest path between two named concepts (each hop's relation + confidence). Explain in plain language what each hop means and why the bridge is significant.
+
+## explain
+
+```bash
+okstra graphify explain "<NodeName>" --project-root <projectRoot>
+```
+
+Prints one node's source, type, community, degree, and its connections. Write a 3-5 sentence explanation of what it is, what it connects to, and why — cite source locations.
+
+## wiki
+
+```bash
+okstra graphify wiki --project-root <projectRoot>
+```
+
+Writes an agent-crawlable wiki to `<projectRoot>/.okstra/graph/wiki/` — `index.md` (entry point) plus one article per community. Point the user at `index.md`.
+
+## mcp
+
+```bash
+okstra graphify mcp --project-root <projectRoot>
+```
+
+Starts a stdio MCP server exposing the graph (`query_graph`, `get_node`, `get_neighbors`, `shortest_path`, …) so other agents can query it live. Long-running — the user Ctrl+C's to stop. This sub-command additionally requires `pip install mcp` (opt-in MCP server); the core `build`/`query`/`path`/`explain`/`wiki` sub-commands need no extra install. After doc changes, re-run `build` for LLM semantic re-extraction.
+
+---
+
+## Output Rules (shared)
+
+- Respond concisely in Korean unless the user requests otherwise.
+- Use project-relative paths where possible; outputs live under `<projectRoot>/.okstra/graph/`.
+- Never invent an edge — if unsure, it is AMBIGUOUS. Never hide cohesion/confidence scores.
+- `query`/`path`/`explain`/`wiki`/`mcp` require a built graph; if the CLI says none exists, run `build` first.

package/runtime/skills/okstra-inspect/SKILL.md

@@ -166,9 +166,9 @@ Accepted `<status>` values: `todo`, `in-progress`, `blocked`, `done`.
 **Procedure:**
 
 1. **Validate status value.** If not in the enum, output an error and the allowed values list. Do not modify any file.
-2. **Resolve the task** with the shared resolver (pass `--task-group` when the user gave one — it scopes the match case-insensitively):
+2. **Resolve the task** with the shared resolver. The token may be a task-id or a task-group (matched on both axes; a group expands to its member tasks). `--task-group` additionally scopes the task-id match case-insensitively:
    ```bash
-   okstra resolve-task-key <task-id> [--task-group <task-group>] --project-root <projectRoot> --json
+   okstra resolve-task-key <token> [--task-group <task-group>] --project-root <projectRoot> --json
    ```
    Branch on `matches[]`: single → proceed. Multiple → list candidates and ask the user to retry with the explicit form (`okstra status set <task-group> <TASK-ID> <status>`). None → `<TASK-ID>를 찾을 수 없습니다.` and stop.
 3. **Open the matching `task-manifest.json`** at `.okstra/tasks/<task-group-segment>/<task-id-segment>/task-manifest.json`. Assemble the path from the catalog entry's `taskGroupPathSegment` and `taskIdPathSegment` fields (filesystem-safe segments emitted by the renderer) — NOT from the raw user-supplied strings, which may differ in case or contain characters normalized when the manifest was created. Prefer the `taskManifestPath` field directly when present.
@@ -363,7 +363,7 @@ Aggregate elapsed work time for a task, grouped by **task type** and broken down
 
 ### time.1 — Resolve the task-key
 
-Same standard as `cost.1`: full task-key → use directly; bare task-id → `okstra resolve-task-key <task-id> --project-root <projectRoot> --json` and branch on `matches[]` (0 = not found, 1 = use, N = 3-option picker). If no okstra history exists, say `No okstra history found. Run /okstra-run first.`
+Same standard as `cost.1`: full task-key → use directly; bare token (task-id or task-group) → `okstra resolve-task-key <token> --project-root <projectRoot> --json` and branch on `matches[]` (0 = not found, 1 = use, N = 3-option picker). If no okstra history exists, say `No okstra history found. Run /okstra-run first.`
 
 ### time.2 — Fetch aggregated data
 
@@ -421,7 +421,7 @@ Read-only estimate of how much file/context surface a prepared task bundle asks
 Accepted target forms:
 
 1. Full task-key: `<project-id>:<task-group>:<task-id>`.
-2. Task id only, e.g. `DEV-9184`.
+2. Bare token — a task-id (e.g. `DEV-9184`) **or** a task-group (e.g. `PROD`).
 3. Task root path, e.g. `<projectRoot>/.okstra/tasks/<group>/<task-id>`.
 
 If the user gives a task root path, run `okstra context-cost <absolute-or-user-provided-path>` directly.
@@ -432,16 +432,16 @@ If the user gives a full task-key, run:
 okstra context-cost <task-key> --project-root <projectRoot>
 ```
 
-If the user gives only a task id, resolve it to a task-key with the shared resolver (SSOT — `scripts/okstra_ctl/resolve_task_key.py` / `okstra_project.resolve_task_id`):
+If the user gives a bare token, resolve it with the shared resolver (SSOT — `scripts/okstra_ctl/resolve_task_key.py` / `okstra_project.resolve_task_reference`). The resolver matches the token as a task-id **and** as a task-group, unioning both (a group expands to its member tasks); each entry carries `_matchedVia` (`"taskId"` | `"taskGroup"`):
 
 ```bash
-okstra resolve-task-key <task-id> --project-root <projectRoot> --json
+okstra resolve-task-key <token> --project-root <projectRoot> --json
 ```
 
 Branch on the stdout JSON `matches[]` — this **standard 0/1/N rule** is referenced by `errors`/`recap` below:
 - **0개** → report the task cannot be found. Do not guess.
 - **1개** → use that entry's `taskKey`.
-- **N개** → list the candidate `taskKey`s (with `updatedAt`) and ask via a 3-option picker (1~2 추천 + `직접 입력`), then use the chosen `taskKey`.
+- **N개** → list the candidate `taskKey`s (with `updatedAt`, and `_matchedVia` so the user sees which came from a task-id vs a task-group) and ask via a 3-option picker (1~2 추천 + `직접 입력`), then use the chosen `taskKey`.
 
 If the user asks generally ("컨텍스트 비용 보여줘") and does not name a task:
 
@@ -605,9 +605,11 @@ Aggregate a task's okstra-run error logs (`runs/*/logs/errors-*.jsonl`, lead-obs
 Accepted target forms (same as `cost`):
 
 1. Full task-key: `<project-id>:<task-group>:<task-id>`.
-2. Task id only — resolve via `okstra resolve-task-key <task-id> --project-root <projectRoot> --json` and branch on `matches[]` using the standard 0/1/N rule from `cost.1` (0 = not found, 1 = use, N = picker).
+2. Bare token (task-id or task-group) — resolve via `okstra resolve-task-key <token> --project-root <projectRoot> --json` and branch on `matches[]` using the standard 0/1/N rule from `cost.1` (0 = not found, 1 = use, N = picker).
 3. Task root path.
 
+사용자가 task 를 지정하지 않고 그냥 에러 리포트를 요청하면, `cost.1` 과 동일한 no-task fallback 을 적용한다 — 플레이스홀더 형식만 나열하고 되묻지 않는다: `.okstra/discovery/task-catalog.json` 을 읽어 task 가 1개면 그대로 사용하고, 여러 개면 `updatedAt` 최신 10개를 실제 task-key 로 나열해 물어본다(추측 금지).
+
 ### errors.2 — Run the renderer
 
 Use the CLI output as the source of truth:
@@ -708,7 +710,13 @@ task-id 하나에 쌓인 `.okstra` 산출물 위에서 (a) 처리 전/후 요약
 
 ### recap.1 — Resolve target
 
-`cost` / `errors` 와 동일한 3형식: ① full task-key, ② task-id 만(→ `okstra resolve-task-key <task-id> --project-root <projectRoot> --json`; `cost.1` 의 표준 0/1/N 분기), ③ task-root path.
+`cost` / `errors` 와 동일한 3형식: ① full task-key, ② bare token(task-id 또는 task-group → `okstra resolve-task-key <token> --project-root <projectRoot> --json`; `cost.1` 의 표준 0/1/N 분기), ③ task-root path.
+
+사용자가 task 를 지정하지 않고 그냥 recap 을 요청하면(예: "이 작업 요약해줘"), `cost.1` 과 동일한 no-task fallback 을 적용한다 — 절대 `<task-group>` 같은 플레이스홀더 형식만 나열하고 되묻지 않는다:
+
+1. `.okstra/discovery/task-catalog.json` 을 읽는다.
+2. task 가 정확히 1개면 그 task 를 그대로 사용한다.
+3. 여러 개면 `updatedAt` 최신 10개를 실제 task-key 로 나열하고 어느 task 인지 물어본다(추측 금지).
 
 ### recap.2 — Assemble the before/after summary
 

package/runtime/templates/reports/settings.template.json

@@ -29,6 +29,10 @@
       "Bash(docker:*)"
     ]
   },
+  "sandbox": {
+    "network": { "allowLocalBinding": true },
+    "filesystem": { "allowWrite": ["~/.gemini", "~/.codex"] }
+  },
   "hooks": {
     "PreToolUse": [
       {

package/runtime/validators/forbidden_actions.py

@@ -122,13 +122,19 @@ def scan_forbidden_actions(
     """Return human-readable violation strings (empty = clean)."""
     _ensure_token_usage_importable()
     from okstra_token_usage.claude import find_claude_team_sessions
-    from okstra_token_usage.collect import resolve_run_window, resolve_team_name
+    from okstra_token_usage.collect import (
+        resolve_run_window,
+        resolve_team_needles_with_source,
+    )
 
     since, until = resolve_run_window(team_state_path, team_state)
     lead_sid = (team_state.get("lead") or {}).get("sessionId") or ""
+    team_needles, _needle_source = resolve_team_needles_with_source(
+        team_state, project_root, since, until, projects_root=claude_projects_dir
+    )
     sessions = find_claude_team_sessions(
         project_root,
-        resolve_team_name(team_state),
+        team_needles,
         lead_sid,
         projects_root=claude_projects_dir,
     )

package/runtime/validators/validate_session_conformance.py

@@ -33,7 +33,13 @@ _WORKER_DISPATCH_MODES = {"cli-wrapper", "mixed", "tmux-pane"}
 _ATTEMPTED_STATUSES = {"completed", "timeout", "error"}
 
 # lead 의 체크포인트 라인 — assistant text 블록 안에서 line-anchored 로만 인정.
-_PROGRESS_LINE_RE = re.compile(r"^PROGRESS:[ \t]+(?P<phase>\S+)(?P<rest>.*)$", re.MULTILINE)
+# lead 는 계약상 raw 로 emit 해야 하지만 실측(dev-9902)에서 `` `PROGRESS: ...` ``
+# 인라인 코드나 코드펜스로 감싸 emit 하는 경우가 있어, 라인 양끝의 backtick 과
+# 선행 들여쓰기를 허용한다. phase 는 backtick 을 포함하지 않는다.
+_PROGRESS_LINE_RE = re.compile(
+    r"^[ \t]*`*[ \t]*PROGRESS:[ \t]+(?P<phase>[^\s`]+)(?P<rest>[^`\n]*)`*[ \t]*$",
+    re.MULTILINE,
+)
 
 # claude-worker audit 사이드카의 heartbeat 라인 (claude-worker.md "Heartbeat").
 _HEARTBEAT_LINE_RE = re.compile(
@@ -139,7 +145,8 @@ def _scan_one_jsonl(
                     continue
                 if block.get("type") == "text":
                     for m in _PROGRESS_LINE_RE.finditer(block.get("text") or ""):
-                        progress.append((ts, m.group("phase"), m.group(0).strip()))
+                        line = f"PROGRESS: {m.group('phase')}{m.group('rest')}".rstrip()
+                        progress.append((ts, m.group("phase"), line))
                 elif block.get("type") == "tool_use" and block.get("name") == "Read":
                     base = Path(str((block.get("input") or {}).get("file_path") or "")).name
                     if base in _SIDECAR_BASENAMES:
@@ -160,14 +167,29 @@ def _collect_lead_evidence(
     agentName 없음)를 흡수한다 — worker 세션은 agentName 이 있어 자연 배제된다.
     """
     from okstra_token_usage.claude import find_claude_team_sessions
-    from okstra_token_usage.collect import resolve_run_window, resolve_team_name
+    from okstra_token_usage.collect import (
+        resolve_run_window,
+        resolve_team_needles_with_source,
+    )
     from okstra_token_usage.paths import claude_project_dir
 
     since, until = resolve_run_window(team_state_path, team_state)
     lead_sid = (team_state.get("lead") or {}).get("sessionId") or ""
+    team_needles, _needle_source = resolve_team_needles_with_source(
+        team_state, project_root, since, until, projects_root=projects_root
+    )
     sessions = find_claude_team_sessions(
-        project_root, resolve_team_name(team_state), lead_sid, projects_root=projects_root
+        project_root, team_needles, lead_sid, projects_root=projects_root
     )
+    # `claude --resume` 로 fork 되거나 leadSessionIds[] 에 기록된 lead 세대는
+    # team 태그 needle 로 안 잡힐 수 있어 명시적으로 후보에 추가한다.
+    proj_dir = claude_project_dir(project_root, projects_root)
+    for sid in (team_state.get("leadSessionIds") or []):
+        if not isinstance(sid, str) or not sid:
+            continue
+        candidate = proj_dir / f"{sid}.jsonl"
+        if candidate.is_file():
+            sessions.setdefault(sid, candidate)
     evidence = _LeadEvidence(window=(since, until))
     for sid, path in sorted(sessions.items()):
         progress, reads, agent_name = _scan_one_jsonl(path, since, until)
@@ -178,7 +200,6 @@ def _collect_lead_evidence(
         for base, ts_list in reads.items():
             evidence.sidecar_reads.setdefault(base, []).extend(ts_list)
     if not evidence.scanned_files:
-        proj_dir = claude_project_dir(project_root, projects_root)
         return None, (
             f"lead session jsonl not found under {proj_dir} "
             f"(lead.sessionId={lead_sid or '<empty>'}) — PROGRESS checkpoint / "

package/src/cli-registry.mjs

@@ -173,6 +173,13 @@ export const COMMAND_REGISTRY = [
     category: "introspection",
     summary: ["Manage cross-project okstra tasks"],
   },
+  {
+    name: "graphify",
+    module: "./commands/graphify.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Build/query a .okstra-scoped knowledge graph"],
+  },
   {
     name: "worktree-lookup",
     module: "./commands/execute/worktree-lookup.mjs",

package/src/commands/graphify.mjs

@@ -0,0 +1,32 @@
+import { runPythonModule } from "../lib/python-helper.mjs";
+
+const USAGE = `okstra graphify — build/query a .okstra-scoped knowledge graph
+
+Usage:
+  okstra graphify build   --project-root <dir> [options]
+  okstra graphify query   --project-root <dir> [options]
+  okstra graphify path    --project-root <dir> [options]
+  okstra graphify explain --project-root <dir> [options]
+  okstra graphify mcp     --project-root <dir> [options]
+  okstra graphify watch   --project-root <dir> [options]
+  okstra graphify wiki    --project-root <dir> [options]
+
+--project-root <dir> targets the project whose .okstra/ subtree holds the graph.
+All arguments are forwarded to the python wrapper (okstra_ctl.graphify_cmd);
+--project-root is required by the wrapper, so a bare 'okstra graphify build'
+fails cleanly with an argparse usage error.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.graphify_cmd",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}

package/src/commands/lifecycle/doctor.mjs

@@ -113,6 +113,14 @@ async function checkPythonImport(moduleName, pythonpath) {
   return { ok: true, detail: `${moduleName} importable` };
 }
 
+async function checkGraphifyVendor() {
+  const r = await runPythonSnippet({ script: "import okstra_vendor, graphify, networkx" });
+  if (r.code !== 0) {
+    return { ok: false, detail: `vendored graphify import failed: ${r.stderr.trim().split("\n").pop()}` };
+  }
+  return { ok: true, detail: "okstra_vendor, graphify, networkx importable" };
+}
+
 async function checkBashEntry(binDir, name) {
   const p = join(binDir, name);
   if (!(await fileExists(p))) return { ok: false, detail: `missing ${p}` };
@@ -218,6 +226,7 @@ export async function run(args) {
     await check("python3", checkPython3),
     await check("okstra_project import", () => checkPythonImport("okstra_project", paths.pythonpath)),
     await check("okstra_ctl import", () => checkPythonImport("okstra_ctl", paths.pythonpath)),
+    await check("graphify vendor import", checkGraphifyVendor),
     await check("agents dir", async () =>
       (await fileExists(paths.agents))
         ? { ok: true, detail: paths.agents }

package/src/lib/skill-catalog.mjs

@@ -14,6 +14,7 @@ export const USER_SKILL_NAMES = Object.freeze([
   "okstra-rollup",
   "okstra-schedule",
   "okstra-container-build",
+  "okstra-graphify",
 ]);
 
 // Names okstra used to install as skills before they were renamed or moved