@techierathore/techieflow 1.0.1 → 1.0.3

package/.tfcore/hooks/codex-adapter.py

@@ -1,248 +0,0 @@
-#!/usr/bin/env python3
-"""Translate Codex hooks to TechieFlow's existing guard and telemetry contracts.
-
-Modes (see .codex/hooks.json):
-  pre-tool       Bash  -> block-git.sh + guard-artifacts.sh
-                 Edit/Write/apply_patch -> guard-status.sh + guard-verify.sh
-  stop           guard-status-html.sh (PROJECT-STATUS.html must not be stale)
-  session-start  session pointer + sweep-artifacts.sh (expired run material)
-  session-start  write the .tfcore/.session/codex.json pointer
-  session-end    pointer + session telemetry
-"""
-
-from __future__ import annotations
-
-import json
-import os
-import pathlib
-import re
-import subprocess
-import sys
-from datetime import datetime, timezone
-
-
-def read_event() -> dict:
-    try:
-        value = json.load(sys.stdin)
-        return value if isinstance(value, dict) else {}
-    except Exception:
-        return {}
-
-
-def project_root(event: dict) -> pathlib.Path:
-    start = pathlib.Path(str(event.get("cwd") or os.getcwd())).resolve()
-    for candidate in (start, *start.parents):
-        if (candidate / ".tfcore").is_dir():
-            return candidate
-    return start
-
-
-def environment(root: pathlib.Path, event: dict) -> dict[str, str]:
-    env = os.environ.copy()
-    env.update(
-        TF_HARNESS="codex",
-        TF_PROJECT_DIR=str(root),
-        CLAUDE_PROJECT_DIR=str(root),
-        TF_SESSION_ID=str(event.get("session_id") or ""),
-    )
-    if (root / ".tfcore" / ".session" / "yolo.json").exists():
-        env["TF_YOLO"] = "1"
-    return env
-
-
-def deny(reason: str) -> None:
-    print(json.dumps({
-        "hookSpecificOutput": {
-            "hookEventName": "PreToolUse",
-            "permissionDecision": "deny",
-            "permissionDecisionReason": reason,
-        }
-    }))
-
-
-def run_guard(root: pathlib.Path, event: dict, script: str, payload: dict) -> str | None:
-    path = root / ".tfcore" / "hooks" / script
-    if not path.exists():
-        return None
-    try:
-        env = environment(root, event)
-        if script == "block-git.sh":
-            # Codex also has an all-git exec-policy rule. Keep the hook's
-            # compound-command fallback equally strict in YOLO mode.
-            env["TF_STRICT_GIT"] = "1"
-        result = subprocess.run(
-            ["bash", str(path)], input=json.dumps(payload), text=True,
-            capture_output=True, timeout=10, env=env, check=False,
-        )
-    except Exception as exc:
-        # Policy checks fail closed. Telemetry is handled separately and fails open.
-        return f"TechieFlow could not execute {script}: {exc}"
-    if result.returncode == 2:
-        return result.stderr.strip() or f"Blocked by TechieFlow guard {script}"
-    if result.returncode not in (0,):
-        return f"TechieFlow guard {script} failed unexpectedly (exit {result.returncode})."
-    return None
-
-
-def pre_tool(event: dict) -> None:
-    root = project_root(event)
-    tool = str(event.get("tool_name") or "")
-    raw = event.get("tool_input")
-    args = raw if isinstance(raw, dict) else {}
-    scripts: list[str] = []
-    if tool == "Bash":
-        payload = {"tool_name": "Bash", "tool_input": {"command": str(args.get("command") or "")}}
-        scripts = ["block-git.sh", "guard-artifacts.sh"]
-    elif tool == "apply_patch":
-        patch = str(args.get("command") or args.get("patch") or "")
-        # Run the existing guards once per file using actual paths and separated
-        # added/removed lines. This avoids treating context or removed Verified
-        # cells as newly introduced content.
-        headers = list(re.finditer(r"(?m)^\*\*\* (Update|Add|Delete) File: (.+)$", patch))
-        for index, header in enumerate(headers):
-            end = headers[index + 1].start() if index + 1 < len(headers) else len(patch)
-            section = patch[header.end():end]
-            file_path = header.group(2).strip()
-            base_name = pathlib.PurePosixPath(file_path.replace("\\", "/")).name.lower()
-            if header.group(1) == "Delete" and (
-                base_name == "project-status.md" or base_name.endswith("-checklist.md")
-            ):
-                deny(
-                    "TechieFlow protected documents cannot be deleted: "
-                    f"{file_path}. Update their canonical fixed shape instead."
-                )
-                return
-            added = []
-            removed = []
-            for line in section.splitlines():
-                if line.startswith("+") and not line.startswith("+++"):
-                    added.append(line[1:])
-                elif line.startswith("-") and not line.startswith("---"):
-                    removed.append(line[1:])
-            payload = {
-                "hook_event_name": "PreToolUse", "cwd": str(root),
-                "session_id": event.get("session_id"), "tool_name": "Edit",
-                "tool_input": {"file_path": file_path,
-                               "old_string": "\n".join(removed),
-                               "new_string": "\n".join(added)},
-            }
-            for script in ("guard-status.sh", "guard-verify.sh"):
-                reason = run_guard(root, event, script, payload)
-                if reason:
-                    deny(reason)
-                    return
-        return
-    elif tool in ("Edit", "Write"):
-        payload = {"tool_name": tool, "tool_input": args}
-        scripts = ["guard-status.sh", "guard-verify.sh"]
-    else:
-        return
-    payload.update(hook_event_name="PreToolUse", cwd=str(root), session_id=event.get("session_id"))
-    for script in scripts:
-        reason = run_guard(root, event, script, payload)
-        if reason:
-            deny(reason)
-            return
-
-
-def stop(event: dict) -> None:
-    """Stop hook: refuse to end the turn while PROJECT-STATUS.html is stale.
-
-    Same contract as the Claude Code Stop hook (_status-update-gate.md §8):
-    guard-status-html.sh exits 2 when the .html is older than the .md or
-    missing; `stop_hook_active` is passed through so a turn that genuinely
-    cannot render still terminates instead of looping.
-    """
-    root = project_root(event)
-    payload = {
-        "hook_event_name": "Stop", "cwd": str(root),
-        "session_id": event.get("session_id"),
-        "stop_hook_active": bool(event.get("stop_hook_active")),
-    }
-    reason = run_guard(root, event, "guard-status-html.sh", payload)
-    if reason:
-        print(json.dumps({"decision": "block", "reason": reason}))
-
-
-def write_pointer(root: pathlib.Path, event: dict) -> None:
-    session_id = str(event.get("session_id") or "")
-    if not session_id:
-        return
-    target = root / ".tfcore" / ".session" / "codex.json"
-    try:
-        target.parent.mkdir(parents=True, exist_ok=True)
-        target.write_text(json.dumps({
-            "session_id": session_id,
-            "transcript_path": event.get("transcript_path"),
-            "model": event.get("model"),
-            "ts": datetime.now(timezone.utc).isoformat(),
-        }) + "\n", encoding="utf-8")
-    except Exception:
-        pass
-
-
-def sweep_artifacts(root: pathlib.Path, event: dict) -> None:
-    """SessionStart analogue of the Claude Code sweep-artifacts.sh hook: delete
-    run material under tests/.artifacts/ and .verify/ older than the retention
-    window and any banned repo-root legacy dir. No veto — never raises."""
-    script = root / ".tfcore" / "hooks" / "sweep-artifacts.sh"
-    if not script.exists():
-        return
-    try:
-        res = subprocess.run(["bash", str(script)], input=json.dumps(event), text=True,
-                             capture_output=True, timeout=30, env=environment(root, event), check=False)
-        summary = (res.stdout or "").strip()
-        if summary:
-            print(summary)  # SessionStart stdout is surfaced into the session
-    except Exception:
-        pass
-
-
-def session_end(root: pathlib.Path, event: dict) -> None:
-    # Transcript format is explicitly not a stable Codex hook interface. Record
-    # honest session metadata; codex exec --json telemetry is enriched separately.
-    emit = root / ".tfcore" / "utils" / "tf-emit.sh"
-    if not emit.exists() or not event.get("session_id"):
-        return
-    record = {
-        "kind": "session",
-        "session_id": event.get("session_id"),
-        "model": event.get("model"),
-        "duration_s": None,
-        "input_tokens": None,
-        "output_tokens": None,
-        "cache_read_tokens": None,
-        "cache_creation_tokens": None,
-        "cost_usd": None,
-        "children_sessions": None,
-        "harness": "codex",
-    }
-    try:
-        subprocess.run(["bash", str(emit), "sessions"], input=json.dumps(record), text=True,
-                       capture_output=True, timeout=2, env=environment(root, event), check=False)
-    except Exception:
-        pass
-
-
-def main() -> int:
-    event = read_event()
-    root = project_root(event)
-    mode = sys.argv[1] if len(sys.argv) > 1 else ""
-    if mode == "pre-tool":
-        pre_tool(event)
-    elif mode == "stop":
-        stop(event)
-    elif mode == "session-start":
-        write_pointer(root, event)
-        # .codex/hooks.json runs session-start for UserPromptSubmit too; sweep
-        # only on the real session start so every prompt does not walk the tree.
-        if str(event.get("hook_event_name") or "").lower() != "userpromptsubmit":
-            sweep_artifacts(root, event)
-    elif mode == "session-end":
-        write_pointer(root, event)
-        session_end(root, event)
-    return 0
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())

package/.tfcore/tasks/advanced-elicitation.md

@@ -1,117 +0,0 @@
-# Advanced Elicitation Task
-
-## Purpose
-
-- Provide optional reflective and brainstorming actions to enhance content quality
-- Enable deeper exploration of ideas through structured elicitation techniques
-- Support iterative refinement through multiple analytical perspectives
-- Usable during template-driven document creation or any chat conversation
-
-## Usage Scenarios
-
-### Scenario 1: Template Document Creation
-
-After outputting a section during document creation:
-
-1. **Section Review**: Ask user to review the drafted section
-2. **Offer Elicitation**: Present 9 carefully selected elicitation methods
-3. **Simple Selection**: User types a number (0-8) to engage method, or 9 to proceed
-4. **Execute & Loop**: Apply selected method, then re-offer choices until user proceeds
-
-### Scenario 2: General Chat Elicitation
-
-User can request advanced elicitation on any agent output:
-
-- User says "do advanced elicitation" or similar
-- Agent selects 9 relevant methods for the context
-- Same simple 0-9 selection process
-
-## Task Instructions
-
-### 1. Intelligent Method Selection
-
-**Context Analysis**: Before presenting options, analyze:
-
-- **Content Type**: Technical specs, user stories, architecture, requirements, etc.
-- **Complexity Level**: Simple, moderate, or complex content
-- **Stakeholder Needs**: Who will use this information
-- **Risk Level**: High-impact decisions vs routine items
-- **Creative Potential**: Opportunities for innovation or alternatives
-
-**Method Selection Strategy**:
-
-1. **Always Include Core Methods** (choose 3-4):
-   - Expand or Contract for Audience
-   - Critique and Refine
-   - Identify Potential Risks
-   - Assess Alignment with Goals
-
-2. **Context-Specific Methods** (choose 4-5):
-   - **Technical Content**: Tree of Thoughts, ReWOO, Meta-Prompting
-   - **User-Facing Content**: Agile Team Perspective, Stakeholder Roundtable
-   - **Creative Content**: Innovation Tournament, Escape Room Challenge
-   - **Strategic Content**: Red Team vs Blue Team, Hindsight Reflection
-
-3. **Always Include**: "Proceed / No Further Actions" as option 9
-
-### 2. Section Context and Review
-
-When invoked after outputting a section:
-
-1. **Provide Context Summary**: Give a brief 1-2 sentence summary of what the user should look for in the section just presented
-
-2. **Explain Visual Elements**: If the section contains diagrams, explain them briefly before offering elicitation options
-
-3. **Clarify Scope Options**: If the section contains multiple distinct items, inform the user they can apply elicitation actions to:
-   - The entire section as a whole
-   - Individual items within the section (specify which item when selecting an action)
-
-### 3. Present Elicitation Options
-
-**Review Request Process:**
-
-- Ask the user to review the drafted section
-- In the SAME message, inform them they can suggest direct changes OR select an elicitation method
-- Present 9 intelligently selected methods (0-8) plus "Proceed" (9)
-- Keep descriptions short - just the method name
-- Await simple numeric selection
-
-**Action List Presentation Format:**
-
-```text
-**Advanced Elicitation Options**
-Choose a number (0-8) or 9 to proceed:
-
-0. [Method Name]
-1. [Method Name]
-2. [Method Name]
-3. [Method Name]
-4. [Method Name]
-5. [Method Name]
-6. [Method Name]
-7. [Method Name]
-8. [Method Name]
-9. Proceed / No Further Actions
-```
-
-**Response Handling:**
-
-- **Numbers 0-8**: Execute the selected method, then re-offer the choice
-- **Number 9**: Proceed to next section or continue conversation
-- **Direct Feedback**: Apply user's suggested changes and continue
-
-### 4. Method Execution Framework
-
-**Execution Process:**
-
-1. **Retrieve Method**: Access the specific elicitation method from the elicitation-methods data file
-2. **Apply Context**: Execute the method from your current role's perspective
-3. **Provide Results**: Deliver insights, critiques, or alternatives relevant to the content
-4. **Re-offer Choice**: Present the same 9 options again until user selects 9 or gives direct feedback
-
-**Execution Guidelines:**
-
-- **Be Concise**: Focus on actionable insights, not lengthy explanations
-- **Stay Relevant**: Tie all elicitation back to the specific content being analyzed
-- **Identify Personas**: For multi-persona methods, clearly identify which viewpoint is speaking
-- **Maintain Flow**: Keep the process moving efficiently

package/.tfcore/tasks/author-brd.md

@@ -1,79 +0,0 @@
-# author-brd
-
-Author or extend a Business Requirements Document (BRD) with stable BRD-N requirement IDs, using interactive elicitation. The analyst NEVER assumes a requirement — each candidate is confirmed by the user before it lands in the BRD.
-
-> **When to use:** this is the INTERACTIVE alternative for extending an existing BRD requirement-by-requirement. For creating a project's BRD, the default path is `*day1-brownfield` / `*day1-greenfield` (bulk draft, no per-item confirmation).
-
-## Purpose
-
-Produce a BRD where every business/functional requirement has a unique, stable, append-only ID (`BRD-1`, `BRD-2`, …) that downstream agents (UI agent, orchestrator, verifier) can declare and verify against. Eliminate the "implicit requirement" problem by forcing per-item user confirmation.
-
-## elicit
-
-elicit=true — this task REQUIRES user interaction. Never skip elicitation for efficiency.
-
-## Inputs
-
-- `{AppName}` argument (required for the canonical filename; ask once if missing).
-- `{topic}` argument (optional) — the product/feature area. If absent, ask once: "What's the topic / product area for this BRD?"
-- Existing BRD path. Resolve in this order: `core-config.yaml → customTechnicalDocuments`, then `docs/{AppName}-BRD.md` (legacy fallbacks: `docs/brd.md`, `docs/BRD.md`). If found, OPEN it and continue from the highest existing BRD-N. If not found, create `docs/{AppName}-BRD.md` from `.tfcore/templates/v4custom/app-brd-tmpl.md` (feature catalog + §10 BRD-N ledger shape — NOT ad-hoc "Phase N" sections).
-
-## SEQUENTIAL Execution
-
-### 1. Read or scaffold the BRD
-
-- If the resolved BRD exists: read it, parse all existing `BRD-{N}` IDs, and record the highest N. New requirements continue from N+1.
-- If absent: scaffold `docs/{AppName}-BRD.md` from `.tfcore/templates/v4custom/app-brd-tmpl.md` (leave unconfirmed sections empty; confirmed requirements land in the §10 ledger).
-- Ask the user which areas they want to scope today.
-
-### 2. Drive elicitation per area, one at a time
-
-For each area the user wants to cover (UI, data, workflow, NFRs, etc.):
-
-1. Generate a numbered list of CANDIDATE requirements for that area — 3 to 7 items, written as one-line "user can X" / "system shall Y" statements. Do NOT assign BRD-N IDs yet.
-2. Present the list and ask the user to (a) accept, (b) reject, (c) refine, or (d) add their own — one item at a time. Use this exact prompt format:
-   ```
-   Candidate requirements for {area}:
-   1. {candidate}
-   2. {candidate}
-   ...
-   For each, reply: keep / drop / refine: <new text>. Or add a new one with: add: <text>.
-   ```
-3. After the user processes each item, assign the next BRD-N to every KEPT or REFINED item, in the order they were confirmed. Show the assignments back:
-   ```
-   Assigned:
-   - BRD-{N}: {final text}
-   - BRD-{N+1}: {final text}
-   ```
-4. Append the assigned requirements to the §10 Functional-requirements ledger of the resolved BRD file (and flesh out / create the owning feature-catalog entry).
-
-Repeat for each area until the user says they're done with this BRD pass.
-
-### 3. NFRs and acceptance criteria (optional pass)
-
-If the user wants NFRs (performance, accessibility, browser support, etc.) or acceptance criteria for any BRD-N, run the same elicitation pattern. NFRs get their own BRD-N IDs (do NOT use a separate `NFR-N` series — keep one ID space so the verifier can grade everything uniformly).
-
-### 4. Final output
-
-Append/refresh the footer block of the BRD:
-```
----
-Last updated: {YYYY-MM-DD}
-Highest BRD ID: BRD-{N}
-```
-
-Print a compact summary to the user:
-```
-BRD updated → docs/{AppName}-BRD.md
-Added: BRD-{a}..BRD-{b} ({count} requirements)
-Phases touched: {list}
-```
-
-HALT.
-
-## Hard rules
-
-- elicit=true — never batch-confirm; one item at a time.
-- BRD-N IDs are append-only — never renumber an existing ID even if the user removes a requirement later (mark it `~~BRD-N~~ (removed)` instead).
-- Requirements are written as observable outcomes, not implementation hints. The verifier needs to be able to test them.
-- The analyst writes the BRD; the analyst does NOT implement anything.