okstra 0.50.0 → 0.52.0

package/runtime/templates/reports/final-report.template.md

@@ -18,6 +18,7 @@ project-id: {{ frontmatter.projectId | yaml_scalar }}
 taskType: {{ frontmatter.taskType | yaml_scalar }}
 workerId: {{ frontmatter.workerId | yaml_scalar }}
 approved: {{ frontmatter.approved | yaml_scalar }}
+implementation-option: {{ frontmatter.implementationOption | yaml_scalar }}
 ---
 
 # {{ header.taskKey }} - Multi-Agent Cross Verification Final Report

package/runtime/templates/worker-prompt-preamble.md

@@ -8,7 +8,7 @@ It replaces the previous practice of inlining ~80 lines of identical boilerplate
 
 ## Required reading (analysis workers + report-writer worker)
 
-You are required to read every input file enumerated by the dispatcher (the lead's prompt lists them under `[Required reading]`) from the very first character to the very last character before you produce any analysis output. Skimming, partial reads, jumping to a single section, or relying on prior knowledge of a similar file's structure is not acceptable. Each file may contain decisive context that is not surfaced in its summary or first page.
+You are required to read every primary input file enumerated by the dispatcher (the lead's prompt lists them under `[Required reading]`) from the very first character to the very last character before you produce any analysis output. Skimming, partial reads, jumping to a single section, or relying on prior knowledge of a similar file's structure is not acceptable. Source files listed as fallback/evidence paths are read on demand when you need to verify a citation, resolve ambiguity, or inspect material the packet says it omitted.
 
 ### Audience-scoped enumeration (BLOCKING — performance optimization)
 
@@ -16,7 +16,7 @@ Different recipients need different files. Do NOT include `final-report-template
 
 | Recipient | Files included in `[Required reading]` |
 |---|---|
-| Claude / Codex / Gemini analysis workers | task-brief, analysis-profile, analysis-material (if present), reference-expectations, clarification-response (if carry-in) |
+| Claude / Codex / Gemini analysis workers | analysis-packet.md as the primary compact input; task-brief, analysis-profile, analysis-material, reference-expectations, and clarification-response remain source/fallback paths, not automatic first-read files |
 | Report writer worker (Phase 6) | all of the above **plus** the instruction-set-local `final-report-template.md` (phase-stripped) and `final-report-schema.json` (per-task-type excerpt) — NOT the full `templates/reports/...` / `schemas/...` sources |
 | Reverify dispatches (Phase 5.5, lightweight mode) | **do NOT inject `[Required reading]` at all** — see [okstra-convergence](../skills/okstra-convergence/SKILL.md) "Reverify prompt: required-reading suppression". |
 
@@ -25,7 +25,7 @@ Different recipients need different files. Do NOT include `final-report-template
 - Use a single `Read` tool call per file with no `offset` and no `limit`. If a file is genuinely too large for one read, page through with explicit `offset` / `limit` covering the entire file, and state the page boundaries in your Findings.
 - For the carry-in clarification response, walk every row of `## 1. Clarification Items` (`C-001`, `C-002`, ...) in full, including rows whose `User input` cell is blank — a blank `User input` with `Status=open` is itself a signal you must surface. The structural similarity between the prior final report and the upcoming output is NOT a license to skim.
 - Write the Reading Confirmation block to your **audit sidecar** at `runs/<task-type>/worker-results/<worker>-audit-<task-type>-<seq>.md` (sibling to the main worker-results file). One short line per input file confirming end-to-end reading. Do NOT include a `## 0. Reading Confirmation` heading in the main worker-results file — the validator fails worker-results that contain one. If you cannot truthfully confirm a file end-to-end, record a `tool-failure` in the errors sidecar instead of fabricating Findings.
-- Do not collapse multiple input files into a single mental summary before reading them all individually. Each file has its own canonical role: brief = the user's request, profile = the lead's rules for this phase, reference-expectations = ground-truth config/deployment values, clarification-response = prior run's open questions and the user's answers, final-report-template = the structure your eventual writeup must conform to. Conflating them loses signal.
+- Treat `analysis-packet.md` as the canonical primary analysis input. It preserves the source files' frontmatter and extracts the task-specific brief, phase focus, reference expectations, and carry-in clarification rows. If the packet appears incomplete or a finding depends on a source citation, open the corresponding source file and cite it directly.
 
 ---
 

package/runtime/validators/validate-implementation-plan-stages.py

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""S1–S9 checks for the Stage Map structure of an approved
+"""S1–S10 checks for the Stage Map structure of an approved
 implementation-planning final-report.md. Run from prepare_task_bundle
 of `implementation` task or standalone."""
 
@@ -40,7 +40,7 @@ class StageMeta:
 
 @dataclass
 class ValidationError:
-    code: str   # S1..S9
+    code: str   # S1..S10
     stage: int  # 0 = global
     message: str
 
@@ -104,30 +104,36 @@ def _slice_stage_section(text: str, stage_number: int) -> str:
     return text[start: start + nxt.start()] if nxt else text[start:]
 
 
-def _count_effective_steps(section: str) -> int:
+def _effective_step_rows(section: str) -> List[List[str]]:
+    """Effective (non header/divider/comment) rows of the `### Stepwise
+    Execution Order` table, each as a list of stripped cells. Columns are
+    `step | action | files | command | expected`, so action is index 1."""
     m = re.search(r"^###\s+Stepwise Execution Order\b", section, re.M)
     if not m:
-        return 0
+        return []
     body = section[m.end():]
     nxt = re.search(r"^###\s+\w", body, re.M)
     if nxt:
         body = body[: nxt.start()]
-    count = 0
+    rows: List[List[str]] = []
     for line in body.splitlines():
         s = line.strip()
         if not s or s.startswith("<!--"):
             continue
         if not s.startswith("|"):
             continue
-        # Reuse the same header/divider detection as _parse_stage_map:
-        # split on `|`, inspect first non-empty cell.
-        first_cell = s.strip("|").split("|")[0].strip()
+        cells = [c.strip() for c in s.strip("|").split("|")]
+        first_cell = cells[0]
         if first_cell.lower() == "step":
             continue
         if set(first_cell) <= set("-: "):
             continue
-        count += 1
-    return count
+        rows.append(cells)
+    return rows
+
+
+def _count_effective_steps(section: str) -> int:
+    return len(_effective_step_rows(section))
 
 
 def _check_each_stage_section(text: str, stages: List[StageMeta]) -> List[ValidationError]:
@@ -159,6 +165,45 @@ def _check_each_stage_section(text: str, stages: List[StageMeta]) -> List[Valida
     return errs
 
 
+SLICE_VALUE = re.compile(r"^\s*Slice value\s*:\s*(.+?)\s*$", re.M)
+ACCEPTANCE = re.compile(r"^\s*Acceptance\s*:\s*(.+?)\s*$", re.M)
+TDD_EXEMPTION = re.compile(r"^\s*TDD exemption\s*:\s*\S", re.M)
+
+
+def _check_slice_tdd(text: str, stages: List[StageMeta]) -> List[ValidationError]:
+    """S10: each stage declares a vertical slice and follows RED→GREEN ordering.
+
+    S10a — `Slice value:` line with a non-empty value.
+    S10b — `Acceptance:` line with a non-empty value.
+    S10c — first effective Stepwise step's action starts with `RED:` AND some
+           action starts with `GREEN:`, OR a `TDD exemption:` line is present.
+    """
+    errs: List[ValidationError] = []
+    for s in stages:
+        section = _slice_stage_section(text, s.stage_number)
+        if not section:
+            continue   # S3 already reported the missing section
+
+        if not SLICE_VALUE.search(section):
+            errs.append(ValidationError("S10", s.stage_number,
+                "S10a: 'Slice value:' line missing or empty"))
+        if not ACCEPTANCE.search(section):
+            errs.append(ValidationError("S10", s.stage_number,
+                "S10b: 'Acceptance:' line missing or empty"))
+
+        if TDD_EXEMPTION.search(section):
+            continue
+        rows = _effective_step_rows(section)
+        actions = [r[1] for r in rows if len(r) > 1]
+        first_is_red = bool(actions) and actions[0].startswith("RED:")
+        has_green = any(a.startswith("GREEN:") for a in actions)
+        if not (first_is_red and has_green):
+            errs.append(ValidationError("S10", s.stage_number,
+                "S10c: first step action must start with 'RED:' and some "
+                "step action with 'GREEN:', or add a 'TDD exemption:' line"))
+    return errs
+
+
 def _check_depends_on(stages: List[StageMeta]) -> List[ValidationError]:
     errs: List[ValidationError] = []
     valid = {s.stage_number for s in stages}
@@ -229,7 +274,7 @@ def _check_parallel_safety(text: str, stages: List[StageMeta]) -> List[Validatio
 
 
 def collect_validation_errors(text: str) -> List[ValidationError]:
-    """All S1–S9 checks against the report text; empty list means valid.
+    """All S1–S10 checks against the report text; empty list means valid.
 
     S1 (missing `## 5.5 Stage Map` heading) makes the rest unparseable, so it
     short-circuits. Shared by `main()` (CLI / implementation entry) and the
@@ -244,6 +289,7 @@ def collect_validation_errors(text: str) -> List[ValidationError]:
     errors.extend(s2_errs)
     if stages:
         errors.extend(_check_each_stage_section(text, stages))
+        errors.extend(_check_slice_tdd(text, stages))
         errors.extend(_check_depends_on(stages))
         errors.extend(_check_parallel_safety(text, stages))
     return errors

package/src/_python-helper.mjs

@@ -1,12 +1,12 @@
 import { spawn } from "node:child_process";
-import { resolvePaths } from "./paths.mjs";
+import { buildPythonpath, resolvePaths } from "./paths.mjs";
 
 export async function runPythonSnippet({ script, args = [], extraEnv = {} }) {
   const paths = await resolvePaths();
   return new Promise((resolve) => {
     const child = spawn("python3", ["-c", script, ...args], {
       stdio: ["ignore", "pipe", "pipe"],
-      env: { ...process.env, PYTHONPATH: paths.pythonpath, ...extraEnv },
+      env: { ...process.env, PYTHONPATH: buildPythonpath(paths), ...extraEnv },
     });
     let stdout = "";
     let stderr = "";
@@ -22,7 +22,7 @@ export async function runPythonModule({ module, args = [], extraEnv = {}, stdio
   return new Promise((resolve) => {
     const child = spawn("python3", ["-m", module, ...args], {
       stdio: stdio === "capture" ? ["ignore", "pipe", "pipe"] : ["ignore", "inherit", "inherit"],
-      env: { ...process.env, PYTHONPATH: paths.pythonpath, ...extraEnv },
+      env: { ...process.env, PYTHONPATH: buildPythonpath(paths), ...extraEnv },
     });
     let stdout = "";
     let stderr = "";

package/src/context-cost.mjs

@@ -0,0 +1,27 @@
+import { runPythonModule } from "./_python-helper.mjs";
+
+const USAGE = `okstra context-cost — estimate context/read cost for a task bundle
+
+Usage:
+  okstra context-cost <task-root>
+  okstra context-cost <task-key> --project-root <dir>
+  okstra context-cost <task-key> --cwd <dir>
+
+Output: JSON with task file counts, current-run counts, lead Phase 1 read
+surface, analysis-worker initial read surface, and report-writer synthesis
+surface. This is read-only; it never mutates task artifacts.
+`;
+
+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.context_cost",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code ?? 0;
+}

package/src/install.mjs

@@ -22,6 +22,7 @@ const BIN_ENTRYPOINTS = [
   "okstra-codex-exec.sh",
   "okstra-gemini-exec.sh",
   "okstra-trace-cleanup.sh",
+  "okstra-team-reconcile.sh",
   "okstra-central.sh",
   "okstra-token-usage.py",
   "okstra-error-log.py",

package/src/memory.mjs

@@ -46,8 +46,11 @@ It is separate from project-local .okstra task artifacts.
 
 Usage:
   okstra memory add [--content <text> | --file <path>] [options]
-  okstra memory list [--limit <n>] [--tag <tag>] [--type <type>] [--json]
-  okstra memory search <query> [--limit <n>] [--include-archived] [--json]
+  okstra memory list [--limit <n>] [--tag <tag>] [--type <type>]
+                     [--project-group <name>] [--json]
+  okstra memory search <query> [--limit <n>] [--project-group <name>]
+                       [--include-archived] [--json]
+  okstra memory groups [--include-archived] [--json]
   okstra memory show <id> [--json]
   okstra memory archive <id> [--json]
 
@@ -55,7 +58,7 @@ Add options:
   --title <title>       Entry title. Defaults to the first non-empty line.
   --type <type>         context|decision|preference|requirement|person|
                         project-hint|follow-up. Default: context.
-  --scope <scope>       Free-form scope label. Default: global.
+  --project-group <name> Project group label (e.g. acme, private). Default: global.
   --project <id>        Related project id. Repeatable.
   --tag <tag>           Tag. Repeatable or comma-separated.
   --source <source>     Source label. Default: conversation.
@@ -97,7 +100,7 @@ function parseAddArgs(args) {
     file: null,
     title: null,
     type: "context",
-    scope: "global",
+    projectGroup: "global",
     source: "conversation",
     tags: [],
     projects: [],
@@ -110,7 +113,7 @@ function parseAddArgs(args) {
     else if (flag === "--file") opts.file = takeValue(args, i++, flag);
     else if (flag === "--title") opts.title = takeValue(args, i++, flag);
     else if (flag === "--type") opts.type = takeValue(args, i++, flag);
-    else if (flag === "--scope") opts.scope = takeValue(args, i++, flag);
+    else if (flag === "--project-group") opts.projectGroup = takeValue(args, i++, flag);
     else if (flag === "--source") opts.source = takeValue(args, i++, flag);
     else if (flag === "--project") opts.projects.push(takeValue(args, i++, flag));
     else if (flag === "--tag") opts.tags.push(...splitCsv(takeValue(args, i++, flag)));
@@ -128,24 +131,26 @@ function parseAddArgs(args) {
 }
 
 function parseListArgs(args) {
-  const opts = { ...parseGlobalFlags(args), limit: 20, tag: null, type: null };
+  const opts = { ...parseGlobalFlags(args), limit: 20, tag: null, type: null, projectGroup: null };
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === "--json" || flag === "--include-archived") continue;
     if (flag === "--limit") opts.limit = parseLimit(takeValue(args, i++, flag));
     else if (flag === "--tag") opts.tag = takeValue(args, i++, flag);
     else if (flag === "--type") opts.type = takeValue(args, i++, flag);
+    else if (flag === "--project-group") opts.projectGroup = takeValue(args, i++, flag);
     else throw new Error(`unknown flag ${flag}`);
   }
   return opts;
 }
 
 function parseQueryArgs(args) {
-  const opts = { ...parseGlobalFlags(args), limit: 20, query: [] };
+  const opts = { ...parseGlobalFlags(args), limit: 20, query: [], projectGroup: null };
   for (let i = 0; i < args.length; i++) {
     const flag = args[i];
     if (flag === "--json" || flag === "--include-archived") continue;
     if (flag === "--limit") opts.limit = parseLimit(takeValue(args, i++, flag));
+    else if (flag === "--project-group") opts.projectGroup = takeValue(args, i++, flag);
     else if (flag.startsWith("--")) throw new Error(`unknown flag ${flag}`);
     else opts.query.push(flag);
   }
@@ -153,6 +158,19 @@ function parseQueryArgs(args) {
   return { ...opts, query: opts.query.join(" ").trim() };
 }
 
+function parseGroupsArgs(args) {
+  for (const flag of args) {
+    if (flag !== "--json" && flag !== "--include-archived") {
+      throw new Error(`unknown flag ${flag}`);
+    }
+  }
+  return parseGlobalFlags(args);
+}
+
+function entryGroup(entry) {
+  return entry.projectGroup ?? "global";
+}
+
 function parseLimit(raw) {
   const value = Number.parseInt(raw, 10);
   if (!Number.isInteger(value) || value < 1) {
@@ -220,7 +238,7 @@ function buildEntry(opts, content, now) {
     id,
     title,
     type: opts.type,
-    scope: opts.scope,
+    projectGroup: opts.projectGroup,
     source: opts.source,
     tags: [...new Set(opts.tags)],
     relatedProjects: [...new Set(opts.projects)],
@@ -237,7 +255,7 @@ function renderMarkdown(entry, content) {
     `id: ${entry.id}`,
     `createdAt: ${entry.createdAt}`,
     `source: ${entry.source}`,
-    `scope: ${entry.scope}`,
+    `project-group: ${entry.projectGroup}`,
     `type: ${entry.type}`,
     `status: ${entry.status}`,
     `relatedProjects: [${entry.relatedProjects.join(", ")}]`,
@@ -258,6 +276,7 @@ async function confirmSave(entry, content, opts) {
   process.stdout.write(`Memory Book entry:\n`);
   process.stdout.write(`  title: ${entry.title}\n`);
   process.stdout.write(`  type:  ${entry.type}\n`);
+  process.stdout.write(`  group: ${entry.projectGroup}\n`);
   process.stdout.write(`  tags:  ${entry.tags.join(", ") || "(none)"}\n`);
   process.stdout.write(`  text:  ${truncate(content.trim().replace(/\s+/g, " "), 140)}\n`);
   const rl = createInterface({ input, output });
@@ -341,6 +360,7 @@ async function opList(args) {
   const entries = visibleEntries(await readIndex(), opts)
     .filter((entry) => !opts.tag || entry.tags.includes(opts.tag))
     .filter((entry) => !opts.type || entry.type === opts.type)
+    .filter((entry) => !opts.projectGroup || entryGroup(entry) === opts.projectGroup)
     .slice(0, opts.limit);
   if (opts.json) emitJson(entries);
   else process.stdout.write(entries.map(formatEntryLine).join("\n") + (entries.length ? "\n" : ""));
@@ -350,7 +370,9 @@ async function opList(args) {
 async function opSearch(args) {
   const opts = parseQueryArgs(args);
   const needle = opts.query.toLowerCase();
-  const entries = visibleEntries(await readIndex(), opts);
+  const entries = visibleEntries(await readIndex(), opts).filter(
+    (entry) => !opts.projectGroup || entryGroup(entry) === opts.projectGroup,
+  );
   const matches = [];
   for (const entry of entries) {
     if (await entryMatches(entry, needle)) matches.push(entry);
@@ -361,12 +383,27 @@ async function opSearch(args) {
   return 0;
 }
 
+async function opGroups(args) {
+  const opts = parseGroupsArgs(args);
+  const counts = new Map();
+  for (const entry of visibleEntries(await readIndex(), opts)) {
+    const group = entryGroup(entry);
+    counts.set(group, (counts.get(group) ?? 0) + 1);
+  }
+  const groups = [...counts.entries()]
+    .map(([name, count]) => ({ name, count }))
+    .sort((a, b) => b.count - a.count || a.name.localeCompare(b.name));
+  if (opts.json) emitJson(groups);
+  else process.stdout.write(groups.map((g) => `${g.name}  (${g.count})`).join("\n") + (groups.length ? "\n" : ""));
+  return 0;
+}
+
 async function entryMatches(entry, needle) {
   const haystack = [
     entry.id,
     entry.title,
     entry.type,
-    entry.scope,
+    entryGroup(entry),
     entry.source,
     ...entry.tags,
     ...entry.relatedProjects,
@@ -446,6 +483,8 @@ export async function run(args) {
         return await opList(rest);
       case "search":
         return await opSearch(rest);
+      case "groups":
+        return await opGroups(rest);
       case "show":
         return await opShow(rest);
       case "archive":

package/src/uninstall.mjs

@@ -8,6 +8,7 @@ const BIN_ENTRYPOINTS = [
   "okstra-codex-exec.sh",
   "okstra-gemini-exec.sh",
   "okstra-trace-cleanup.sh",
+  "okstra-team-reconcile.sh",
   "okstra-central.sh",
   "okstra-token-usage.py",
   "okstra-error-log.py",