okstra 0.26.0 → 0.27.0

package/runtime/validators/validate-brief.py

@@ -0,0 +1,385 @@
+#!/usr/bin/env python3
+"""Validate brief markdown files produced by the okstra-brief skill.
+
+Checks performed per brief file:
+
+1. YAML frontmatter exists on line 1 with required keys.
+2. brief-id matches the filename stem.
+3. depth equals the number of `sub/` segments in the path (relative to the
+   `briefs/` root).
+4. Every Open Questions row starts with one of the five signal prefixes
+   (general | terminology | intent-check | conversion-block | adr-candidate).
+   `adr-candidate:` targets okstra-internal
+   `<PROJECT_ROOT>/.project-docs/okstra/decisions/`, not external `docs/adr/`.
+5. Every Augmentation entry (inline `> augmented: <label>` blockquotes and
+   `Augmentation` section bullets) carries one of the four labels
+   (evidence-link | format-conversion | terminology-mapping | intent-inference).
+   Both documented forms are accepted: `label: ...` and `label — ...`.
+6. Every `intent-inference` augmentation has a corresponding
+   `intent-check:` row in Open Questions (auto-mirroring rule).
+7. Every `terminology-mapping` augmentation (excluding Step 4.5 outcome
+   markers `applied glossary:` / `skipped glossary:`) has a corresponding
+   `terminology:` row in Open Questions.
+8. `parent-id` chain: at depth 0 the value MUST be the literal `self`;
+   at depth ≥ 1 it MUST NOT be `self` and MUST differ from the brief's
+   own `brief-id`.
+9. `reporter-confirmations` consistency: when `complete`, every
+   `intent-check:` and `conversion-block:` row in Open Questions MUST
+   carry a `[CONFIRMED YYYY-MM-DD → RC-N]` marker.
+
+Exit code 0 on PASS, 1 on FAIL.
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+from typing import Iterable
+
+REQUIRED_FRONTMATTER_KEYS = {
+    "type",
+    "brief-id",
+    "parent-id",
+    "ticket-id",
+    "source-type",
+    "task-group",
+    "depth",
+    "created",
+    "generator",
+    "reporter-confirmations",
+}
+
+OPEN_QUESTIONS_PREFIXES = {
+    "general:",
+    "terminology:",
+    "intent-check:",
+    "conversion-block:",
+    "adr-candidate:",
+}
+
+AUGMENTATION_LABELS = {
+    "evidence-link",
+    "format-conversion",
+    "terminology-mapping",
+    "intent-inference",
+}
+
+REPORTER_CONFIRMATION_VALUES = {"complete", "partial", "pending", "skipped"}
+
+
+def parse_frontmatter(text: str) -> tuple[dict[str, str], int]:
+    """Return (frontmatter dict, line after closing `---`)."""
+    lines = text.splitlines()
+    if not lines or lines[0].strip() != "---":
+        raise ValueError("missing opening frontmatter delimiter on line 1")
+    out: dict[str, str] = {}
+    for idx in range(1, len(lines)):
+        line = lines[idx]
+        if line.strip() == "---":
+            return out, idx + 1
+        # naive key: value (comments after #)
+        bare = line.split("#", 1)[0].strip()
+        if not bare:
+            continue
+        if ":" not in bare:
+            raise ValueError(f"frontmatter line without colon: {line!r}")
+        key, _, value = bare.partition(":")
+        out[key.strip()] = value.strip()
+    raise ValueError("missing closing frontmatter delimiter")
+
+
+def section_body(text: str, heading: str) -> str:
+    """Return the body lines between `## <heading>` and the next `## ` heading."""
+    pattern = re.compile(
+        r"^##\s+" + re.escape(heading) + r"\s*$(.*?)(?=^##\s|\Z)",
+        re.MULTILINE | re.DOTALL,
+    )
+    match = pattern.search(text)
+    if not match:
+        return ""
+    return match.group(1)
+
+
+def is_placeholder(line: str) -> bool:
+    bare = line.strip().lstrip("-").strip()
+    return bare in {"_(none)_", "_(none — pending or skipped)_", ""}
+
+
+def is_template_example(line: str) -> bool:
+    """Lines that are template scaffolding (placeholder/example), not real entries."""
+    bare = line.strip().lstrip("-").strip()
+    return bare.startswith("<") and bare.endswith(">")
+
+
+def open_questions_rows(text: str) -> list[str]:
+    body = section_body(text, "Open Questions")
+    rows: list[str] = []
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        content = stripped[2:].strip()
+        if is_placeholder(content) or is_template_example(content):
+            continue
+        # strip backticks if the row body is wrapped in `…`
+        content = content.strip("`")
+        rows.append(content)
+    return rows
+
+
+def augmentation_entries(text: str) -> list[str]:
+    """Bullets under the `## Augmentation` section (entries that look like real data)."""
+    body = section_body(text, "Augmentation")
+    entries: list[str] = []
+    for line in body.splitlines():
+        stripped = line.strip()
+        if not stripped.startswith("- "):
+            continue
+        content = stripped[2:].strip()
+        if is_placeholder(content) or is_template_example(content):
+            continue
+        # strip backticks
+        content = content.strip("`")
+        entries.append(content)
+    return entries
+
+
+def inline_augmented_blockquotes(text: str) -> list[str]:
+    """Lines starting with `> augmented:`."""
+    out: list[str] = []
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped.startswith("> augmented:"):
+            payload = stripped[len("> augmented:"):].strip()
+            if payload.startswith("<") and payload.endswith(">"):
+                # template scaffold, e.g. `> augmented: <label> — <interpretation>`
+                continue
+            out.append(payload)
+    return out
+
+
+def parse_augmentation_label(entry: str) -> tuple[str | None, str]:
+    """Return (label, payload) for documented augmentation forms."""
+    stripped = entry.strip()
+    for label in AUGMENTATION_LABELS:
+        if stripped == label:
+            return label, ""
+        for sep in (":", " — ", " - "):
+            prefix = f"{label}{sep}"
+            if stripped.startswith(prefix):
+                return label, stripped[len(prefix):].strip()
+    return None, stripped
+
+
+def validate_brief(path: Path, briefs_root: Path) -> list[str]:
+    text = path.read_text(encoding="utf-8")
+    errors: list[str] = []
+
+    # 1. frontmatter
+    try:
+        fm, _ = parse_frontmatter(text)
+    except ValueError as exc:
+        return [f"frontmatter: {exc}"]
+
+    missing = REQUIRED_FRONTMATTER_KEYS - fm.keys()
+    if missing:
+        errors.append(f"frontmatter missing keys: {sorted(missing)}")
+
+    if fm.get("type") != "brief":
+        errors.append(f"frontmatter type must be 'brief', got {fm.get('type')!r}")
+
+    if fm.get("generator") != "okstra-brief":
+        errors.append(
+            f"frontmatter generator must be 'okstra-brief', got {fm.get('generator')!r}"
+        )
+
+    if fm.get("reporter-confirmations") not in REPORTER_CONFIRMATION_VALUES:
+        errors.append(
+            "frontmatter reporter-confirmations must be one of "
+            f"{sorted(REPORTER_CONFIRMATION_VALUES)}, got "
+            f"{fm.get('reporter-confirmations')!r}"
+        )
+
+    # 2. brief-id matches filename stem
+    stem = path.stem
+    if fm.get("brief-id") and fm["brief-id"] != stem:
+        errors.append(
+            f"brief-id {fm['brief-id']!r} does not match filename stem {stem!r}"
+        )
+
+    # 3. depth equals path's `sub/` nesting depth
+    try:
+        rel = path.relative_to(briefs_root)
+    except ValueError:
+        rel = path
+    # path components after the task-group dir: any number of `sub` segments + filename
+    parts = list(rel.parts)
+    if len(parts) >= 2:
+        nested = [p for p in parts[1:-1] if p == "sub"]
+        expected_depth = len(nested)
+        try:
+            actual_depth = int(fm.get("depth", "0"))
+        except ValueError:
+            actual_depth = -1
+        if actual_depth != expected_depth:
+            errors.append(
+                f"depth mismatch: path has {expected_depth} `sub/` segments, "
+                f"frontmatter says depth={fm.get('depth')!r}"
+            )
+
+    # 4. Open Questions prefixes
+    oq_rows = open_questions_rows(text)
+    intent_check_rows: list[str] = []
+    terminology_rows: list[str] = []
+    conversion_block_rows: list[str] = []
+    for row in oq_rows:
+        if not any(row.startswith(prefix) for prefix in OPEN_QUESTIONS_PREFIXES):
+            errors.append(f"Open Questions row lacks a known prefix: {row!r}")
+        if row.startswith("intent-check:"):
+            intent_check_rows.append(row)
+        elif row.startswith("terminology:"):
+            terminology_rows.append(row)
+        elif row.startswith("conversion-block:"):
+            conversion_block_rows.append(row)
+
+    # 5. Augmentation labels
+    augmentation_lines: list[str] = []
+    augmentation_lines.extend(augmentation_entries(text))
+    augmentation_lines.extend(inline_augmented_blockquotes(text))
+    intent_inference_count = 0
+    terminology_mapping_count = 0
+    for entry in augmentation_lines:
+        label, payload = parse_augmentation_label(entry)
+        if label not in AUGMENTATION_LABELS:
+            errors.append(
+                f"Augmentation entry lacks a known label: {entry!r} "
+                f"(label parsed as {label!r})"
+            )
+            continue
+        if label == "intent-inference":
+            intent_inference_count += 1
+        elif label == "terminology-mapping":
+            # Step 4.5 outcome markers do not need a paired Open Questions row.
+            if payload.startswith("applied glossary:") or payload.startswith(
+                "skipped glossary:"
+            ):
+                continue
+            terminology_mapping_count += 1
+
+    # 6. auto-mirroring rule (intent-inference ↔ intent-check:)
+    if intent_inference_count > len(intent_check_rows):
+        errors.append(
+            f"intent-inference augmentations present ({intent_inference_count}) "
+            f"but only {len(intent_check_rows)} intent-check: row(s) in Open Questions"
+        )
+
+    # 7. dual-record rule (terminology-mapping ↔ terminology:)
+    if terminology_mapping_count > 0 and not terminology_rows:
+        errors.append(
+            f"terminology-mapping augmentations present ({terminology_mapping_count}) "
+            f"but no terminology: row(s) in Open Questions"
+        )
+
+    # 8. parent-id chain
+    parent_id = fm.get("parent-id", "")
+    brief_id = fm.get("brief-id", "")
+    try:
+        depth_value = int(fm.get("depth", "0"))
+    except ValueError:
+        depth_value = -1
+    if depth_value == 0:
+        if parent_id != "self":
+            errors.append(
+                f"parent-id for the root (depth 0) brief must be 'self', "
+                f"got {parent_id!r}"
+            )
+    elif depth_value > 0:
+        if parent_id == "self":
+            errors.append(
+                f"parent-id for a descendant (depth {depth_value}) brief must not be 'self'"
+            )
+        elif parent_id == brief_id:
+            errors.append(
+                f"parent-id for a descendant brief must differ from its own brief-id "
+                f"({brief_id!r})"
+            )
+
+    # 9. reporter-confirmations consistency
+    rc_status = fm.get("reporter-confirmations")
+    if rc_status == "complete":
+        unconfirmed = [
+            row
+            for row in (intent_check_rows + conversion_block_rows)
+            if "[CONFIRMED" not in row
+        ]
+        if unconfirmed:
+            sample = unconfirmed[0]
+            errors.append(
+                f"reporter-confirmations is 'complete' but {len(unconfirmed)} "
+                f"intent-check:/conversion-block: row(s) lack a [CONFIRMED …] "
+                f"marker (e.g. {sample!r})"
+            )
+
+    return errors
+
+
+def find_briefs(root: Path) -> Iterable[Path]:
+    yield from root.rglob("*.md")
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument(
+        "briefs_dir",
+        type=Path,
+        help="Directory containing brief markdown files (recursed).",
+    )
+    parser.add_argument(
+        "--briefs-root",
+        type=Path,
+        default=None,
+        help=(
+            "Root used for depth computation (defaults to briefs_dir). "
+            "Usually `<PROJECT_ROOT>/.project-docs/okstra/briefs`."
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    briefs_dir: Path = args.briefs_dir
+    if not briefs_dir.exists():
+        print(f"[FAIL] briefs directory not found: {briefs_dir}", file=sys.stderr)
+        return 1
+
+    briefs_root: Path = args.briefs_root or briefs_dir
+
+    total = 0
+    failed_files: list[tuple[Path, list[str]]] = []
+    for brief in find_briefs(briefs_dir):
+        total += 1
+        errors = validate_brief(brief, briefs_root)
+        if errors:
+            failed_files.append((brief, errors))
+
+    if total == 0:
+        print(f"[PASS] no briefs found under {briefs_dir} (nothing to validate)")
+        return 0
+
+    if not failed_files:
+        print(f"[PASS] {total} brief(s) validated under {briefs_dir}")
+        return 0
+
+    for path, errors in failed_files:
+        print(f"[FAIL] {path}")
+        for err in errors:
+            print(f"  - {err}")
+    print(
+        f"[FAIL] {len(failed_files)}/{total} brief(s) failed validation",
+        file=sys.stderr,
+    )
+    return 1
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/runtime/validators/validate-brief.sh

@@ -0,0 +1,35 @@
+#!/usr/bin/env bash
+#
+# Validate brief markdown files produced by okstra-brief.
+#
+# Usage:
+#   validators/validate-brief.sh <briefs-dir> [--briefs-root <dir>]
+#
+# Typical invocation (inside a project that has run okstra-setup):
+#   validators/validate-brief.sh "$PROJECT_ROOT/.project-docs/okstra/briefs"
+#
+# Thin bash entrypoint — delegates to validate-brief.py for content checks.
+
+set -euo pipefail
+
+SOURCE_PATH="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE_PATH" ]]; do
+  SOURCE_DIR="$(cd -P "$(dirname "$SOURCE_PATH")" && pwd)"
+  SOURCE_PATH="$(readlink "$SOURCE_PATH")"
+  [[ "$SOURCE_PATH" != /* ]] && SOURCE_PATH="$SOURCE_DIR/$SOURCE_PATH"
+done
+
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE_PATH")" && pwd)"
+PYTHON_VALIDATOR="$SCRIPT_DIR/validate-brief.py"
+
+if [[ ! -f "$PYTHON_VALIDATOR" ]]; then
+  echo "[FAIL] python helper not found: $PYTHON_VALIDATOR" >&2
+  exit 1
+fi
+
+if [[ $# -lt 1 ]]; then
+  echo "usage: $0 <briefs-dir> [--briefs-root <dir>]" >&2
+  exit 1
+fi
+
+exec python3 "$PYTHON_VALIDATOR" "$@"

package/runtime/validators/validate-workflow.sh

@@ -18,7 +18,6 @@ OKSTRA_SCRIPT="$WORKSPACE_ROOT/scripts/okstra.sh"
 RUN_VALIDATOR_SCRIPT="$WORKSPACE_ROOT/validators/validate-run.py"
 SOURCE_ASSET_ROOT="$WORKSPACE_ROOT/agents"
 TASK_TYPE="final-verification"
-MARKER="MANUAL-VALIDATION-MARKER"
 PRIMARY_TASK_GROUP="validation"
 PRIMARY_TASK_ID="asset-refresh-and-reference-expectations"
 PRIMARY_BRIEF_FILENAME="validation-brief-primary.md"
@@ -56,7 +55,6 @@ PRIMARY_BRIEF_PATH="$PROJECT_ROOT/$PRIMARY_BRIEF_FILENAME"
 SECONDARY_BRIEF_PATH="$PROJECT_ROOT/$SECONDARY_BRIEF_FILENAME"
 DISCOVERY_FILE="$PROJECT_ROOT/$LATEST_TASK_RELATIVE_PATH"
 CATALOG_FILE="$PROJECT_ROOT/$TASK_CATALOG_RELATIVE_PATH"
-MARKER_FILE="$PROJECT_ROOT/.claude/agents/codex-worker.md"
 PRIMARY_TASK_KEY="$(task_key "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID")"
 SECONDARY_TASK_KEY="$(task_key "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID")"
 PRIMARY_REFERENCE_EXPECTATIONS_FILE="$(task_root "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID")/instruction-set/reference-expectations.md"
@@ -155,36 +153,12 @@ if ! validate_task_catalog "$SECONDARY_TASK_KEY" "$PRIMARY_TASK_KEY" "$SECONDARY
 fi
 pass "latest-task.json and task-catalog.json now reflect distinct primary and secondary tasks"
 
-step "Verifying that rerun without refresh preserves project-local assets"
-require_file "$MARKER_FILE"
-printf '\n%s\n' "$MARKER" >>"$MARKER_FILE"
-assert_contains "$MARKER_FILE" "$MARKER"
-if ! run_okstra "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID" "$SECONDARY_BRIEF_FILENAME"; then
-  fail "Secondary task rerun without refresh failed"
-fi
-assert_contains "$MARKER_FILE" "$MARKER"
-if ! validate_latest_task_pointer "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID"; then
-  fail "latest-task.json changed unexpectedly during secondary rerun without refresh"
-fi
-if ! validate_task_catalog "$SECONDARY_TASK_KEY" "$PRIMARY_TASK_KEY" "$SECONDARY_TASK_KEY"; then
-  fail "task-catalog.json changed unexpectedly during secondary rerun without refresh"
-fi
-pass "Rerun without refresh preserved the modified project-local asset and retained both catalog entries"
-
-step "Verifying that rerun with refresh regenerates project-local assets"
-if ! run_okstra "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID" "$SECONDARY_BRIEF_FILENAME" --refresh-assets; then
-  fail "Secondary task rerun with --refresh-assets failed"
-fi
-assert_not_contains "$MARKER_FILE" "$MARKER"
-if ! validate_seeded_assets match; then
-  fail "Refreshed project-local okstra assets do not match the source files"
-fi
-if ! validate_latest_task_pointer "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID"; then
-  fail "latest-task.json became invalid after refresh"
-fi
-if ! validate_task_catalog "$SECONDARY_TASK_KEY" "$PRIMARY_TASK_KEY" "$SECONDARY_TASK_KEY"; then
-  fail "task-catalog.json became invalid after refresh"
-fi
-pass "Refresh regenerated the mapped project-local okstra assets while preserving both catalog entries"
+# Removed: the historical "rerun without refresh preserves project-local
+# assets" and "rerun with refresh regenerates project-local assets" stanzas.
+# Those tested a contract from when `okstra install` seeded per-project
+# `.claude/` files; install now writes only to `$HOME/.claude` and
+# `$HOME/.okstra`, so the project-local sentinel is no longer a meaningful
+# contract. The `--refresh-assets` flag was removed entirely in a paired
+# commit; users with old scripts should switch to `okstra install --refresh`.
 
 print_summary