@deftai/directive-content 0.55.2 → 0.56.0

package/scripts/_vbrief_story_quality.py

@@ -0,0 +1,353 @@
+"""Shared story-quality checks for decomposition and swarm readiness."""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+BROAD_FILE_SCOPE_ROOTS = {"backend", "frontend", "docs", "vbrief"}
+CODE_PATH_TERMS = (
+    "api",
+    "cli",
+    "component",
+    "config",
+    "database",
+    "endpoint",
+    "file",
+    "handler",
+    "model",
+    "module",
+    "repository",
+    "route",
+    "schema",
+    "script",
+    "service",
+    "source",
+    "src/",
+)
+VERIFY_EVIDENCE_TERMS = (
+    "assert",
+    "evidence",
+    "fixture",
+    "report",
+    "spec",
+    "test",
+    "tests/",
+    "verify",
+)
+GENERIC_VERIFY_COMMANDS = {
+    "cargo test",
+    "go test ./...",
+    "npm run test",
+    "npm test",
+    "pytest",
+    "task check",
+}
+PLACEHOLDER_ACCEPTANCE_PATTERNS = (
+    "acceptance criteria for",
+    "copy from parent",
+    "copy from specification",
+    "placeholder",
+    "refine from parent",
+    "tbd",
+    "to be defined",
+    "to refine",
+    "to refine from parent scope",
+    "todo",
+)
+DOCS_ONLY_ACCEPTANCE_PATTERNS = (
+    "docs updated",
+    "documentation updated",
+    "readme updated",
+    "update docs",
+    "update documentation",
+    "update readme",
+)
+GENERIC_IMPLEMENTATION_PATTERNS = (
+    "add tests so it works",
+    "change the code",
+    "implement the feature",
+    "make it work",
+    "update the code",
+    "works as expected",
+)
+VAGUE_ACCEPTANCE_PATTERNS = (
+    "displays a message",
+    "handles errors",
+    "is implemented",
+    "is updated",
+    "passes tests",
+    "shows a message",
+    "the system displays a message",
+    "updates the ui",
+    "works as expected",
+)
+OBSERVABLE_TERMS = (
+    "blocks",
+    "creates",
+    "deletes",
+    "displays",
+    "emits",
+    "fails",
+    "persists",
+    "records",
+    "redirects",
+    "rejects",
+    "renders",
+    "returns",
+    "saves",
+    "shows",
+    "stores",
+    "updates",
+    "validates",
+    "when ",
+    "given ",
+    "then ",
+)
+USER_STORY_RE = re.compile(
+    r"^\s*As\s+a[n]?\s+[^,]+,\s*I\s+want\s+.+,\s*so\s+that\s+.+\.\s*$",
+    re.IGNORECASE | re.DOTALL,
+)
+
+
+def as_str_list(value: Any) -> list[str]:
+    if value is None:
+        return []
+    if isinstance(value, str):
+        return [value.strip()] if value.strip() else []
+    if isinstance(value, list):
+        return [str(item).strip() for item in value if str(item).strip()]
+    return []
+
+
+def acceptance_texts_from_items(items: Any) -> list[str]:
+    texts: list[str] = []
+    if not isinstance(items, list):
+        return texts
+    for item in items:
+        if not isinstance(item, dict):
+            continue
+        narrative = item.get("narrative")
+        if isinstance(narrative, dict):
+            acceptance = narrative.get("Acceptance")
+            if isinstance(acceptance, str) and acceptance.strip():
+                texts.append(acceptance.strip())
+        for child_key in ("items", "subItems"):
+            texts.extend(acceptance_texts_from_items(item.get(child_key)))
+    return texts
+
+
+def item_has_acceptance(item: dict[str, Any]) -> bool:
+    narrative = item.get("narrative")
+    if isinstance(narrative, dict):
+        value = narrative.get("Acceptance")
+        if isinstance(value, str) and value.strip():
+            return True
+    for child_key in ("items", "subItems"):
+        children = item.get(child_key)
+        if isinstance(children, list):
+            for child in children:
+                if isinstance(child, dict) and item_has_acceptance(child):
+                    return True
+    return False
+
+
+def items_have_acceptance(items: Any) -> bool:
+    if not isinstance(items, list):
+        return False
+    return any(isinstance(item, dict) and item_has_acceptance(item) for item in items)
+
+
+def item_has_traces(item: dict[str, Any]) -> bool:
+    narrative = item.get("narrative")
+    if isinstance(narrative, dict):
+        value = narrative.get("Traces")
+        if isinstance(value, str) and value.strip():
+            return True
+    for child_key in ("items", "subItems"):
+        children = item.get(child_key)
+        if isinstance(children, list):
+            for child in children:
+                if isinstance(child, dict) and item_has_traces(child):
+                    return True
+    return False
+
+
+def missing_required_swarm_fields(swarm: dict[str, Any]) -> list[str]:
+    missing: list[str] = []
+    for key in ("file_scope", "verify_commands", "expected_outputs"):
+        if not as_str_list(swarm.get(key)):
+            missing.append(f"plan.metadata.swarm.{key}")
+    if "depends_on" not in swarm:
+        missing.append("plan.metadata.swarm.depends_on")
+    for key in ("conflict_group", "size", "file_scope_confidence", "model_tier"):
+        value = swarm.get(key)
+        if not isinstance(value, str) or not value.strip():
+            missing.append(f"plan.metadata.swarm.{key}")
+    return missing
+
+
+def deprecated_subitems_issues(items: Any, prefix: str = "plan.items") -> list[str]:
+    issues: list[str] = []
+
+    def visit(children: Any, path: str) -> None:
+        if not isinstance(children, list):
+            return
+        for index, item in enumerate(children):
+            if not isinstance(item, dict):
+                continue
+            item_path = f"{path}[{index}]"
+            if "subItems" in item:
+                issues.append(f"{item_path}.subItems is deprecated; use items")
+            visit(item.get("items"), f"{item_path}.items")
+            visit(item.get("subItems"), f"{item_path}.subItems")
+
+    visit(items, prefix)
+    return issues
+
+
+def story_quality_issues(
+    *,
+    title: str,
+    description: str,
+    implementation_plan: str,
+    user_story: str,
+    acceptance_texts: list[str],
+    acceptance_count_justification: str,
+    swarm: dict[str, Any],
+    concurrent_ready: bool = True,
+) -> list[str]:
+    issues: list[str] = []
+    if not USER_STORY_RE.match(user_story or ""):
+        issues.append(
+            "UserStory must match 'As a <role>, I want <capability>, so that <outcome>.'"
+        )
+    issues.extend(_description_issues(description))
+    issues.extend(_implementation_plan_issues(implementation_plan))
+    if not (2 <= len(acceptance_texts) <= 5) and not acceptance_count_justification.strip():
+        issues.append("2-5 acceptance criteria required unless justified")
+
+    normalized_title = _normalize(title)
+    normalized_description = _normalize(description)
+    for criterion in acceptance_texts:
+        normalized = _normalize(criterion)
+        lower = criterion.lower()
+        if any(pattern in lower for pattern in PLACEHOLDER_ACCEPTANCE_PATTERNS):
+            issues.append("placeholder acceptance criterion")
+        if normalized and normalized in {normalized_title, normalized_description}:
+            issues.append("acceptance criterion duplicates title or description")
+        if any(pattern in lower for pattern in DOCS_ONLY_ACCEPTANCE_PATTERNS):
+            issues.append("vague docs-only acceptance criterion")
+        if _word_count(criterion) < 8 or any(
+            pattern in lower for pattern in VAGUE_ACCEPTANCE_PATTERNS
+        ):
+            issues.append("acceptance criterion must describe specific observable behavior")
+        if not _looks_observable(lower):
+            issues.append("acceptance criterion must describe observable behavior")
+
+    if concurrent_ready:
+        issues.extend(_file_scope_issues(swarm))
+        issues.extend(_verify_command_issues(swarm))
+        if swarm.get("parallel_safe") is False:
+            issues.append(
+                "readiness=ready requires parallel_safe=true; use readiness=sequential "
+                "or needs_refinement for non-concurrent work"
+            )
+        if swarm.get("file_scope_confidence") == "low":
+            issues.append("readiness=ready requires file_scope_confidence above low")
+    return _dedupe(issues)
+
+
+def _file_scope_issues(swarm: dict[str, Any]) -> list[str]:
+    issues: list[str] = []
+    for file_path in as_str_list(swarm.get("file_scope")):
+        normalized = file_path.strip().strip("/")
+        root = normalized.split("/", 1)[0]
+        if (
+            any(ch in normalized for ch in "*?[")
+            or normalized in BROAD_FILE_SCOPE_ROOTS
+            or file_path.rstrip("/") in BROAD_FILE_SCOPE_ROOTS
+            or (root in BROAD_FILE_SCOPE_ROOTS and normalized in {root, f"{root}/*"})
+        ):
+            issues.append(f"broad file_scope is not swarm-ready: {file_path}")
+    return issues
+
+
+def _verify_command_issues(swarm: dict[str, Any]) -> list[str]:
+    commands = [command.lower() for command in as_str_list(swarm.get("verify_commands"))]
+    if len(commands) == 1 and _normalize_command(commands[0]) in GENERIC_VERIFY_COMMANDS:
+        return [f"generic verify command is not swarm-ready: {commands[0]}"]
+    return []
+
+
+def _description_issues(description: str) -> list[str]:
+    if not description.strip():
+        return ["plan.narratives.Description is required"]
+    if _sentence_count(description) < 2 or _word_count(description) < 20:
+        return ["plan.narratives.Description must contain at least two concrete sentences"]
+    return []
+
+
+def _implementation_plan_issues(implementation_plan: str) -> list[str]:
+    if not implementation_plan.strip():
+        return ["plan.narratives.ImplementationPlan is required"]
+    issues: list[str] = []
+    if _step_count(implementation_plan) < 2 or _word_count(implementation_plan) < 20:
+        issues.append(
+            "plan.narratives.ImplementationPlan must contain at least two concrete steps"
+        )
+    lower = implementation_plan.lower()
+    if any(pattern in lower for pattern in PLACEHOLDER_ACCEPTANCE_PATTERNS):
+        issues.append("plan.narratives.ImplementationPlan must not be placeholder text")
+    if any(pattern in lower for pattern in GENERIC_IMPLEMENTATION_PATTERNS) or not (
+        any(term in lower for term in CODE_PATH_TERMS)
+        and any(term in lower for term in VERIFY_EVIDENCE_TERMS)
+    ):
+        issues.append(
+            "plan.narratives.ImplementationPlan must identify concrete code paths "
+            "and verification evidence"
+        )
+    return issues
+
+
+def _looks_observable(lower: str) -> bool:
+    return any(term in lower for term in OBSERVABLE_TERMS)
+
+
+def _sentence_count(value: str) -> int:
+    return len([part for part in re.split(r"[.!?]+(?:\s+|$)", value.strip()) if part.strip()])
+
+
+def _step_count(value: str) -> int:
+    lines = [line.strip() for line in value.splitlines() if line.strip()]
+    bullet_lines = [
+        line
+        for line in lines
+        if re.match(r"^([-*]|\d+[.)])\s+", line)
+    ]
+    if len(bullet_lines) >= 2:
+        return len(bullet_lines)
+    return _sentence_count(value)
+
+
+def _word_count(value: str) -> int:
+    return len(re.findall(r"\b\w+\b", value))
+
+
+def _normalize(value: str) -> str:
+    return re.sub(r"[^a-z0-9]+", " ", value.lower()).strip()
+
+
+def _normalize_command(value: str) -> str:
+    return re.sub(r"\s+", " ", value.strip().lower())
+
+
+def _dedupe(values: list[str]) -> list[str]:
+    out: list[str] = []
+    seen: set[str] = set()
+    for value in values:
+        if value in seen:
+            continue
+        seen.add(value)
+        out.append(value)
+    return out

package/scripts/_vbrief_validation.py

@@ -0,0 +1,299 @@
+r"""Shared validation and slug-safe ID helpers for the vBRIEF migrator (#498).
+
+Extracted from ``scripts/migrate_vbrief.py`` so the migrator stays under the
+1000-line hard cap documented in ``deft/coding/coding.md`` while still
+hard-blocking on schema-invalid output (per #506 D8).
+
+Public API
+----------
+* ``slugify_id(raw, existing=None)`` -- single sanitiser used for BOTH the
+  filename slug component AND every in-JSON identifier
+  (``plan.items[*].id``, ``plan.id``, scope-registry ids) emitted by the
+  migrator. Conforms to the schema-locked ID regex
+  ``^[a-zA-Z0-9_-]+(\.[a-zA-Z0-9_-]+)*$`` (shared conventions #506) by
+  restricting output to lowercase ASCII letters, digits, and hyphens only.
+  Also satisfies the stricter lifecycle-folder filename validator
+  (``^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*\.vbrief\.json$``) which
+  disallows underscores and dots -- hyphen-only output keeps a single
+  implementation that passes both surfaces.
+* ``slug_fallback_id(item)`` -- resolve the logical identifier source for a
+  roadmap/scope ``item`` dict in the preference order used by both filename
+  construction and the PROJECT-DEFINITION scope registry, so both surfaces
+  compute the same slug input from the same item.
+* ``validate_migration_output(vbrief_dir)`` -- thin wrapper around
+  ``vbrief_validate.validate_all`` scoped to the migrator's emitted-file set.
+  Returns ``(errors, warnings)`` with full per-file diagnostics.
+* ``isolate_invalid_output(project_root, vbrief_dir)`` -- on validation
+  failure, move the emitted ``vbrief/`` tree to ``vbrief.invalid/`` (with a
+  numeric suffix on collision) so the operator can inspect the partial
+  output without it blocking subsequent migrator runs. Pre-migration
+  ``.premigrate.*`` backups (Agent C, #497) are left untouched.
+* ``finalize_migration(project_root, vbrief_dir, actions)`` -- terminal
+  validate + isolate step the migrator plugs in at the end of its body.
+* ``RECOVERY_HINT`` -- canonical CLI recovery hint printed on failure.
+
+Story: #498 (migrate:vbrief self-validation + slug-safe IDs + golden tests).
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import sys
+from pathlib import Path
+
+# Ensure sibling ``vbrief_validate`` is importable whether this module is
+# imported from a test harness (which inserts ``scripts/`` onto sys.path) or
+# from ``scripts/migrate_vbrief.py`` itself (which performs the same insert
+# at the top of its module).
+_SCRIPTS_DIR = Path(__file__).resolve().parent
+if str(_SCRIPTS_DIR) not in sys.path:
+    sys.path.insert(0, str(_SCRIPTS_DIR))
+
+import vbrief_validate  # noqa: E402  (import after sys.path mutation)
+
+__all__ = [
+    "RECOVERY_HINT",
+    "slugify_id",
+    "slug_fallback_id",
+    "validate_migration_output",
+    "isolate_invalid_output",
+    "finalize_migration",
+    "ID_MAX_LENGTH",
+    "HASH_SUFFIX_LENGTH",
+]
+
+# Canonical recovery hint surfaced when the migrator hard-blocks on
+# schema-invalid output (#506 D8). Agent C (#497) owns the ``--rollback`` flag
+# implementation; this module only references the flag by name.
+RECOVERY_HINT = "Restore with: task migrate:vbrief -- --rollback"
+
+# Per #498: slug-safe IDs truncate to 80 characters. The optional 6-char hash
+# suffix reserves ``1 + 6 = 7`` characters so the base slug before the suffix
+# is 73 characters max -- keeps total length <= 80 for collision-disambiguated
+# values.
+ID_MAX_LENGTH = 80
+HASH_SUFFIX_LENGTH = 6
+
+
+def slugify_id(raw: str | None, existing: set[str] | None = None) -> str:
+    """Return a slug-safe id for filenames and in-JSON id fields (#498).
+
+    Rules (per #498 acceptance criteria and #506 shared conventions):
+
+    * lowercase ASCII letters, digits, and hyphens only
+    * runs of any non-allowed character collapse to a single hyphen
+    * leading/trailing hyphens are stripped
+    * truncate to ``ID_MAX_LENGTH`` (80) characters
+    * when ``existing`` is provided and the resulting slug collides,
+      append a stable 6-char hex suffix derived from the raw input so
+      repeated migrations produce the same disambiguated value; if that
+      still collides, perturb the hash deterministically until unique
+
+    Parameters
+    ----------
+    raw:
+        The raw input text to slugify. ``None`` and empty values are
+        normalised to ``"untitled"``.
+    existing:
+        Optional mutable set used as the "already-emitted" registry. When
+        provided, the returned slug is added to the set so subsequent calls
+        can detect collisions. Pass ``None`` for one-shot slug computation
+        (no collision tracking).
+
+    Returns
+    -------
+    str
+        A slug matching ``^[a-z0-9]+(-[a-z0-9]+)*$`` -- conforms to both the
+        schema ID regex and the lifecycle filename regex.
+    """
+    text = (raw or "").strip()
+    slug = re.sub(r"[^a-z0-9]+", "-", text.lower())
+    slug = re.sub(r"-+", "-", slug).strip("-")
+    if not slug:
+        slug = "untitled"
+    if len(slug) > ID_MAX_LENGTH:
+        slug = slug[:ID_MAX_LENGTH].rstrip("-") or slug[:ID_MAX_LENGTH]
+
+    if existing is None:
+        return slug
+
+    if slug not in existing:
+        existing.add(slug)
+        return slug
+
+    # Collision path -- append a stable 6-char hash suffix. Seed from the
+    # original raw input (falls back to the computed slug when raw is empty)
+    # so repeated migrations with the same content yield the same suffix.
+    digest_seed = text or slug
+    base_max = ID_MAX_LENGTH - 1 - HASH_SUFFIX_LENGTH  # "-" + 6 hex chars
+    base = slug[:base_max].rstrip("-") or slug[:base_max] or "id"
+    h = hashlib.sha1(digest_seed.encode("utf-8")).hexdigest()[:HASH_SUFFIX_LENGTH]
+    candidate = f"{base}-{h}"
+
+    attempt = 0
+    while candidate in existing and attempt < 1000:
+        attempt += 1
+        h2 = hashlib.sha1(
+            f"{digest_seed}|{attempt}".encode()
+        ).hexdigest()[:HASH_SUFFIX_LENGTH]
+        candidate = f"{base}-{h2}"
+
+    existing.add(candidate)
+    return candidate
+
+
+def slug_fallback_id(item: dict) -> str:
+    """Return the logical identifier source for a scope ``item`` dict.
+
+    Preference order mirrors the filename construction in Step 4 / 4b so
+    both surfaces (PROJECT-DEFINITION scope registry id AND scope vBRIEF
+    filename) resolve the same logical identifier from the same item:
+
+    1. GitHub issue ``number``
+    2. Explicit ``task_id``
+    3. ``synthetic_id`` (assigned by the ROADMAP parser fallback)
+    4. ``title`` (used when nothing else is available)
+
+    Returns the raw (un-slugified) string; callers are expected to pipe the
+    result through :func:`slugify_id`.
+    """
+    number = str(item.get("number", "") or "")
+    if number:
+        return number
+    task_id = str(item.get("task_id", "") or "")
+    if task_id:
+        return task_id
+    synthetic = str(item.get("synthetic_id", "") or "")
+    if synthetic:
+        return synthetic
+    return str(item.get("title", "") or "untitled")
+
+
+def validate_migration_output(
+    vbrief_dir: Path,
+) -> tuple[list[str], list[str]]:
+    """Validate every file emitted by the migrator under ``vbrief_dir``.
+
+    Delegates the heavy lifting to :func:`vbrief_validate.validate_all`,
+    which already implements the full D2/D3/D4/D7/D11 rule set plus schema
+    validation for scope vBRIEFs and PROJECT-DEFINITION.vbrief.json.
+
+    Returns
+    -------
+    (errors, warnings):
+        ``errors`` is a list of human-readable diagnostic strings; when
+        non-empty the migrator MUST exit non-zero per #506 D8 (hard-block on
+        schema-invalid output). ``warnings`` are surfaced but do NOT block
+        success -- they follow the same semantics as
+        ``scripts/vbrief_validate.py`` (e.g. D11 origin provenance warnings
+        for pending/active without a github-issue reference).
+    """
+    if not vbrief_dir.is_dir():
+        # Nothing emitted -- fail loudly so the caller reports something
+        # useful rather than silently accepting an empty migration.
+        return (
+            [f"{vbrief_dir}: expected vbrief directory does not exist"],
+            [],
+        )
+
+    errors, warnings, _scope_count = vbrief_validate.validate_all(vbrief_dir)
+    return list(errors), list(warnings)
+
+
+def isolate_invalid_output(
+    project_root: Path, vbrief_dir: Path
+) -> Path | None:
+    """Move the emitted ``vbrief/`` tree to ``vbrief.invalid/`` on failure.
+
+    Per #506 D8: schema-invalid migration output must be isolated from
+    ``vbrief/`` so downstream tasks (``task check`` / ``task scope:*`` /
+    renders) don't consume broken state. Agent C's ``.premigrate.*`` backups
+    remain untouched at the project root so ``task migrate:vbrief --
+    --rollback`` can restore the pre-migration state.
+
+    Returns the destination path, or ``None`` when ``vbrief_dir`` does not
+    exist (nothing to move).
+
+    Collision handling: if ``vbrief.invalid/`` already exists (e.g. from a
+    prior failed migration), increment a numeric suffix -- ``vbrief.invalid.2``,
+    ``vbrief.invalid.3``, etc. -- so operators retain the history of failed
+    attempts instead of overwriting.
+    """
+    if not vbrief_dir.exists():
+        return None
+
+    target = project_root / "vbrief.invalid"
+    idx = 1
+    while target.exists():
+        idx += 1
+        target = project_root / f"vbrief.invalid.{idx}"
+
+    vbrief_dir.rename(target)
+    return target
+
+
+def finalize_migration(
+    project_root: Path,
+    vbrief_dir: Path,
+    actions: list[str],
+) -> tuple[bool, list[str]]:
+    """Run validation + isolation as the migrator's terminal gate (#498).
+
+    Designed as a drop-in terminal step for ``scripts/migrate_vbrief.py::
+    migrate`` so the migrator body stays under the 1000-line hard cap.
+    Pipes diagnostics to stderr and returns the final ``(ok, actions)``
+    tuple that the migrator should propagate to its CLI entry point:
+
+    * On success: returns ``(True, actions)`` untouched -- caller prints its
+      normal success message ("Migration completed successfully.").
+    * On failure: prints per-file diagnostics to stderr, moves ``vbrief/``
+      to ``vbrief.invalid/`` (isolation), appends failure diagnostics and a
+      ``Restore with: task migrate:vbrief -- --rollback`` recovery hint to a
+      copy of ``actions``, and returns ``(False, failure_actions)``.
+
+    The ``actions`` list passed in is NOT mutated so callers can reuse it
+    for downstream logging independent of migration outcome.
+    """
+    errors, warnings = validate_migration_output(vbrief_dir)
+    if not errors:
+        # Surface non-blocking validator warnings (e.g. D11 origin-provenance
+        # warnings for pending/active scopes without a github-issue reference)
+        # so operators see them even on the success path. Matches the
+        # ``scripts/vbrief_validate.py`` CLI behaviour where warnings print
+        # but do not change exit code.
+        for w in warnings:
+            print(f"WARNING: {w}", file=sys.stderr)
+        return True, actions
+
+    print(
+        f"ERROR: Migration produced invalid output ({len(errors)} "
+        f"file-level error(s)):",
+        file=sys.stderr,
+    )
+    for err in errors:
+        print(f"  {err}", file=sys.stderr)
+
+    invalid_dir = isolate_invalid_output(project_root, vbrief_dir)
+
+    failure_actions: list[str] = list(actions)
+    failure_actions.append(
+        f"FAIL  migration produced {len(errors)} schema validation error(s)"
+    )
+    for err in errors:
+        failure_actions.append(f"  {err}")
+    if invalid_dir is not None:
+        try:
+            rel_invalid = invalid_dir.relative_to(project_root)
+        except ValueError:
+            rel_invalid = invalid_dir
+        failure_actions.append(
+            f"MOVE  vbrief/ -> {rel_invalid}/ (isolated from vbrief/)"
+        )
+        print(
+            f"Isolated partial output to: {rel_invalid}",
+            file=sys.stderr,
+        )
+    failure_actions.append(RECOVERY_HINT)
+    print(RECOVERY_HINT, file=sys.stderr)
+    return False, failure_actions