okstra 0.111.0 → 0.113.0

package/runtime/python/okstra_ctl/set_work_status.py

@@ -0,0 +1,147 @@
+"""task-manifest.json 의 workStatus 를 갱신하는 단일 CLI 진입점.
+
+okstra-inspect status.4 가 Edit 도구로 하던 수동 JSON 편집(키 순서·개행 보존
+규칙을 프롬프트로 강제)을 CLI 로 수렴시킨다. 직렬화는 render._write_json 과
+동일한 json.dumps(indent=2, ensure_ascii=False) + "\n" 이므로 재렌더와 byte
+규칙이 일치한다. discovery/task-catalog.json 은 여기서 재생성하지 않는다 —
+다음 run 렌더가 manifest 를 재투영할 때까지 stale 할 수 있다.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+from okstra_ctl.ids import slugify_task_segment
+from okstra_project import (
+    ResolverError,
+    StateError,
+    resolve_project_root,
+    resolve_task_reference,
+)
+
+ALLOWED_WORK_STATUSES = ("todo", "in-progress", "blocked", "done")
+
+
+def _emit(payload: dict) -> None:
+    print(json.dumps(payload, ensure_ascii=False, indent=2))
+
+
+def _manifest_path(project_root: Path, entry: dict) -> Path:
+    rel = entry.get("taskManifestPath") or ""
+    if rel:
+        candidate = Path(rel)
+        return candidate if candidate.is_absolute() else project_root / candidate
+    group_seg = entry.get("taskGroupPathSegment") or slugify_task_segment(
+        entry.get("taskGroup", "")
+    )
+    id_seg = entry.get("taskIdPathSegment") or slugify_task_segment(
+        entry.get("taskId", "")
+    )
+    return project_root / ".okstra" / "tasks" / group_seg / id_seg / "task-manifest.json"
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        description="Set a task's user-managed workStatus in task-manifest.json."
+    )
+    parser.add_argument(
+        "token",
+        help="full task-key (<project-id>:<task-group>:<task-id>) or bare task-id",
+    )
+    parser.add_argument("status", choices=ALLOWED_WORK_STATUSES)
+    parser.add_argument(
+        "--note",
+        default=None,
+        help="set workStatusNote; omit to leave any existing note untouched",
+    )
+    parser.add_argument(
+        "--task-group", default="", help="scope a bare task-id 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)")
+    args = parser.parse_args(argv)
+
+    try:
+        project_root = resolve_project_root(explicit_root=args.project_root, cwd=args.cwd)
+    except ResolverError as exc:
+        _emit({"ok": False, "stage": "resolve", "reason": str(exc)})
+        return 2
+
+    token = args.token
+    task_group = args.task_group
+    if token.count(":") == 2:
+        _, key_group, key_id = token.split(":")
+        token = key_id
+        task_group = key_group or task_group
+
+    try:
+        matches = resolve_task_reference(
+            project_root, token, task_group=task_group or None
+        )
+    except StateError as exc:
+        _emit({"ok": False, "stage": "catalog", "reason": str(exc)})
+        return 2
+
+    if not matches:
+        _emit({"ok": False, "stage": "not-found", "token": args.token})
+        return 1
+    if len(matches) > 1:
+        _emit({"ok": False, "stage": "ambiguous", "matches": matches})
+        return 2
+
+    entry = matches[0]
+    manifest_path = _manifest_path(project_root, entry)
+    if not manifest_path.exists():
+        _emit(
+            {
+                "ok": False,
+                "stage": "manifest-missing",
+                "taskKey": entry.get("taskKey", ""),
+                "taskManifestPath": str(manifest_path),
+            }
+        )
+        return 1
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+    except ValueError as exc:
+        _emit(
+            {
+                "ok": False,
+                "stage": "manifest-invalid",
+                "taskManifestPath": str(manifest_path),
+                "reason": str(exc),
+            }
+        )
+        return 1
+
+    previous = manifest.get("workStatus", "")
+    manifest["workStatus"] = args.status
+    manifest["workStatusUpdatedAt"] = datetime.now(timezone.utc).strftime(
+        "%Y-%m-%dT%H:%M:%SZ"
+    )
+    if args.note is not None:
+        manifest["workStatusNote"] = args.note
+    manifest_path.write_text(
+        json.dumps(manifest, indent=2, ensure_ascii=False) + "\n", encoding="utf-8"
+    )
+
+    _emit(
+        {
+            "ok": True,
+            "taskKey": entry.get("taskKey", ""),
+            "previousWorkStatus": previous,
+            "workStatus": args.status,
+            "workStatusUpdatedAt": manifest["workStatusUpdatedAt"],
+            "workStatusNote": manifest.get("workStatusNote", ""),
+            "taskManifestPath": str(manifest_path),
+        }
+    )
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main(sys.argv[1:]))

package/runtime/python/okstra_ctl/team_reconcile.py

@@ -15,7 +15,7 @@ recorded pane — those are left for graceful shutdown.
 CC v2.1.178 removed ``TeamDelete``: the implicit team ends with the session and
 run-end teardown only dismisses teammates via ``shutdown_request``. Reconcile
 keeps the roster honest so a dismissed-but-dead member does not linger as a
-live pill — see _common-contract.md "Run-end teammate teardown".
+live pill — see okstra-lead-contract.md "Run-scoped pane & teammate lifecycle".
 
 Roster resolution (``--project-root``) exists because ``team-state.lead.sessionId``
 is a phase-3 snapshot: Claude Code re-issues the session id across resume /

package/runtime/schemas/final-report-v1.0.schema.json

@@ -696,7 +696,7 @@
                 "properties": {
                   "target": { "type": "string" },
                   "performed": { "type": "string" },
-                  "result": { "type": "string" },
+                  "result": { "enum": ["pass", "fail", "blocked"] },
                   "observed": { "type": "string" }
                 }
               }
@@ -1691,16 +1691,18 @@
         "number": { "type": "integer", "minimum": 1 },
         "tier": { "enum": [1, 2] },
         "command": { "type": "string", "minLength": 1 },
-        "status": { "enum": ["executed", "rejected", "not-configured"] },
+        "status": { "enum": ["executed", "rejected", "not-configured", "env-unavailable"] },
         "exitCode": { "type": ["integer", "null"] },
-        "rejectionReason": { "type": ["string", "null"] },
+        "statusReason": { "type": ["string", "null"] },
         "outputTail": { "type": "string" }
       },
       "allOf": [
         { "if": { "properties": { "status": { "const": "executed" } } },
           "then": { "properties": { "exitCode": { "type": "integer" } } } },
         { "if": { "properties": { "status": { "const": "rejected" } } },
-          "then": { "required": ["rejectionReason"] } }
+          "then": { "required": ["statusReason"] } },
+        { "if": { "properties": { "status": { "const": "env-unavailable" } } },
+          "then": { "required": ["statusReason"] } }
       ]
     },
 

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

@@ -117,26 +117,15 @@ as source material, and never writes them. Decision files (when raised by
   via `implementation`):
   `<PROJECT_ROOT>/.okstra/decisions/<NNNN>-<slug>.md`.
 
-## Step 0: Resolve project root
+## Step 0: Preflight
 
-Reuse the same literal-token-first rule as `okstra-run`. Each command below is a **separate Bash tool call** starting with the literal token `okstra` so the `Bash(okstra:*)` permission match succeeds. Do **not** wrap any of them in `if`, `eval`, `export`, `$(...)`, `VAR=...`, `||`, or `&&`, and do **not** introduce a `$OKSTRA_CMD` variable or an `npx -y okstra@latest` fallback — those leading tokens defeat the permission match and force a confirmation prompt on every call.
+Every Bash command in this skill is a **separate Bash tool call** starting with the literal token `okstra` (never wrapped in `if`/`eval`/`export`/`$(...)`/`VAR=...`/`||`/`&&`/`npx` — a non-literal leading token defeats the `Bash(okstra:*)` permission match).
 
 ```bash
-okstra ensure-installed --runtime claude-code
+okstra preflight --runtime claude-code --json
 ```
 
-If this exits non-zero, tell the user: "okstra not installed — run `/okstra-setup` first." Then stop. Do **not** try to invoke `npx -y okstra@latest ...` as a fallback.
-
-```bash
-okstra check-project --json
-```
-
-Parse the JSON from stdout:
-
-- `ok: true` → use `projectRoot` from the JSON output. Carry it as a literal string into the steps below.
-- `ok: false` → tell the user: "this project has no okstra setup. Run `/okstra-setup` first." Then stop.
-
-> If the `okstra` binary is not on `PATH` at all, the commands above will not run. In that case tell the user verbatim: "okstra not installed — run `/okstra-setup` first." Do **not** try to invoke `npx -y okstra@latest ...` from this skill — `npx` is not on the literal-token allow-list this skill targets and will force a confirmation prompt on every subsequent call.
+Parse the stdout JSON. `ok: true` → carry `projectRoot` as a literal string into the steps below. `ok: false` (or `okstra` not on `PATH` at all) → tell the user: "okstra not set up — run `/okstra-setup` first." Then stop. If the call fails with `unknown command: preflight`, the `okstra` binary on PATH predates this skill — tell the user to update it (`npm i -g okstra@latest`), then stop (`/okstra-setup` does not update the binary). Do **not** try `npx -y okstra@latest ...` as a fallback.
 
 ## Step 1: Choose input source
 
@@ -234,86 +223,15 @@ Order of operations:
    preserved)`).
 
 6. **Sub-ticket / child-issue / sub-task handling — recursive**:
-   - Look at child references in the fetched ticket response:
-     - Linear: `children` / `subIssues` field
-     - Jira: `subtasks` (or `issuelinks` with the `is parent of` relation)
-     - GitHub: `gh issue view --json title,body,comments,labels,state` only
-       returns the issue body and comments — child relations are NOT in that
-       JSON. Resolve children via two paths:
-       1. **task-list parsing** — scan the fetched body and comments for
-          markdown task-list checkboxes referencing other issues
-          (`- [ ] #NNN`, `- [x] owner/repo#NNN`, `- [ ] https://github.com/...`).
-          Capture each as a child candidate.
-       2. **tracked / sub-issue GraphQL** — for GitHub Projects v2
-          "tracked issues" / sub-issue relations, the REST `gh issue view`
-          response does NOT carry them. Query GraphQL explicitly, e.g.
-          `gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){trackedIssues(first:50){nodes{number repository{nameWithOwner}}} subIssues:trackedInIssues(first:50){nodes{number repository{nameWithOwner}}}}}}' -f o=<owner> -f r=<repo> -F n=<num>`.
-          If the GraphQL request fails (auth scope missing, feature
-          unavailable on this repo, network error), **do NOT silently
-          continue with full recursion**. Disable the "Generate the full
-          tree recursively" option for this branch, default to
-          `Parent only; list children in Related Artifacts and Related Task
-          Graph`, and surface the GraphQL failure to the user in one line so
-          they can decide whether to paste child bodies manually.
-     - Notion: child pages / sub-pages
-   - If there is **one or more** child, ask **once at the top parent**:
-     - `AskUserQuestion` (single-select)
-       - **Label**: `"This ticket has sub-tickets. How should the child tree be handled?"`
-       - **Options**:
-         1. `Full tree` (recommended) — walk children, grandchildren, …
-            via BFS/DFS and emit one brief per node.
-         2. `Parent only` — single brief. Children are not fetched; their
-            keys/URLs are recorded under Related Artifacts and as `parent-of`
-            rows in Related Task Graph.
-         3. `Selected` — multi-select the direct children; for each chosen
-            child, apply option-1 policy recursively to that branch.
-   - For options 1 / 3, **recurse into Step 1b sub-steps 3–5** for every
-     descendant. No depth limit. Maintain a visited set of
-     `<tracker>:<ticket-id>` to prevent cycles; on revisit, do not emit a
-     new brief — only add a link back to the existing brief.
-   - **Visited-set across re-runs (rebuild from disk)** — the in-memory
-     visited set is per-run and disappears between invocations. When this
-     skill runs again over a tree that already has briefs on disk, it MUST
-     reseed the visited set by scanning
-     `<PROJECT_ROOT>/.okstra/briefs/<task-group>/` recursively
-     and reading each brief's frontmatter `ticket-id` + `source-type`.
-     Reseed precedence:
-     1. On-disk frontmatter (`ticket-id` ≠ "") populates visited entries
-        as `<source-type>:<ticket-id>` — these win.
-     2. Step 2c collision policy (`Skip` / `Append timestamp` /
-        `Overwrite`) applies to any node whose path is already taken.
-     3. The fresh in-memory walk fills any gaps for tickets not yet on
-        disk.
-     A ticket present on disk is NOT refetched unless the user explicitly
-     answers `Overwrite` for that path.
-   - Each descendant's brief file at depth N is created under
-     `<task-group>/<sub/ nested N times>/<ticket-id>-<file-title>.md` per
-     Step 2b.
-   - Each node's `Related Artifacts` should list:
-     - The parent brief's relative path (`../<ticket-id>-<file-title>.md`)
-     - All direct children briefs' relative paths
-       (`sub/<ticket-id>-<file-title>.md`)
-     bidirectionally. (Non-direct ancestors/descendants are tracked via the
-     frontmatter `parent-id` chain.)
-   - Each generated brief's `Related Task Graph` should contain the same full
-     split topology, not only the current node's direct edges, so downstream
-     phases can start from any child brief without losing order or dependency
-     context. Use one row per source-backed edge with these columns:
-     `From | Relation | To | Direction | Source | Impact`.
-     - `From` / `To` use task key, brief id, tracker id, or URL. The edge
-       direction is `From` → `To`.
-     - `Relation` is one of `parent-of`, `child-of`, `depends-on`, `blocks`,
-       `blocked-by`, `follow-up-of`, `split-from`, `duplicates`, `related-to`.
-     - `Direction` is `directed` for parentage/ordering relations and
-       `undirected` for `duplicates` / `related-to`.
-     - `Source` names the evidence for the edge: tracker linked issue,
-       markdown task-list checkbox, reporter statement, manual split, or prior
-       okstra task.
-     - `Impact` states what the next phase must preserve, such as "run after
-       API contract" or "avoid duplicate implementation".
-     Do not invent graph edges from filename similarity or topic overlap; if a
-     relation is unclear, use `related-to` + `undirected` only when the source
-     explicitly says the items are related.
+   - If the fetched ticket response shows **any** child reference (Linear
+     `children`/`subIssues`, Jira `subtasks`/`issuelinks`, GitHub task-list
+     checkboxes or tracked/sub-issues, Notion child pages), **read
+     `references/tracker-recursion.md` next to this SKILL.md and follow it**
+     before writing any brief — it defines per-tracker child discovery
+     (including the GitHub GraphQL query and its failure handling), the
+     Full tree / Parent only / Selected picker, the cross-run visited-set
+     reseed from on-disk brief frontmatter, and the Related Artifacts /
+     Related Task Graph topology every emitted brief must carry.
    - If there are no children, proceed with a single brief (depth 0).
 
 ### 1c. `Link URL`
@@ -584,13 +502,11 @@ project's domain.
 
 ## Step 4: Fill in missing fields (NO full interview)
 
-> **Verbatim-source rule**: Source Material collected in Step 1 must never
-> be paraphrased, summarized, or restructured. When supplementing missing
-> information, write only into the dedicated `Augmentation` section (see
-> Step 5); never modify Source Material by a single byte. **Anything
-> learned by grilling in this step lands in `Augmentation` or `Open
-> Questions` only.** brief is a pre-discovery artifact, not a PRD —
-> decisions belong to later phases.
+> **Verbatim-source rule** (the first non-negotiable at the top of this
+> file): never modify Source Material by a single byte. **Anything learned
+> by grilling in this step lands in `Augmentation` or `Open Questions`
+> only.** brief is a pre-discovery artifact, not a PRD — decisions belong
+> to later phases.
 
 Inspect the synthesized brief draft. For each REQUIRED section below that is
 empty or trivially thin **after** reading Source Material verbatim, ask **at
@@ -903,72 +819,16 @@ If the list is non-empty, run **one** `AskUserQuestion`:
      `implementation-planning`); see each phase profile's "Brief
      consumption" addendum.
 
-### 6.5c. Batch the questions
-
-For each pending row, formulate one question. Because the
-`AskUserQuestion` tool caps options at 4 per call and questions per call
-also at 4, split into batches of ≤ 4 questions.
-
-**Cap — 12 questions per Step 6.5 run.** When the pending list
-exceeds 12 rows, sort by priority and ask only the top 12 this round:
-
-1. `conversion-block:` rows first (translation failure — highest
-   downstream risk).
-2. `intent-check:` rows next, in the order they appear in `Open
-   Questions`.
-
-Any rows beyond the cap are left unanswered in this run; set
-`reporter-confirmations: partial` in the frontmatter and tell the user
-which rows remain. The next `okstra-brief` re-run (or the downstream
-phase that consumes `Blocks=next-phase`) handles the remainder.
-
-Each question carries:
-
-- The reporter-facing phrasing (plain language, no jargon).
-- A recommended answer drawn from the brief's `intent-inference` /
-  `conversion-block:` content, marked `(Recommended)`.
-- 2–3 alternative options when the answer space is naturally enumerable;
-  otherwise a free-text fallback.
-
-### 6.5d. Record verbatim
-
-Create a new top-level section `## Reporter Confirmations` in the brief
-(if not present) with one subsection per answered row:
-
-```markdown
-## Reporter Confirmations
-
-### RC-1 — <intent-check: or conversion-block: row id / topic>
-- asked: <YYYY-MM-DD HH:MM>
-- linked-row: `<exact Open Questions row text>`
-- answer (verbatim):
-
-  > <reporter's answer, byte-for-byte>
-```
-
-Mark the linked `Open Questions` row by appending `[CONFIRMED <YYYY-MM-DD> → RC-N]` to the end of the row's line. Do NOT delete the row — the
-`CONFIRMED` marker keeps the audit trail intact.
-
-For every `intent-inference` augmentation whose paired `intent-check:`
-was confirmed, add one new line directly below the `> augmented:
-intent-inference …` blockquote:
-
-```
-> confirmed-by-reporter: RC-N — <one-line summary of confirmation>
-```
-
-This converts the inference from "unverified hypothesis" to "verified
-hypothesis" without rewriting the original augmentation.
-
-### 6.5e. Frontmatter state
-
-Update `reporter-confirmations` in the brief frontmatter:
+### 6.5c–e. Collect, record, and set frontmatter state
 
-- `complete` — every pending row was answered.
-- `partial` — some rows answered, some skipped within this run.
-- `skipped` — user picked option 2 in 6.5b.
-- `pending` — should never appear at this point; if it does, treat the
-  brief as not yet handed off and refuse to proceed.
+When 6.5b answered "Yes — collect now", **read
+`references/reporter-confirmations.md` next to this SKILL.md and follow it**:
+it defines the ≤ 4-question batching, the 12-question cap with
+`conversion-block:`-first priority, the `## Reporter Confirmations` RC-N
+record shape with `[CONFIRMED <date> → RC-N]` row markers and
+`> confirmed-by-reporter:` blockquote lines, and the final
+`reporter-confirmations` frontmatter value (`complete` / `partial` /
+`skipped`).
 
 Step 6.5 ends here. The brief now has either zero pending reporter-only
 rows (`complete` / `partial` with remainder in the same file) or an
@@ -1038,11 +898,11 @@ started.
   stays under `<PROJECT_ROOT>/.okstra/` — briefs in `.okstra/briefs/`, glossary
   in `.okstra/glossary.md` (Step 4.5). Paths outside that subtree are read-only
   source material, and only when the reporter cited them.
-- **Verbatim source**: never paraphrase, summarize, restructure, or reorder
-  the Source Material section. Only format conversion (ADF → MD, HTML → MD)
-  is allowed, and the conversion must be annotated in the `format:` meta.
-  Augmentation / interpretation goes only into the `Augmentation` section
-  or a `> augmented:` blockquote inside the required section.
+- **Verbatim source** (the two non-negotiables at the top of this file
+  govern): no line budget overrides them — if source content is large,
+  preserve it exactly as separate `Source Material` entries; if a tool
+  returns a truncated body, ask the user for the missing content or emit a
+  `conversion-block:` row. Never silently excerpt or summarize.
 - **No template author-guidance in the artifact body.** The Step 5
   template carries author guidance in HTML comments (`<!-- ... -->`);
   **strip every such comment when writing the brief** — the final artifact
@@ -1061,10 +921,6 @@ started.
   paste.
 - Never fabricate content for empty sections; use `_(none)_`.
 - Echo each `AskUserQuestion` outcome on one short line.
-- No line budget overrides the verbatim-source rule. If source content is
-  large, preserve it exactly as separate `Source Material` entries; if a
-  tool only returns a truncated body, ask the user for the missing content
-  or emit a `conversion-block:` row. Never silently excerpt or summarize.
 
 ## Failure Modes
 

package/runtime/skills/okstra-brief/references/reporter-confirmations.md

@@ -0,0 +1,71 @@
+# Reporter batch confirmation — collection procedure (Step 6.5c–e)
+
+Read this only when Step 6.5b answered "Yes — collect now" for a non-empty
+pending list of `intent-check:` / `conversion-block:` rows.
+
+## 6.5c. Batch the questions
+
+For each pending row, formulate one question. Because the `AskUserQuestion`
+tool caps options at 4 per call and questions per call also at 4, split into
+batches of ≤ 4 questions.
+
+**Cap — 12 questions per Step 6.5 run.** When the pending list exceeds 12
+rows, sort by priority and ask only the top 12 this round:
+
+1. `conversion-block:` rows first (translation failure — highest downstream
+   risk).
+2. `intent-check:` rows next, in the order they appear in `Open Questions`.
+
+Any rows beyond the cap are left unanswered in this run; set
+`reporter-confirmations: partial` in the frontmatter and tell the user which
+rows remain. The next `okstra-brief` re-run (or the downstream phase that
+consumes `Blocks=next-phase`) handles the remainder.
+
+Each question carries:
+
+- The reporter-facing phrasing (plain language, no jargon).
+- A recommended answer drawn from the brief's `intent-inference` /
+  `conversion-block:` content, marked `(Recommended)`.
+- 2–3 alternative options when the answer space is naturally enumerable;
+  otherwise a free-text fallback.
+
+## 6.5d. Record verbatim
+
+Create a new top-level section `## Reporter Confirmations` in the brief (if
+not present) with one subsection per answered row:
+
+```markdown
+## Reporter Confirmations
+
+### RC-1 — <intent-check: or conversion-block: row id / topic>
+- asked: <YYYY-MM-DD HH:MM>
+- linked-row: `<exact Open Questions row text>`
+- answer (verbatim):
+
+  > <reporter's answer, byte-for-byte>
+```
+
+Mark the linked `Open Questions` row by appending
+`[CONFIRMED <YYYY-MM-DD> → RC-N]` to the end of the row's line. Do NOT delete
+the row — the `CONFIRMED` marker keeps the audit trail intact.
+
+For every `intent-inference` augmentation whose paired `intent-check:` was
+confirmed, add one new line directly below the `> augmented: intent-inference …`
+blockquote:
+
+```
+> confirmed-by-reporter: RC-N — <one-line summary of confirmation>
+```
+
+This converts the inference from "unverified hypothesis" to "verified
+hypothesis" without rewriting the original augmentation.
+
+## 6.5e. Frontmatter state
+
+Update `reporter-confirmations` in the brief frontmatter:
+
+- `complete` — every pending row was answered.
+- `partial` — some rows answered, some skipped within this run.
+- `skipped` — user picked option 2 in 6.5b.
+- `pending` — should never appear at this point; if it does, treat the brief
+  as not yet handed off and refuse to proceed.

package/runtime/skills/okstra-brief/references/tracker-recursion.md

@@ -0,0 +1,90 @@
+# Sub-ticket / child-issue recursion (tracker sources)
+
+Read this only when a fetched tracker ticket shows one or more child references
+(okstra-brief Step 1b sub-step 6). It defines how the child tree is discovered,
+which briefs are emitted, and how re-runs stay idempotent.
+
+## 1. Discover child references per tracker
+
+- Linear: `children` / `subIssues` field.
+- Jira: `subtasks` (or `issuelinks` with the `is parent of` relation).
+- GitHub: `gh issue view --json title,body,comments,labels,state` only returns
+  the issue body and comments — child relations are NOT in that JSON. Resolve
+  children via two paths:
+  1. **task-list parsing** — scan the fetched body and comments for markdown
+     task-list checkboxes referencing other issues (`- [ ] #NNN`,
+     `- [x] owner/repo#NNN`, `- [ ] https://github.com/...`). Capture each as a
+     child candidate.
+  2. **tracked / sub-issue GraphQL** — for GitHub Projects v2 "tracked issues" /
+     sub-issue relations, query GraphQL explicitly, e.g.
+     `gh api graphql -f query='query($o:String!,$r:String!,$n:Int!){repository(owner:$o,name:$r){issue(number:$n){trackedIssues(first:50){nodes{number repository{nameWithOwner}}} subIssues:trackedInIssues(first:50){nodes{number repository{nameWithOwner}}}}}}' -f o=<owner> -f r=<repo> -F n=<num>`.
+     If the GraphQL request fails (auth scope missing, feature unavailable,
+     network error), do NOT silently continue with full recursion: disable the
+     "Full tree" option for this branch, default to `Parent only`, and surface
+     the GraphQL failure to the user in one line so they can decide whether to
+     paste child bodies manually.
+- Notion: child pages / sub-pages.
+
+## 2. Ask once at the top parent
+
+If there is one or more child, `AskUserQuestion` (single-select):
+
+- **Label**: `"This ticket has sub-tickets. How should the child tree be handled?"`
+- **Options**:
+  1. `Full tree` (recommended) — walk children, grandchildren, … via BFS/DFS
+     and emit one brief per node.
+  2. `Parent only` — single brief. Children are not fetched; their keys/URLs are
+     recorded under Related Artifacts and as `parent-of` rows in Related Task
+     Graph.
+  3. `Selected` — multi-select the direct children; for each chosen child,
+     apply option-1 policy recursively to that branch.
+
+For options 1 / 3, recurse into Step 1b sub-steps 3–5 for every descendant. No
+depth limit. Maintain a visited set of `<tracker>:<ticket-id>` to prevent
+cycles; on revisit, do not emit a new brief — only add a link back to the
+existing brief.
+
+## 3. Visited-set across re-runs (rebuild from disk)
+
+The in-memory visited set is per-run. When this skill runs again over a tree
+that already has briefs on disk, reseed the visited set by scanning
+`<PROJECT_ROOT>/.okstra/briefs/<task-group>/` recursively and reading each
+brief's frontmatter `ticket-id` + `source-type`. Reseed precedence:
+
+1. On-disk frontmatter (`ticket-id` ≠ "") populates visited entries as
+   `<source-type>:<ticket-id>` — these win.
+2. Step 2c collision policy (`Skip` / `Append timestamp` / `Overwrite`) applies
+   to any node whose path is already taken.
+3. The fresh in-memory walk fills any gaps for tickets not yet on disk.
+
+A ticket present on disk is NOT refetched unless the user explicitly answers
+`Overwrite` for that path.
+
+## 4. Per-node output
+
+- Each descendant's brief file at depth N is created under
+  `<task-group>/<sub/ nested N times>/<ticket-id>-<file-title>.md` per Step 2b.
+- Each node's `Related Artifacts` lists, bidirectionally:
+  - the parent brief's relative path (`../<ticket-id>-<file-title>.md`)
+  - all direct children briefs' relative paths
+    (`sub/<ticket-id>-<file-title>.md`)
+  (Non-direct ancestors/descendants are tracked via the frontmatter
+  `parent-id` chain.)
+- Each generated brief's `Related Task Graph` contains the same **full split
+  topology**, not only the current node's direct edges, so downstream phases
+  can start from any child brief without losing order or dependency context.
+  One row per source-backed edge with columns
+  `From | Relation | To | Direction | Source | Impact`:
+  - `From` / `To` use task key, brief id, tracker id, or URL; edge direction is
+    `From` → `To`.
+  - `Relation` is one of `parent-of`, `child-of`, `depends-on`, `blocks`,
+    `blocked-by`, `follow-up-of`, `split-from`, `duplicates`, `related-to`.
+  - `Direction` is `directed` for parentage/ordering relations, `undirected`
+    for `duplicates` / `related-to`.
+  - `Source` names the evidence for the edge: tracker linked issue, markdown
+    task-list checkbox, reporter statement, manual split, or prior okstra task.
+  - `Impact` states what the next phase must preserve (e.g. "run after API
+    contract", "avoid duplicate implementation").
+  Do not invent graph edges from filename similarity or topic overlap; if a
+  relation is unclear, use `related-to` + `undirected` only when the source
+  explicitly says the items are related.