@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/_vbrief_story_quality.py

@@ -1,353 +0,0 @@
-"""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

@@ -1,299 +0,0 @@
-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