@xenonbyte/req-2-plan 0.2.3 → 0.3.0

package/tools/workflow_cli/gates.py

@@ -7,6 +7,7 @@ The Agent handles semantic quality; this module handles structural validation.
 from __future__ import annotations
 
 import re
+from collections import Counter
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -19,7 +20,14 @@ from tools.workflow_cli.models import (
     TierEstimate,
     TierModifier,
 )
+from tools.workflow_cli.markdown import (
+    heading_bounded_bodies,
+    strip_readonly_sections,
+    unfenced_markdown_lines,
+    unfenced_markdown_text,
+)
 from tools.workflow_cli.output import EXIT_GATE_FAIL
+from tools.workflow_cli.stage_schema import PLAN_TASK_FIELD_RE, PLAN_TASK_FIELDS
 
 # ---------------------------------------------------------------------------
 # GateResult
@@ -82,11 +90,42 @@ def check_entry_gate(
 # Upstream ID reference pattern
 # ---------------------------------------------------------------------------
 
+_FILL_IN_PLACEHOLDER_RE = re.compile(r"<!--\s*fill in\s*-->", re.IGNORECASE)
+
+_PLACEHOLDER_PATTERNS = [
+    _FILL_IN_PLACEHOLDER_RE,                              # untouched template body
+    re.compile(
+        r"(?im)^\s*(?:[-*]\s*)?(?:[A-Za-z][A-Za-z0-9 /_-]*:\s*)?TBD\s*$"
+    ),                                                     # TBD as a line, field value, or list item
+    re.compile(r"(?im)^\s*(?:[-*]\s*)?maybe\s*$"),
+    re.compile(r"\bTODO later\b", re.IGNORECASE),
+    re.compile(
+        r"(?im)^\s*(?:[-*]\s*)?(?:[A-Za-z][A-Za-z0-9 /_-]*:\s*)?FIXME\s*$"
+    ),                                                     # FIXME as a placeholder line/field, not prose
+]
+
 # IDs that represent upstream references: REQ-*, RISK-*, DES-*, SPEC-*
 _UPSTREAM_ID_PATTERN = re.compile(
     r"\b(REQ-[A-Z]+-\d+|RISK-[A-Z]+-\d+|DES-[A-Z]+-\d+|SPEC-[A-Z]+-\d+)\b"
 )
 
+# Trace-ID validation: well-formed vs candidate patterns
+_VALID_TRACE_ID_RE = re.compile(
+    r"^(?:REQ|RISK|DES|SPEC)-[A-Z]+-\d+$|^SCOPE-(?:IN|OUT)-\d+$|^PLAN-TASK-\d+$"
+)
+_TRACE_ID_CANDIDATE_RE = re.compile(
+    r"\b(?:REQ|RISK|DES|SPEC)-[A-Za-z][A-Za-z0-9_-]*\d[A-Za-z0-9_-]*"
+    r"|\bSCOPE-(?:IN|OUT)-[A-Za-z0-9_-]*\d[A-Za-z0-9_-]*"
+    r"|\bPLAN-TASK-[A-Za-z0-9_-]*\d[A-Za-z0-9_-]*"
+)
+
+# Native-ID heading patterns: stages that MUST define at least one native ID in a heading
+_STAGE_NATIVE_HEADING_PATTERNS = {
+    Stage.RISK_DISCOVERY: re.compile(r"(?m)^#+\s+.*\bRISK-[A-Z]+-\d+\b"),
+    Stage.DESIGN: re.compile(r"(?m)^#+\s+.*\bDES-[A-Z]+-\d+\b"),
+    Stage.SPEC: re.compile(r"(?m)^#+\s+.*\bSPEC-[A-Z]+-\d+\b"),
+}
+
 # Closure status tags
 _CLOSURE_TAGS = frozenset(["[ADDRESSED]", "[DEFERRED]", "[N/A]", "[OUT-OF-SCOPE]", "[CLOSED]"])
 
@@ -97,7 +136,7 @@ _DEFINED_ID_PATTERN = re.compile(r"\b([A-Z]+-[A-Z]+-\d+)\b")
 def _find_defined_ids(content: str) -> set[str]:
     """Return IDs that are defined in headings (i.e. the current artifact is defining them)."""
     heading_pattern = re.compile(r"^#{1,6}\s+.*\b([A-Z]+-[A-Z]+-\d+)\b", re.MULTILINE)
-    return set(heading_pattern.findall(content))
+    return set(heading_pattern.findall(unfenced_markdown_text(content)))
 
 
 def _find_ids_without_closure(content: str) -> list[str]:
@@ -106,7 +145,8 @@ def _find_ids_without_closure(content: str) -> list[str]:
     IDs defined in headings of the current artifact are excluded — they are
     being *defined* here, not referencing upstream artifacts that need closure.
     """
-    all_refs = set(_UPSTREAM_ID_PATTERN.findall(content))
+    search_content = unfenced_markdown_text(content)
+    all_refs = set(_UPSTREAM_ID_PATTERN.findall(search_content))
     defined_here = _find_defined_ids(content)
     # Only check IDs that are referenced but NOT defined in this artifact
     refs_to_check = all_refs - defined_here
@@ -121,7 +161,7 @@ def _find_ids_without_closure(content: str) -> list[str]:
                 re.escape(ref_id) + r"[^\n]*" + re.escape(tag),
                 re.IGNORECASE,
             )
-            if pattern.search(content):
+            if pattern.search(search_content):
                 has_closure = True
                 break
         if not has_closure:
@@ -132,7 +172,7 @@ def _find_ids_without_closure(content: str) -> list[str]:
 def _find_duplicate_ids(content: str) -> list[str]:
     """Return IDs that appear more than once in heading (definition) context."""
     heading_pattern = re.compile(r"^#{1,6}\s+.*\b([A-Z]+-[A-Z]+-\d+)\b", re.MULTILINE)
-    heading_ids = heading_pattern.findall(content)
+    heading_ids = heading_pattern.findall(unfenced_markdown_text(content))
 
     from collections import Counter
     counts = Counter(heading_ids)
@@ -145,41 +185,9 @@ def _find_duplicate_ids(content: str) -> list[str]:
 
 _EXTERNAL_DOCS_RE = re.compile(r"^## External Documentation Checked\s*$", re.MULTILINE)
 _H2_RE = re.compile(r"^##\s+", re.MULTILINE)
-_MARKDOWN_CODE_FENCE_RE = re.compile(r"^[ \t]{0,3}(`{3,}|~{3,})", re.MULTILINE)
-_MARKDOWN_FENCE_MARKER_RE = re.compile(r"^[ \t]{0,3}(`{3,}|~{3,})")
 _ISO_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
 
 
-def _unfenced_markdown_lines(content: str):
-    """Yield (line, start, end) for lines outside Markdown fenced code blocks."""
-    fence_char = ""
-    fence_len = 0
-    offset = 0
-    for line in content.splitlines(keepends=True):
-        marker = _MARKDOWN_FENCE_MARKER_RE.match(line)
-        if fence_char:
-            if (
-                marker
-                and marker.group(1)[0] == fence_char
-                and len(marker.group(1)) >= fence_len
-                and not line[marker.end():].strip()
-            ):
-                fence_char = ""
-                fence_len = 0
-            offset += len(line)
-            continue
-
-        if marker:
-            fence_char = marker.group(1)[0]
-            fence_len = len(marker.group(1))
-            offset += len(line)
-            continue
-
-        start = offset
-        offset += len(line)
-        yield line, start, offset
-
-
 def _plain_table_cell(cell: str) -> str:
     return cell.strip().strip("_*`").strip()
 
@@ -218,14 +226,14 @@ def _is_external_docs_inventory_row(line: str) -> bool:
 
 def _has_external_docs_inventory(content: str) -> bool:
     section_start = None
-    for line, _, end in _unfenced_markdown_lines(content):
+    for line, _, end in unfenced_markdown_lines(content):
         if _EXTERNAL_DOCS_RE.match(line):
             section_start = end
             break
     if section_start is None:
         return False
 
-    for line, start, _ in _unfenced_markdown_lines(content):
+    for line, start, _ in unfenced_markdown_lines(content):
         if start < section_start:
             continue
         if _H2_RE.match(line):
@@ -242,15 +250,14 @@ def _has_external_docs_inventory(content: str) -> bool:
 
 _PLAN_TASK_RE = re.compile(r"^### PLAN-TASK-\d+", re.MULTILINE)
 _CODE_FENCE_LINE_RE = re.compile(r"^[ \t]{0,3}(`{3,}|~{3,})(.*)$")
-_PLAN_TASK_FIELD_RE = re.compile(
-    r"^(Spec References|Change Type|TDD Applicable|Files|Skeleton|Steps|Verification):"
-)
+_INLINE_CODE_VALUE_RE = re.compile(r"^(`+)(.*?)\1$", re.DOTALL)
+_MARKDOWN_LINK_VALUE_RE = re.compile(r"^\[([^\]]+)\]\([^)]+\)$")
 
 
 def _plan_task_starts(content: str) -> list[int]:
     return [
         start
-        for line, start, _ in _unfenced_markdown_lines(content)
+        for line, start, _ in unfenced_markdown_lines(content)
         if _PLAN_TASK_RE.match(line)
     ]
 
@@ -268,7 +275,7 @@ def _plan_task_field_body(task_body: str, field: str) -> str:
 
 def _find_plan_task_field(task_body: str, field: str):
     field_re = re.compile(rf"^{re.escape(field)}:[ \t]*(.*)$")
-    for line, start, _ in _unfenced_markdown_lines(task_body):
+    for line, start, _ in unfenced_markdown_lines(task_body):
         match = field_re.match(line)
         if match:
             return match, start
@@ -276,8 +283,8 @@ def _find_plan_task_field(task_body: str, field: str):
 
 
 def _find_next_plan_task_field_start(task_body: str, after: int) -> int | None:
-    for line, start, _ in _unfenced_markdown_lines(task_body):
-        if start >= after and _PLAN_TASK_FIELD_RE.match(line):
+    for line, start, _ in unfenced_markdown_lines(task_body):
+        if start >= after and PLAN_TASK_FIELD_RE.match(line):
             return start
     return None
 
@@ -290,6 +297,161 @@ def _plan_task_field_value(task_body: str, field: str) -> str:
     return match.group(1).strip()
 
 
+def _iter_plan_task_bodies(content: str):
+    return heading_bounded_bodies(content, _PLAN_TASK_RE.match)
+
+
+def _plan_task_label(body: str) -> str:
+    m = re.match(r"###\s+PLAN-TASK-(\d+)", body)
+    return f"PLAN-TASK-{m.group(1)}" if m else "PLAN-TASK-?"
+
+
+def _strip_markdown_path_wrappers(value: str) -> str:
+    text = value.strip()
+    changed = True
+    while changed:
+        changed = False
+        inline_code = _INLINE_CODE_VALUE_RE.fullmatch(text)
+        if inline_code:
+            text = inline_code.group(2).strip()
+            changed = True
+            continue
+        markdown_link = _MARKDOWN_LINK_VALUE_RE.fullmatch(text)
+        if markdown_link:
+            text = markdown_link.group(1).strip()
+            changed = True
+            continue
+        if len(text) >= 2 and text.startswith("<") and text.endswith(">"):
+            text = text[1:-1].strip()
+            changed = True
+            continue
+        for marker in ("**", "__"):
+            if (
+                len(text) > 2 * len(marker)
+                and text.startswith(marker)
+                and text.endswith(marker)
+            ):
+                text = text[len(marker):-len(marker)].strip()
+                changed = True
+                break
+    return text
+
+
+def _plan_task_path_part(raw_path: str) -> str:
+    value = _strip_markdown_path_wrappers(raw_path)
+    return _strip_markdown_path_wrappers(value.split("::")[0])
+
+
+def _plan_task_file_paths(files_field: str) -> list[str]:
+    paths: list[str] = []
+    lines = [line for line, _, _ in unfenced_markdown_lines(files_field)]
+    if not lines:
+        return paths
+
+    first = lines[0].strip()
+    if first:
+        raw_path = first[2:].strip() if first.startswith(("- ", "* ")) else first
+        path_part = _plan_task_path_part(raw_path)
+        if path_part:
+            paths.append(path_part)
+
+    for line in lines[1:]:
+        stripped = line.strip()
+        if not stripped.startswith(("- ", "* ")):
+            continue
+        path_part = _plan_task_path_part(stripped[2:])
+        if path_part:
+            paths.append(path_part)
+    return paths
+
+
+def _check_plan_file_refs(run_dir: Path, content: str) -> list[str]:
+    """Hard-check Files paths against the Context Pack repo_root. create-type tasks
+    are exempt; the part after '::' (a symbol) is advisory and not checked (no AST pack yet)."""
+    import json
+    pack_json = run_dir / "02-project-context.json"
+    if not pack_json.exists():
+        return []  # no ground truth -> advisory only
+    try:
+        repo_root = Path(json.loads(pack_json.read_text(encoding="utf-8")).get("repo_root", ""))
+    except (ValueError, OSError):
+        return []
+    if not repo_root or not repo_root.exists():
+        return []
+    repo_root = repo_root.resolve()
+    issues: list[str] = []
+    for body in _iter_plan_task_bodies(content):
+        change_type = _plan_task_field_value(body, "Change Type").strip().lower()
+        skip_missing_path = change_type == "create"
+        files_field = _plan_task_field_body(body, "Files")
+        for path_part in _plan_task_file_paths(files_field):
+            path = Path(path_part)
+            if path.is_absolute():
+                resolved = path.resolve()
+            else:
+                resolved = (repo_root / path).resolve()
+            try:
+                resolved.relative_to(repo_root)
+            except ValueError:
+                issues.append(
+                    f"PLAN-TASK Files references path outside repo_root {path_part!r}."
+                )
+                continue
+            if not resolved.exists():
+                if not skip_missing_path:
+                    issues.append(
+                        f"PLAN-TASK Files references missing path {path_part!r} "
+                        "(mark the task 'Change Type: create' if it is a new file)."
+                    )
+    return issues
+
+
+def _check_spec_refs_valid(run_dir: Path, content: str) -> list[str]:
+    spec_path = run_dir / STAGE_ARTIFACT_MAP[Stage.SPEC]
+    spec_content = (
+        strip_readonly_sections(spec_path.read_text(encoding="utf-8"))
+        if spec_path.exists()
+        else ""
+    )
+    defined_specs: set[str] = set()
+    for line, _, _ in unfenced_markdown_lines(spec_content):
+        if line.lstrip().startswith("#"):
+            defined_specs.update(re.findall(r"\bSPEC-[A-Z]+-\d+\b", line))
+    issues: list[str] = []
+    for body in _iter_plan_task_bodies(content):
+        refs_body = _plan_task_field_body(body, "Spec References")
+        refs = re.findall(r"SPEC-[A-Z]+-\d+", refs_body)
+        if refs_body.strip() and not refs:
+            issues.append(
+                f"{_plan_task_label(body)} must reference at least one SPEC-* ID "
+                "in 'Spec References:'."
+            )
+        for ref in refs:
+            if ref not in defined_specs:
+                issues.append(f"PLAN-TASK references {ref} which is not defined in the SPEC artifact.")
+    return issues
+
+
+def _check_plan_task_fields(content: str) -> list[str]:
+    issues: list[str] = []
+    numbers: list[int] = []
+    for body in _iter_plan_task_bodies(content):
+        m = re.match(r"###\s+PLAN-TASK-(\d+)", body)
+        num = int(m.group(1)) if m else None
+        if num is not None:
+            numbers.append(num)
+        label = _plan_task_label(body)
+        for field in PLAN_TASK_FIELDS:
+            if not _plan_task_field_body(body, field).strip():
+                issues.append(f"{label} is missing a non-empty '{field}:' field.")
+    if numbers:
+        if len(set(numbers)) != len(numbers):
+            issues.append("PLAN-TASK numbers must be unique.")
+        elif sorted(numbers) != list(range(1, len(numbers) + 1)):
+            issues.append("PLAN-TASK numbers must be contiguous starting at 1.")
+    return issues
+
+
 def _has_complete_code_fence(content: str) -> bool:
     fence_char = ""
     fence_len = 0
@@ -324,12 +486,10 @@ def _has_complete_code_fence(content: str) -> bool:
 
 def _plan_tasks_missing_code(content: str) -> bool:
     """True if any TDD-applicable PLAN-TASK has no fenced code block in its Skeleton field."""
-    starts = _plan_task_starts(content)
-    if not starts:
+    bodies = list(_iter_plan_task_bodies(content))
+    if not bodies:
         return False
-    bounds = starts + [len(content)]
-    for i in range(len(starts)):
-        body = content[bounds[i]:bounds[i + 1]]
+    for body in bodies:
         skeleton = _plan_task_field_body(body, "Skeleton")
         tdd_applicable = _plan_task_field_value(body, "TDD Applicable")
         if tdd_applicable.lower() == "yes" and not _has_complete_code_fence(skeleton):
@@ -337,6 +497,173 @@ def _plan_tasks_missing_code(content: str) -> bool:
     return False
 
 
+def _check_plan_task_skeleton_placeholders(content: str) -> list[str]:
+    issues: list[str] = []
+    for body in _iter_plan_task_bodies(content):
+        skeleton = _plan_task_field_body(body, "Skeleton")
+        if skeleton.strip() and any(pattern.search(skeleton) for pattern in _PLACEHOLDER_PATTERNS):
+            issues.append(
+                f"{_plan_task_label(body)} Skeleton contains an unresolved template "
+                "placeholder; replace placeholder text before passing the gate."
+            )
+    return issues
+
+
+def _section_body(content: str, heading: str) -> str:
+    """Return the text of the section under `heading`, stopping at the next same-or-higher heading."""
+    level = len(heading) - len(heading.lstrip("#"))
+    out, capture = [], False
+    for line, _, _ in unfenced_markdown_lines(content):
+        if line.strip() == heading:
+            capture = True
+            continue
+        if capture:
+            stripped = line.lstrip()
+            if stripped.startswith("#"):
+                # Count hashes of this line's heading
+                line_level = len(stripped) - len(stripped.lstrip("#"))
+                if line_level <= level:
+                    break
+            out.append(line.rstrip("\r\n"))
+    return "\n".join(out)
+
+
+def _section_entries_missing_id(content: str, heading: str, id_prefix: str) -> list[str]:
+    missing: list[str] = []
+    pattern = re.compile(rf"\b{re.escape(id_prefix)}-\d+\b")
+    for line in _section_body(content, heading).splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("<!--"):
+            continue
+        if not stripped.startswith(("- ", "* ")):
+            continue
+        if not pattern.search(stripped):
+            missing.append(stripped)
+    return missing
+
+
+def _section_entry_ids(content: str, heading: str, id_prefix: str) -> list[str]:
+    ids: list[str] = []
+    pattern = re.compile(rf"\b{re.escape(id_prefix)}-\d+\b")
+    for line in _section_body(content, heading).splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("<!--"):
+            continue
+        if not stripped.startswith(("- ", "* ")):
+            continue
+        match = pattern.search(stripped)
+        if match:
+            ids.append(match.group(0))
+    return ids
+
+
+def _section_has_bullets(content: str, heading: str) -> bool:
+    return any(l.lstrip().startswith(("- ", "* ")) for l in _section_body(content, heading).splitlines())
+
+
+def _check_elicitation(stage: Stage, tier: TierEstimate, content: str) -> list[str]:
+    """R8: standard-tier brief must record at least one assumption or open question."""
+    from tools.workflow_cli.models import TierBase
+    if stage != Stage.REQUIREMENT_BRIEF or tier.base != TierBase.STANDARD:
+        return []
+    if _section_has_bullets(content, "## Assumptions") or _section_has_bullets(content, "## Open Questions"):
+        return []
+    return ["Standard-tier brief must record at least one assumption or open question (R8 elicitation)."]
+
+
+def _check_scope_freeze(stage: Stage, content: str) -> list[str]:
+    """R8: brief's In/Out-of-Scope must carry stable IDs so trace can anchor them."""
+    if stage != Stage.REQUIREMENT_BRIEF:
+        return []
+    issues: list[str] = []
+    for entry in _section_entries_missing_id(content, "## In-Scope", "SCOPE-IN"):
+        issues.append(f"In-Scope entry must carry a SCOPE-IN-* stable ID (R8): {entry}")
+    for entry in _section_entries_missing_id(content, "## Out-of-Scope", "SCOPE-OUT"):
+        issues.append(f"Out-of-Scope entry must carry a SCOPE-OUT-* stable ID (R8): {entry}")
+    for id_, count in Counter(_section_entry_ids(content, "## In-Scope", "SCOPE-IN")).items():
+        if count > 1:
+            issues.append(f"In-Scope stable ID {id_} is duplicate; scope IDs must be unique (R8).")
+    for id_, count in Counter(_section_entry_ids(content, "## Out-of-Scope", "SCOPE-OUT")).items():
+        if count > 1:
+            issues.append(f"Out-of-Scope stable ID {id_} is duplicate; scope IDs must be unique (R8).")
+    if not re.search(r"\bSCOPE-IN-\d+\b", _section_body(content, "## In-Scope")):
+        issues.append("In-Scope must list at least one stable-ID entry (SCOPE-IN-001, ...); none found (R8).")
+    if not re.search(r"\bSCOPE-OUT-\d+\b", _section_body(content, "## Out-of-Scope")):
+        issues.append("Out-of-Scope must list at least one stable-ID entry (SCOPE-OUT-001, ...); none found (R8).")
+    return issues
+
+
+def _has_meaningful_body(text: str) -> bool:
+    """True if `text` has at least one non-empty, non-comment line."""
+    for line in text.splitlines():
+        stripped = line.strip()
+        if stripped and not stripped.startswith("<!--"):
+            return True
+    return False
+
+
+def _check_stage_schema(stage: Stage, tier: TierEstimate, content: str) -> list[str]:
+    """R2 schema gate: required headings present, each required section has a
+    non-placeholder body, trace IDs are well-formed, RISK/DESIGN/SPEC define a
+    native ID heading, and no unresolved placeholders remain."""
+    from tools.workflow_cli.stage_schema import required_headings
+    issues: list[str] = []
+    headings = required_headings(stage, tier.base)
+    native = _STAGE_NATIVE_HEADING_PATTERNS.get(stage)
+    unfenced_content = unfenced_markdown_text(content)
+    present_headings = {
+        line.strip()
+        for line, _, _ in unfenced_markdown_lines(content)
+        if line.lstrip().startswith("#")
+    }
+
+    if not headings and native is None:
+        return issues
+
+    # R2.1: required headings must be present
+    for heading in headings:
+        if heading not in present_headings:
+            issues.append(
+                f"Missing required section {heading!r} for stage {stage.value!r} "
+                f"at tier '{tier.base.value}'."
+            )
+
+    # R2.3a: each required heading's section must have a non-placeholder body
+    for heading in headings:
+        if heading not in present_headings:
+            continue  # already reported by the required-heading presence check
+        body = _section_body(content, heading)
+        if not _has_meaningful_body(body):
+            issues.append(
+                f"Required section {heading!r} must contain non-placeholder body content."
+            )
+
+    # R2.3b: any trace-ID-looking token must be well-formed
+    for token in _TRACE_ID_CANDIDATE_RE.findall(unfenced_content):
+        if not _VALID_TRACE_ID_RE.fullmatch(token):
+            issues.append(
+                f"Malformed trace ID {token!r}; use REQ-AREA-001, SPEC-AREA-001, "
+                "SCOPE-IN-001, or PLAN-TASK-001 style IDs."
+            )
+
+    # R2.3c: RISK_DISCOVERY / DESIGN / SPEC must define at least one native trace ID in a heading
+    if native is not None and not native.search(unfenced_content):
+        issues.append(
+            f"Stage {stage.value!r} must define at least one native trace ID in a heading "
+            f"matching {native.pattern!r}."
+        )
+
+    # R2.2: placeholder scan
+    for pat in _PLACEHOLDER_PATTERNS:
+        if pat.search(unfenced_content):
+            issues.append(
+                "Artifact contains an unresolved placeholder "
+                f"(pattern {pat.pattern!r}); fill it before passing the gate."
+            )
+            break
+    return issues
+
+
 # ---------------------------------------------------------------------------
 # Quality Gate
 # ---------------------------------------------------------------------------
@@ -358,14 +685,22 @@ def check_quality_gate(
         )
 
     issues: list[str] = []
+    gate_content = strip_readonly_sections(artifact_content)
 
     # Check 2: content must be non-empty
-    if not artifact_content or not artifact_content.strip():
+    if not gate_content or not gate_content.strip():
         issues.append("Artifact content is empty or whitespace-only.")
 
     if not issues:
         # Check 3: upstream reference coverage closure (all tiers)
-        unclosed = _find_ids_without_closure(artifact_content)
+        unclosed = _find_ids_without_closure(gate_content)
+        if stage == Stage.PLAN:
+            from tools.workflow_cli.trace import plan_consumed_spec_ids
+            consumed_specs = plan_consumed_spec_ids(run_dir)
+            unclosed = [
+                ref_id for ref_id in unclosed
+                if not (ref_id.startswith("SPEC-") and ref_id in consumed_specs)
+            ]
         for ref_id in unclosed:
             issues.append(
                 f"Upstream reference {ref_id!r} appears in artifact but has no closure status tag "
@@ -373,7 +708,7 @@ def check_quality_gate(
             )
 
         # Check 4: ID uniqueness within artifact
-        duplicates = _find_duplicate_ids(artifact_content)
+        duplicates = _find_duplicate_ids(gate_content)
         for dup_id in duplicates:
             issues.append(
                 f"Duplicate ID definition {dup_id!r} found in artifact; each ID must be unique."
@@ -382,26 +717,51 @@ def check_quality_gate(
         # Check 5 (PLAN, standard tier): TDD-applicable tasks must carry a code block.
         from tools.workflow_cli.models import TierBase
         if stage == Stage.PLAN and tier.base == TierBase.STANDARD:
-            if not _plan_task_starts(artifact_content):
+            if not _plan_task_starts(gate_content):
                 issues.append(
                     "PLAN is missing '### PLAN-TASK-*' sections; standard tier requires "
                     "machine-parseable executable anchors."
                 )
-            elif _plan_tasks_missing_code(artifact_content):
+            elif _plan_tasks_missing_code(gate_content):
                 issues.append(
                     "PLAN has a 'TDD Applicable: yes' task with no fenced code block; "
                     "add a Skeleton code block (standard tier requires executable anchors)."
                 )
 
+        # Check 5b (PLAN): trace closure — all upstream SPEC/RISK/SCOPE-IN IDs must be consumed.
+        if stage == Stage.PLAN:
+            from tools.workflow_cli.trace import check_trace_closure, scope_out_violations
+            issues.extend(check_trace_closure(run_dir))
+            for sid in scope_out_violations(run_dir):
+                issues.append(f"PLAN references out-of-scope item {sid}; scope overflow (R8).")
+            # R5.1: required fields + contiguous numbering
+            issues.extend(_check_plan_task_fields(gate_content))
+            # R5.2: dangling SPEC references
+            issues.extend(_check_spec_refs_valid(run_dir, gate_content))
+            # R5.2b: Skeleton is fenced, so detect template placeholders there explicitly.
+            issues.extend(_check_plan_task_skeleton_placeholders(gate_content))
+            # R5.3: file refs vs Context Pack repo_root
+            issues.extend(_check_plan_file_refs(run_dir, gate_content))
+
         # Check 6 (SPEC): the External Documentation Checked section must be present and non-empty.
         if stage == Stage.SPEC:
-            if not _has_external_docs_inventory(artifact_content):
+            if not _has_external_docs_inventory(gate_content):
                 issues.append(
                     "SPEC is missing a non-empty '## External Documentation Checked' section. "
                     "Add it; if there are no external dependencies, include an explicit "
                     "'N/A — no external dependencies' row."
                 )
 
+        # Check 7 (R2): tier-aware required-section schema.
+        if not issues:
+            issues.extend(_check_stage_schema(stage, tier, gate_content))
+
+        # Check 8 (R8): scope-freeze — In/Out-of-Scope entries must carry stable IDs.
+        issues.extend(_check_scope_freeze(stage, gate_content))
+
+        # Check 9 (R8): elicitation — standard-tier brief must record at least one assumption or open question.
+        issues.extend(_check_elicitation(stage, tier, gate_content))
+
     return GateResult(
         passed=len(issues) == 0,
         issues=issues,

package/tools/workflow_cli/link_expander.py

@@ -25,6 +25,11 @@ class LinkExpansionResult:
 _URL_PATTERN = re.compile(r'https?://[^\s\)\]\>\"\']+')
 _LOCAL_DOT_PATTERN = re.compile(r'(?:^|[\s\(\[])(\./[^\s\)\]\>\"\']+|\.{2}/[^\s\)\]\>\"\']+)')
 _LOCAL_SUBDIR_PATTERN = re.compile(r'(?:^|[\s\(\[])([a-zA-Z][a-zA-Z0-9_\-]*/[a-zA-Z0-9_\-][a-zA-Z0-9_\-./]*\.md)')
+_PREVIEWABLE_LOCAL_EXTENSIONS = frozenset({".md", ".markdown", ".rst", ".adoc"})
+_SENSITIVE_LOCAL_NAME_RE = re.compile(
+    r"(?:^|[-_.])(?:secrets?|credentials?|tokens?|passwords?|passwd|private[-_]?key|api[-_]?key)(?:$|[-_.])",
+    re.IGNORECASE,
+)
 
 
 def extract_links(text: str) -> list[str]:
@@ -54,7 +59,23 @@ def _fetch_url(url: str) -> LinkExpansionResult:
         return LinkExpansionResult(url=url, status=LinkStatus.UNREACHABLE, error=str(e))
 
 
+def _local_preview_block_reason(path_str: str, candidate: Path, base: Path | None) -> str | None:
+    try:
+        relative = candidate.relative_to(base) if base is not None else Path(path_str)
+    except ValueError:
+        relative = Path(path_str)
+    parts = [part for part in relative.parts if part not in ("", ".", "..")]
+    if any(part.startswith(".") for part in parts):
+        return "Local preview skipped for hidden path."
+    if any(_SENSITIVE_LOCAL_NAME_RE.search(part) for part in parts):
+        return "Local preview skipped for sensitive-looking path."
+    if candidate.suffix.lower() not in _PREVIEWABLE_LOCAL_EXTENSIONS:
+        return "Local preview skipped for unsupported local document extension."
+    return None
+
+
 def _expand_local(path_str: str, base_path: Path | None) -> LinkExpansionResult:
+    base = None
     if base_path is not None:
         base = base_path.resolve()
         candidate = (base / path_str).resolve()
@@ -68,6 +89,13 @@ def _expand_local(path_str: str, base_path: Path | None) -> LinkExpansionResult:
         candidate = Path(path_str).resolve()
 
     if candidate.exists() and candidate.is_file():
+        block_reason = _local_preview_block_reason(path_str, candidate, base)
+        if block_reason is not None:
+            return LinkExpansionResult(
+                url=path_str,
+                status=LinkStatus.LOCAL_FOUND,
+                error=block_reason,
+            )
         try:
             preview = candidate.read_text(encoding="utf-8", errors="ignore")[:500]
             return LinkExpansionResult(url=path_str, status=LinkStatus.LOCAL_FOUND,