okstra 0.51.0 → 0.53.0

package/runtime/templates/reports/final-verification-input.template.md

@@ -29,15 +29,18 @@ taskType: "{{FM_TASK_TYPE}}"
 - What was supposed to be delivered?
 - What is the intended acceptance decision?
 
+## 검증 모드
+
+- 기본은 **전체-task** 검증입니다(`--stage auto`): 모든 Stage Map stage 가 구현·머지된 뒤 한 번 실행합니다.
+- 특정 stage 만 격리 검증하려면 `--stage N` 으로 **단독-stage** 모드를 씁니다(release-handoff 진입 불가, 부분 검증).
+- worktree / base / head 는 okstra 가 registry 와 `consumers.jsonl` 에서 자동 해소하므로 이 입력서에 수동 기입하지 않습니다.
+
 ## Source Implementation Report
 
 - Path (project-relative) to the originating `implementation` final-report:
-- Worktree / checkout path that final-verification must inspect:
-- Implementation base ref (`<base>` for `git diff --stat <base>..HEAD`):
-- Implementation head SHA expected at verification start:
 - Quoted `Commit list` / `Diff summary` excerpt from the implementation report:
 
-> If this section is empty, points to a missing report, or names a checkout that does not match the implementation report's commit list / diff summary, final-verification MUST end with status `blocked` and route back to `implementation` or `implementation-planning`. Do not verify an ambiguous target.
+> 보고서 경로가 비거나 누락된 보고서를 가리키면 final-verification 은 status `blocked` 으로 끝내고 `implementation` 또는 `implementation-planning` 으로 라우팅합니다. 검증 대상(worktree/base/head)은 okstra 가 자동 해소하므로 수동 기입이 어긋나 막히는 일은 없습니다.
 
 ## Requirement Coverage Source
 
@@ -87,7 +90,7 @@ taskType: "{{FM_TASK_TYPE}}"
 
 ## Questions for Analysers
 
-1. Does the verification target (head SHA / diff stat) match the implementation report's commit list and diff summary?
+1. Did your analysis run against the injected `VERIFICATION_TARGET` (base / head SHA / worktree), and does the diff at that target fully cover the stage(s) under verification? (A head you cannot confirm against the injected target is a `tool-failure`, not a silent proceed.)
 2. For each requirement / acceptance criterion, what exact artifact (commit SHA, test output, log line, config value) proves coverage?
 3. Are there any acceptance blockers?
 4. What residual risks remain?

package/runtime/templates/reports/i18n/en.json

@@ -134,6 +134,8 @@
   },
   "finalVerification": {
     "validationEvidenceAside": "requirements coverage",
-    "columnRequirement": "Requirement (plan/brief citation)"
+    "columnRequirement": "Requirement (plan/brief citation)",
+    "verificationScope": "Verification scope",
+    "stageReportsLabel": "Source implementation reports (per stage)"
   }
 }

package/runtime/templates/reports/i18n/ko.json

@@ -134,6 +134,8 @@
   },
   "finalVerification": {
     "validationEvidenceAside": "요구사항 커버리지",
-    "columnRequirement": "Requirement (plan/brief 인용)"
+    "columnRequirement": "Requirement (plan/brief 인용)",
+    "verificationScope": "검증 범위",
+    "stageReportsLabel": "stage 별 구현 리포트"
   }
 }

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/runtime/validators/validate-run.py

@@ -313,6 +313,18 @@ def extract_contract(
     }
 
 
+def effective_run_task_type(run_manifest: dict, task_manifest: dict) -> str:
+    """Return the task type for the specific run being validated.
+
+    `task-manifest.json` is mutable lifecycle state and may point at a later
+    phase after the user has continued the task. A final-report belongs to the
+    immutable run-manifest, so run-manifest wins here.
+    """
+    return str(
+        run_manifest.get("taskType") or task_manifest.get("taskType") or ""
+    ).strip()
+
+
 def validate_team_state(
     team_state: dict, project_root: Path, contract: dict, failures: list[str]
 ) -> None:
@@ -857,6 +869,7 @@ PLANNING_REQUIRED_SECTIONS = (
     "Dependency",
     "Validation Checklist",
     "Rollback",
+    "Requirement Coverage",
     "Plan Body Verification",
 )
 
@@ -951,6 +964,11 @@ _APPROVED_FRONTMATTER_RE = re.compile(
     re.IGNORECASE | re.MULTILINE,
 )
 _FRONTMATTER_BLOCK_RE = re.compile(r"\A---\n(.*?)\n---\n", re.DOTALL)
+_REQUIREMENT_COVERAGE_HEADING_RE = re.compile(
+    r"^###[ \t]+(?:5\.5\.8[ \t]+)?Requirement Coverage\b",
+    re.IGNORECASE | re.MULTILINE,
+)
+_NEXT_THIRD_LEVEL_HEADING_RE = re.compile(r"^###[ \t]+", re.MULTILINE)
 
 
 def _extract_final_verdict_token(content: str) -> str | None:
@@ -968,6 +986,115 @@ def _extract_final_verdict_token(content: str) -> str | None:
     return match.group("value")
 
 
+def _split_markdown_row(line: str) -> list[str]:
+    stripped = line.strip()
+    if stripped.startswith("|"):
+        stripped = stripped[1:]
+    if stripped.endswith("|"):
+        stripped = stripped[:-1]
+    return [cell.strip().strip("`").strip() for cell in stripped.split("|")]
+
+
+def _is_markdown_separator(line: str) -> bool:
+    stripped = line.strip()
+    if not stripped.startswith("|"):
+        return False
+    for cell in stripped.strip("|").split("|"):
+        if not re.fullmatch(r"\s*:?-{2,}:?\s*", cell):
+            return False
+    return True
+
+
+def _append_requirement_coverage_failures(
+    content: str,
+    gate_value: str,
+    failures: list[str],
+) -> None:
+    """Validate implementation-planning §5.5.8 requirement coverage.
+
+    The table is intentionally lightweight: it cannot prove semantic truth, but
+    it makes requirement-to-plan mapping explicit and blocks publishable plans
+    that admit uncovered requirements.
+    """
+    heading = _REQUIREMENT_COVERAGE_HEADING_RE.search(content)
+    if heading is None:
+        failures.append(
+            "implementation-planning report is missing `Requirement Coverage` "
+            "section — every task-brief requirement must map to option/stage/step."
+        )
+        return
+
+    rest = content[heading.end():]
+    next_heading = _NEXT_THIRD_LEVEL_HEADING_RE.search(rest)
+    section = rest[: next_heading.start()] if next_heading else rest
+    lines = section.splitlines()
+
+    header_idx = -1
+    headers: list[str] = []
+    for idx, line in enumerate(lines):
+        if not line.lstrip().startswith("|"):
+            continue
+        cells = [c.lower() for c in _split_markdown_row(line)]
+        if "id" in cells and "requirement" in cells and "status" in cells:
+            header_idx = idx
+            headers = cells
+            break
+    if header_idx < 0:
+        failures.append(
+            "implementation-planning Requirement Coverage section has no table "
+            "with `ID`, `Requirement`, and `Status` columns."
+        )
+        return
+
+    id_col = headers.index("id")
+    status_col = headers.index("status")
+    rows: list[tuple[str, str]] = []
+    body_started = False
+    for line in lines[header_idx + 1:]:
+        if not line.lstrip().startswith("|"):
+            if body_started:
+                break
+            continue
+        if _is_markdown_separator(line):
+            body_started = True
+            continue
+        if not body_started:
+            continue
+        cells = _split_markdown_row(line)
+        if max(id_col, status_col) >= len(cells):
+            failures.append(
+                "implementation-planning Requirement Coverage table has a "
+                f"malformed row: `{line.strip()}`"
+            )
+            continue
+        rows.append((cells[id_col], cells[status_col].lower()))
+
+    if not rows:
+        failures.append(
+            "implementation-planning Requirement Coverage table has no data rows."
+        )
+        return
+
+    for row_id, status in rows:
+        if not re.fullmatch(r"covered|gap|blocked C-\d{3,}", status):
+            failures.append(
+                "implementation-planning Requirement Coverage row "
+                f"`{row_id}` has invalid Status `{status}`; expected "
+                "`covered`, `gap`, or `blocked C-NNN`."
+            )
+
+    if gate_value in ("passed", "passed-with-dissent"):
+        uncovered = [
+            f"{row_id} ({status})"
+            for row_id, status in rows
+            if status != "covered"
+        ]
+        if uncovered:
+            failures.append(
+                "implementation-planning Gate result is publishable but "
+                "Requirement Coverage has uncovered row(s): "
+                + ", ".join(uncovered)
+            )
 def _extract_verdict_card_token(content: str) -> str | None:
     """Return the `Verdict Token` cell from the Verdict Card block."""
     block = _VERDICT_CARD_BLOCK_RE.search(content)
@@ -1101,6 +1228,19 @@ def _validate_final_verification_consistency(data: dict, failures: list[str]) ->
             "when the verdict is `accepted`."
         )
 
+    scope = data.get("verificationScope", "whole-task")
+    if scope not in ("whole-task", "single-stage"):
+        failures.append(
+            f"final-verification: verificationScope must be `whole-task` or "
+            f"`single-stage`, got {scope!r}."
+        )
+    if scope == "single-stage" and "release-handoff" in routing:
+        failures.append(
+            "final-verification: verificationScope `single-stage` cannot recommend "
+            "release-handoff routing — single-stage is a partial verification and "
+            "release-handoff requires whole-task verification."
+        )
+
 
 def validate_report_views(report_path: Path, failures: list[str]) -> None:
     """Enforce Phase 7 step 1.5 (BLOCKING) — the self-contained HTML
@@ -1292,6 +1432,8 @@ def validate_phase_boundary(
             "must NOT publish a pre-approved plan when verification did not pass."
         )
 
+    _append_requirement_coverage_failures(content, gate_value, failures)
+
     # Only a publishable plan (gate passed) can be flipped to `approved: true`
     # and reach the `implementation` entry, so the Stage Map structure is
     # enforced only here — a blocked/aborted plan may legitimately be incomplete.
@@ -1732,7 +1874,7 @@ def main() -> int:
     validate_report(report_path, contract["required_agent_status_entries"], failures)
     validate_team_state_usage(team_state, failures)
 
-    task_type = str(task_manifest.get("taskType") or run_manifest.get("taskType") or "").strip()
+    task_type = effective_run_task_type(run_manifest, task_manifest)
     validate_phase_boundary(task_type, report_path, failures)
     if task_type:
         validate_worker_results_audit(report_path, task_type, failures)

package/runtime/validators/validate-workflow.sh

@@ -17,7 +17,12 @@ WORKSPACE_APP_PATH="$PROJECT_ROOT"
 OKSTRA_SCRIPT="$WORKSPACE_ROOT/scripts/okstra.sh"
 RUN_VALIDATOR_PATH="$WORKSPACE_ROOT/validators/validate-run.py"
 SOURCE_ASSET_ROOT="$WORKSPACE_ROOT/agents"
-TASK_TYPE="final-verification"
+# Arbitrary sample task-type used only to exercise the bundle-prep /
+# discovery-pointer / task-catalog / asset-seeding machinery via render-only
+# run_okstra. Must NOT require --approved-plan (excludes implementation and
+# final-verification) and must have a tests/fixtures/final-report-data/
+# <task-type>-001.data.json sample (used by prepare_run_validator_fixture).
+TASK_TYPE="requirements-discovery"
 PRIMARY_TASK_GROUP="validation"
 PRIMARY_TASK_ID="asset-refresh-and-reference-expectations"
 PRIMARY_BRIEF_FILENAME="validation-brief-primary.md"

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":