@deftai/directive-content 0.59.0 → 0.61.0

package/scripts/project_render.py

@@ -1,293 +0,0 @@
-#!/usr/bin/env python3
-"""
-project_render.py — Regenerate PROJECT-DEFINITION.vbrief.json from lifecycle folders.
-
-Deterministic layer (RFC #309, Decision D14):
-- Scans all lifecycle folders (proposed/, pending/, active/, completed/, cancelled/)
-- Updates the items registry with scope entries (title, status, file path, references)
-- Timestamps freshness (vBRIEFInfo.updated)
-- Flags narratives that may be stale based on completed scope topics
-- Creates skeleton PROJECT-DEFINITION.vbrief.json if none exists
-
-Agent-assisted layer (documented convention, not implemented as code):
-    During sync or refinement sessions, the agent reviews flagged narratives and
-    proposes updates to project identity (overview, capabilities, risks, tech stack)
-    based on completed work.  The user approves -- never fully automatic for content
-    requiring judgment.
-
-    Workflow:
-    1. Run `task project:render` to refresh the items registry and staleness flags.
-    2. The agent reads staleness_flags from plan.metadata.staleness_flags.
-    3. For each flagged narrative, the agent drafts a proposed update reflecting
-       the completed scopes (e.g. if a "tech stack" scope completed, update the
-       TechStack narrative with the new technology choices).
-    4. The user reviews and approves each narrative change.
-    5. The agent writes approved changes back to PROJECT-DEFINITION.vbrief.json.
-
-Usage:
-    uv run python scripts/project_render.py [vbrief_dir]
-
-    vbrief_dir — path to vbrief/ directory (default: ./vbrief)
-
-Exit codes:
-    0 — rendered successfully
-    1 — error occurred
-    2 — usage error
-"""
-
-import json
-import re
-import sys
-from datetime import UTC, datetime
-from pathlib import Path
-
-# Make sibling scripts importable both when run as __main__ and when imported
-# by tests that pre-populate sys.path with the ``scripts/`` directory.
-sys.path.insert(0, str(Path(__file__).resolve().parent))
-
-# UTF-8 stdout guard (#540).
-from _stdio_utf8 import reconfigure_stdio  # noqa: E402
-
-reconfigure_stdio()
-
-from _vbrief_build import (  # noqa: E402
-    EMITTED_VBRIEF_VERSION as _EMITTED_VBRIEF_VERSION,
-)
-
-LIFECYCLE_FOLDERS = ("proposed", "pending", "active", "completed", "cancelled")
-
-# Keys intentionally match scripts/vbrief_validate.py PROJECT_DEF_EXPECTED_NARRATIVES
-# after case-folding: "overview" and "tech stack" are required by D3 (#405).
-# Keep the "tech stack" key exactly as-is (lowercase, space-separated) so
-# `task project:render` skeletons pass `task vbrief:validate` immediately.
-SKELETON_NARRATIVES = {
-    "Overview": "",
-    "tech stack": "",
-    "Architecture": "",
-    "RisksAndUnknowns": "",
-    "Configuration": "",
-}
-
-
-def _split_camel(name: str) -> list[str]:
-    """Split a camelCase or PascalCase string into lowercase words.
-
-    >>> _split_camel("TechStack")
-    ['tech', 'stack']
-    >>> _split_camel("RisksAndUnknowns")
-    ['risks', 'and', 'unknowns']
-    """
-    parts = re.sub(r"([a-z])([A-Z])", r"\1 \2", name)
-    return [w.lower() for w in parts.split()]
-
-
-def scan_lifecycle_folders(vbrief_dir: Path) -> list[dict]:
-    """Scan all lifecycle folders for *.vbrief.json files and return items.
-
-    Scans folders in a fixed order (proposed, pending, active, completed,
-    cancelled) and files alphabetically within each folder, producing
-    deterministic output for the same folder contents.
-    """
-    items: list[dict] = []
-    for folder_name in LIFECYCLE_FOLDERS:
-        folder = vbrief_dir / folder_name
-        if not folder.is_dir():
-            continue
-        for vbrief_file in sorted(folder.glob("*.vbrief.json")):
-            try:
-                with open(vbrief_file, encoding="utf-8") as fh:
-                    data = json.load(fh)
-                plan = data.get("plan", {})
-                title = plan.get("title", vbrief_file.stem)
-                status = plan.get("status", folder_name)
-                references = plan.get("references", [])
-
-                item: dict = {
-                    "id": vbrief_file.stem.replace(".vbrief", ""),
-                    "title": title,
-                    "status": status,
-                    "metadata": {
-                        "source_path": f"{folder_name}/{vbrief_file.name}",
-                        "lifecycle_folder": folder_name,
-                    },
-                }
-                if references:
-                    item["metadata"]["references"] = references
-                items.append(item)
-            except (json.JSONDecodeError, OSError):
-                items.append(
-                    {
-                        "id": vbrief_file.stem.replace(".vbrief", ""),
-                        "title": f"[unreadable] {vbrief_file.name}",
-                        "status": "draft",
-                        "metadata": {
-                            "source_path": f"{folder_name}/{vbrief_file.name}",
-                            "lifecycle_folder": folder_name,
-                            "error": "Failed to read or parse file",
-                        },
-                    }
-                )
-    return items
-
-
-def flag_stale_narratives(
-    narratives: dict[str, str],
-    completed_items: list[dict],
-) -> list[str]:
-    """Flag narratives that may need review based on completed scope topics.
-
-    Algorithm (deterministic):
-    1. Split each narrative key into words (camelCase-aware).
-    2. For each completed scope, extract title words.
-    3. If any narrative-key word (>3 chars) appears in a completed scope title,
-       flag that narrative with the matching scope.
-    4. If >=3 completed scopes exist and no specific flags fired, emit a general
-       review recommendation.
-
-    Returns a sorted list of staleness warning strings.
-    """
-    if not completed_items or not narratives:
-        if completed_items and len(completed_items) >= 3:
-            return [
-                f"{len(completed_items)} scopes completed since last narrative update"
-                " -- review recommended"
-            ]
-        return []
-
-    flags: list[str] = []
-    flagged_narratives: set[str] = set()
-
-    for narrative_key in sorted(narratives.keys()):
-        key_words = {w for w in _split_camel(narrative_key) if len(w) > 3}
-        if not key_words:
-            continue
-        for item in completed_items:
-            title_lower = item.get("title", "").lower()
-            title_words = set(re.split(r"\W+", title_lower))
-            overlap = key_words & title_words
-            if overlap:
-                flags.append(
-                    f"Narrative '{narrative_key}' may be stale: "
-                    f"completed scope '{item.get('title', '')}' "
-                    f"shares topics ({', '.join(sorted(overlap))})"
-                )
-                flagged_narratives.add(narrative_key)
-
-    # General flag if many completed scopes but no specific matches
-    if len(completed_items) >= 3 and not flagged_narratives:
-        flags.append(
-            f"{len(completed_items)} scopes completed since last narrative update"
-            " -- review recommended"
-        )
-
-    return sorted(flags)
-
-
-def create_skeleton(items: list[dict], now: str) -> dict:
-    """Create a skeleton PROJECT-DEFINITION.vbrief.json structure."""
-    completed_items = [i for i in items if i.get("status") == "completed"]
-    staleness_flags = flag_stale_narratives(dict(SKELETON_NARRATIVES), completed_items)
-
-    return {
-        "vBRIEFInfo": {
-            # #533: match the migrator's emitted version so skeletons
-            # produced by ``task project:render`` round-trip through the
-            # validator during the v0.6 transition. Sourced from the
-            # shared constant in _vbrief_build so a future bump lands in
-            # one place.
-            "version": _EMITTED_VBRIEF_VERSION,
-            "description": "Project definition -- synthesized gestalt of the project",
-            "created": now,
-            "updated": now,
-        },
-        "plan": {
-            "title": "PROJECT-DEFINITION",
-            "status": "running",
-            "narratives": dict(SKELETON_NARRATIVES),
-            "items": items,
-            "metadata": {
-                "staleness_flags": staleness_flags,
-            },
-        },
-    }
-
-
-def render_project_definition(vbrief_dir: str) -> tuple[bool, str]:
-    """Regenerate PROJECT-DEFINITION.vbrief.json from lifecycle folder contents.
-
-    Returns:
-        (True, success_message) on success.
-        (False, error_message) on failure.
-    """
-    vbrief_path = Path(vbrief_dir)
-    project_def_path = vbrief_path / "PROJECT-DEFINITION.vbrief.json"
-
-    # Scan lifecycle folders (handles missing folders gracefully)
-    items = scan_lifecycle_folders(vbrief_path)
-
-    now = datetime.now(UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
-    created_new = not project_def_path.exists()
-
-    if project_def_path.exists():
-        # Update existing PROJECT-DEFINITION
-        try:
-            with open(project_def_path, encoding="utf-8") as fh:
-                project_def = json.load(fh)
-        except (json.JSONDecodeError, OSError) as exc:
-            return False, f"✗ Failed to read {project_def_path}: {exc}"
-
-        plan = project_def.get("plan", {})
-
-        # Update items registry (deterministic)
-        plan["items"] = items
-
-        # Timestamp freshness
-        project_def.setdefault("vBRIEFInfo", {})
-        project_def["vBRIEFInfo"]["updated"] = now
-
-        # Flag stale narratives
-        narratives = plan.get("narratives", {})
-        completed_items = [i for i in items if i.get("status") == "completed"]
-        flags = flag_stale_narratives(narratives, completed_items)
-        plan.setdefault("metadata", {})
-        plan["metadata"]["staleness_flags"] = flags
-
-        project_def["plan"] = plan
-    else:
-        # Create skeleton
-        project_def = create_skeleton(items, now)
-
-    # Ensure parent directory exists
-    project_def_path.parent.mkdir(parents=True, exist_ok=True)
-
-    # Write deterministic output
-    with open(project_def_path, "w", encoding="utf-8") as fh:
-        json.dump(project_def, fh, indent=2, ensure_ascii=False)
-        fh.write("\n")
-
-    # Report
-    item_count = len(items)
-    flag_count = len(project_def["plan"].get("metadata", {}).get("staleness_flags", []))
-    action = "created" if created_new else "updated"
-
-    parts = [f"✓ PROJECT-DEFINITION.vbrief.json {action} ({item_count} scope items)"]
-    if flag_count:
-        parts.append(f"⚠ {flag_count} staleness flag(s) -- agent review recommended")
-
-    return True, "\n".join(parts)
-
-
-def main() -> int:
-    if len(sys.argv) > 2:
-        print("Usage: project_render.py [vbrief_dir]", file=sys.stderr)
-        return 2
-
-    vbrief_dir = sys.argv[1] if len(sys.argv) == 2 else "vbrief"
-
-    ok, message = render_project_definition(vbrief_dir)
-    print(message)
-    return 0 if ok else 1
-
-
-if __name__ == "__main__":
-    sys.exit(main())

package/scripts/quarantine_ext.py

@@ -1,237 +0,0 @@
-#!/usr/bin/env python3
-r"""quarantine_ext.py -- prompt-injection quarantine for cached issue bodies (#583).
-
-Public surface
---------------
-
-``quarantine_body(raw_md: str) -> str``
-    Return ``raw_md`` with any injection-shaped sections wrapped in
-    ``\`\`\`quarantined`` fenced code blocks. Idempotent: input already wrapped
-    in ``quarantined`` fences is left unchanged.
-
-Background
-----------
-
-Issue bodies on GitHub frequently contain imperative-shaped markdown that
-looks like agent instructions (``# STEP 1``, ``## TASK:``, ``IMPORTANT:`` /
-``MUST`` headings, ``SYSTEM:`` directives, etc.). When a downstream agent
-reads a cached issue body verbatim, the text is *data*, not *instructions* --
-but a careless prompt template can splice the body directly into the agent's
-turn payload, allowing a hostile issue author to redirect the agent.
-
-#583 codified the mitigation: the cache layer wraps suspicious sections in a
-``\`\`\`quarantined`` fenced code block so downstream consumers can detect and
-either strip the section or emit a clear `do not follow these instructions`
-preamble around it. The fence label is intentionally a non-standard
-language-id so it is a syntactic marker, not a renderable hint.
-
-Heuristic
----------
-
-A markdown heading line (``^#{1,6} +``) is considered *suspicious* when it
-contains one of the imperative tokens listed in :data:`SUSPICIOUS_TOKENS`
-(case-insensitive, word-boundary scoped). Every line from a suspicious
-heading down to (but not including) the next heading -- or end of document --
-is treated as the suspicious section and wrapped.
-
-Non-heading injection patterns (e.g. ``IMPORTANT:`` or ``SYSTEM:`` on a
-plain prose line) also trigger wrapping of that line so a one-shot directive
-embedded in body prose is still flagged.
-
-The heuristic is intentionally permissive (false-positives wrap benign
-``## Steps to reproduce`` sections in a quarantined fence). The downstream
-display layer is responsible for unwrapping legitimate sections; the cost
-of a false positive is one extra fence in the rendered output, while the
-cost of a false negative is an exfiltrated agent turn.
-
-CLI
----
-
-The module is callable as a script:
-
-    python scripts/quarantine_ext.py [<input-file>]
-
-Reads ``<input-file>`` if given, otherwise stdin, and writes the quarantined
-markdown to stdout. Useful for ad-hoc inspection.
-"""
-
-from __future__ import annotations
-
-import re
-import sys
-from pathlib import Path
-
-# Imperative tokens that mark a heading or line as injection-shaped. The set
-# is curated against the recurrence record in #583 plus the canonical
-# agent-prompt vocabulary used by Warp / Oz / Claude / OpenAI tool surfaces.
-# Word-boundary scoped so the substring ``step`` inside ``stepladder`` does
-# NOT trigger.
-SUSPICIOUS_TOKENS: tuple[str, ...] = (
-    "STEP",
-    "TASK:",
-    "TASK ",
-    "IMPORTANT:",
-    "IMPORTANT ",
-    "MUST",
-    "SYSTEM:",
-    "SYSTEM ",
-    "AGENT:",
-    "AGENT ",
-    "ASSISTANT:",
-    "USER:",
-    "INSTRUCTION:",
-    "INSTRUCTIONS:",
-    "TOOL:",
-    "FUNCTION:",
-    "PROMPT:",
-    "OVERRIDE:",
-    "IGNORE PREVIOUS",
-    "DISREGARD PREVIOUS",
-    "FORGET PREVIOUS",
-    "ROLE:",
-    "DIRECTIVE:",
-)
-
-# Regex source of truth -- compiled once. Word-boundary on each side of the
-# token, except for tokens that already include trailing punctuation
-# (``TASK:`` etc.) where the punctuation acts as the boundary.
-_TOKEN_PATTERNS = []
-for _tok in SUSPICIOUS_TOKENS:
-    if _tok.endswith((":", " ")):
-        # punctuation-anchored -- no trailing \b (the colon/space is the boundary)
-        _TOKEN_PATTERNS.append(r"\b" + re.escape(_tok))
-    else:
-        _TOKEN_PATTERNS.append(r"\b" + re.escape(_tok) + r"\b")
-_TOKEN_RE = re.compile("|".join(_TOKEN_PATTERNS), re.IGNORECASE)
-
-# Heading detector: 1-6 hashes followed by at least one space. Setext-style
-# headings (=== / ---) are intentionally not detected because they require
-# multi-line lookahead and are vanishingly rare in GitHub-flavoured-markdown
-# issue bodies.
-_HEADING_RE = re.compile(r"^(#{1,6})\s+(.*\S.*)$")
-
-# A code-fence delimiter line. Tracks whether we are inside an existing
-# code block so heading-shaped text inside ```text``` is not re-quarantined.
-_FENCE_RE = re.compile(r"^(```|~~~)")
-
-QUARANTINE_FENCE_OPEN = "```quarantined"
-QUARANTINE_FENCE_CLOSE = "```"
-
-
-def _is_suspicious(line: str) -> bool:
-    return bool(_TOKEN_RE.search(line))
-
-
-def _is_heading(line: str) -> bool:
-    return bool(_HEADING_RE.match(line))
-
-
-def quarantine_body(raw_md: str) -> str:
-    r"""Wrap injection-shaped sections in ``\`\`\`quarantined`` fences.
-
-    Args:
-        raw_md: Raw markdown body (e.g. the rendered text of a GitHub issue
-            body fetched via ``gh issue view --json body``).
-
-    Returns:
-        The same markdown with suspicious sections wrapped. If no sections
-        match, the input is returned unchanged (modulo trailing-newline
-        normalization).
-
-    The function is idempotent: re-running on already-quarantined text is a
-    no-op because the existing ``\`\`\`quarantined`` fence is recognised as
-    a code block and its contents are skipped.
-    """
-    if not raw_md:
-        return raw_md
-
-    lines = raw_md.splitlines()
-    out: list[str] = []
-    i = 0
-    in_fence: str | None = None  # the fence delimiter we are inside, if any
-
-    while i < len(lines):
-        line = lines[i]
-
-        # Track existing fenced code blocks so we don't re-wrap them.
-        # ``in_fence`` records the opening delimiter; we only close on a
-        # matching delimiter (Greptile P1: previously closed on the
-        # current line's delim, which let a ``~~~`` line close an open
-        # ``\`\`\`` fence and reopen a new one, leaving suspicious headings
-        # after that point unquarantined).
-        fence_match = _FENCE_RE.match(line)
-        if fence_match:
-            delim = fence_match.group(1)
-            if in_fence is None:
-                in_fence = delim
-            elif line.startswith(in_fence):
-                in_fence = None
-            out.append(line)
-            i += 1
-            continue
-        if in_fence is not None:
-            out.append(line)
-            i += 1
-            continue
-
-        # Suspicious heading: capture from this line to (but not including)
-        # the next heading -- regardless of whether the next heading is also
-        # suspicious. The next iteration will re-wrap the next section if
-        # needed.
-        if _is_heading(line) and _is_suspicious(line):
-            section_end = i + 1
-            while section_end < len(lines):
-                nxt = lines[section_end]
-                if _FENCE_RE.match(nxt):
-                    # do not split a quarantined block across an unbalanced
-                    # fence -- consume the entire interior. Both ``\`\`\``
-                    # and ``~~~`` are 3-char delimiters; we slice the same
-                    # prefix length and match the literal opener (Greptile
-                    # P3: dead-conditional cleanup).
-                    section_end += 1
-                    nested = nxt[:3]
-                    while section_end < len(lines) and not lines[
-                        section_end
-                    ].startswith(nested):
-                        section_end += 1
-                    section_end += 1  # consume the closer
-                    continue
-                if _is_heading(nxt):
-                    break
-                section_end += 1
-            out.append(QUARANTINE_FENCE_OPEN)
-            out.extend(lines[i:section_end])
-            out.append(QUARANTINE_FENCE_CLOSE)
-            i = section_end
-            continue
-
-        # Suspicious non-heading line: wrap just that line.
-        if _is_suspicious(line):
-            out.append(QUARANTINE_FENCE_OPEN)
-            out.append(line)
-            out.append(QUARANTINE_FENCE_CLOSE)
-            i += 1
-            continue
-
-        out.append(line)
-        i += 1
-
-    # Preserve trailing newline behaviour of the input. If the input ends
-    # with a newline, splitlines() drops it; re-add for round-trip safety.
-    suffix = "\n" if raw_md.endswith("\n") else ""
-    return "\n".join(out) + suffix
-
-
-def main(argv: list[str] | None = None) -> int:
-    """CLI entry point. Reads input file (or stdin) and emits quarantined md."""
-    argv = list(argv if argv is not None else sys.argv[1:])
-    if argv and argv[0] in {"-h", "--help"}:
-        print(__doc__ or "")
-        return 0
-    text = Path(argv[0]).read_text(encoding="utf-8") if argv else sys.stdin.read()
-    sys.stdout.write(quarantine_body(text))
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())