Merge pull request #257 from Priivacy-ai/codex/branch-contract-and-log-hardening-2x-20260306

2.x: deterministic branch contract + prompt hardening for agent flows

Author: robertDouglass

src/specify_cli/cli/commands/agent/feature.py

@@ -14,6 +14,7 @@
 
 import typer
 
+from specify_cli import __version__ as SPEC_KITTY_VERSION
 from specify_cli.cli import StepTracker
 from specify_cli.cli.helpers import check_version_compatibility, console, show_banner
 from specify_cli.core.git_preflight import (
@@ -75,7 +76,9 @@ def _enforce_git_preflight(repo_root: Path, *, json_output: bool) -> None:
         command_name="spec-kitty merge",
     )
     if json_output:
-        print(json.dumps(payload))
+        enriched = dict(payload)
+        enriched["spec_kitty_version"] = SPEC_KITTY_VERSION
+        print(json.dumps(enriched))
     else:
         console.print(f"[red]Error:[/red] {payload['error']}")
         for cmd in payload.get("remediation", []):
@@ -722,6 +725,7 @@ def merge(
 
     if json_output and not dry_run:
         print(json.dumps({
+            "spec_kitty_version": SPEC_KITTY_VERSION,
             "error": "--json is currently supported with --dry-run only.",
         }))
         raise typer.Exit(1)
@@ -730,6 +734,7 @@ def merge(
         _, current_branch, _ = run_command(["git", "rev-parse", "--abbrev-ref", "HEAD"], capture=True)
         if current_branch == target_branch and not feature:
             print(json.dumps({
+                "spec_kitty_version": SPEC_KITTY_VERSION,
                 "error": f"Already on {target_branch}; pass --feature <slug> for workspace-per-WP planning.",
             }))
             raise typer.Exit(1)
@@ -772,6 +777,7 @@ def merge(
                     steps.append(f"git branch -d {branch}")
 
             print(json.dumps({
+                "spec_kitty_version": SPEC_KITTY_VERSION,
                 "feature_slug": feature_slug,
                 "target_branch": target_branch,
                 "all_wp_branches": [branch for _, _, branch in merge_plan["all_wp_workspaces"]],  # type: ignore[index]
@@ -802,6 +808,7 @@ def merge(
             planned_steps.append(f"git branch -d {feature_slug}")
 
         print(json.dumps({
+            "spec_kitty_version": SPEC_KITTY_VERSION,
             "feature_slug": feature_slug,
             "target_branch": target_branch,
             "all_wp_branches": [],

src/specify_cli/cli/commands/merge.py

@@ -172,7 +172,7 @@ def upgrade(
     # Check if this is a Spec Kitty project
     if not kittify_dir.exists() and not specify_dir.exists():
         if json_output:
-            console.print(json.dumps({"error": "Not a Spec Kitty project"}))
+            print(json.dumps({"error": "Not a Spec Kitty project"}))
         else:
             console.print("[red]Error:[/red] Not a Spec Kitty project.")
             console.print(
@@ -234,7 +234,7 @@ def upgrade(
 
         if json_output:
             warnings = [auto_commit_warning] if auto_commit_warning else []
-            console.print(
+            print(
                 json.dumps(
                     {
                         "status": "up_to_date",
@@ -347,7 +347,7 @@ def upgrade(
             "auto_committed": auto_committed,
             "auto_commit_paths": auto_commit_paths,
         }
-        console.print(json.dumps(output, indent=2))
+        print(json.dumps(output))
         return
 
     # Display results

src/specify_cli/cli/commands/upgrade.py

@@ -71,6 +71,21 @@ def _format_simple_help(group: TyperGroup, ctx, formatter) -> None:
 
 def _should_render_banner_for_invocation(argv: list[str] | None = None) -> bool:
     """Return True only for invocations that should render ASCII art."""
+    # Agent/tool contexts should never receive decorative banner output.
+    # It pollutes deterministic parsing and wastes tokens.
+    if os.environ.get("SPEC_KITTY_NO_BANNER", "").strip().lower() in {"1", "true", "yes", "on"}:
+        return False
+
+    agent_env_markers = (
+        "CLAUDECODE",
+        "CLAUDE_CODE",
+        "CODEX",
+        "OPENCODE",
+        "CURSOR_TRACE_ID",
+    )
+    if any(key in os.environ for key in agent_env_markers):
+        return False
+
     tokens = [token.strip().lower() for token in (argv if argv is not None else sys.argv[1:]) if token.strip()]
     if "--version" in tokens or "-v" in tokens:
         return True

src/specify_cli/cli/helpers.py

@@ -152,6 +152,43 @@ def _list_all_features(repo_root: Path) -> list[str]:
     return sorted(features)
 
 
+def _resolve_numeric_feature_slug(
+    feature_number: str,
+    repo_root: Path,
+    *,
+    mode: Literal["strict", "lenient"],
+) -> Optional[str]:
+    """Resolve a 3-digit feature number (e.g., ``019``) to full slug.
+
+    This is a compatibility affordance for agents that pass only the numeric
+    feature id after parsing logs or UI text.
+    """
+    all_features = _list_all_features(repo_root)
+    matches = [slug for slug in all_features if slug.startswith(f"{feature_number}-")]
+
+    if len(matches) == 1:
+        return matches[0]
+
+    if len(matches) > 1:
+        error_msg = (
+            f"Feature number '{feature_number}' matches multiple features:\n"
+            + "\n".join(f"  - {slug}" for slug in matches)
+            + "\n\nUse the full slug with --feature <###-feature-name>."
+        )
+        if mode == "strict":
+            raise MultipleFeaturesError(matches, error_msg)
+        return None
+
+    error_msg = (
+        f"No feature found for number '{feature_number}'.\n\n"
+        + "Available features:\n"
+        + "\n".join(f"  - {slug}" for slug in all_features[:20])
+    )
+    if mode == "strict":
+        raise NoFeatureFoundError(error_msg)
+    return None
+
+
 def _detect_from_git_branch(repo_root: Path) -> Optional[str]:
     """Detect feature from git branch name.
 
@@ -413,12 +450,26 @@ def detect_feature(
     # Priority 1: Explicit --feature parameter
     if explicit_feature:
         detected_slug = explicit_feature.strip()
-        detection_method = "explicit"
+        if re.fullmatch(r"\d{3}", detected_slug):
+            resolved = _resolve_numeric_feature_slug(detected_slug, repo_root, mode=mode)
+            if resolved is None:
+                return None
+            detected_slug = resolved
+            detection_method = "explicit_number"
+        else:
+            detection_method = "explicit"
 
     # Priority 2: SPECIFY_FEATURE environment variable
     elif "SPECIFY_FEATURE" in env and env["SPECIFY_FEATURE"].strip():
         detected_slug = env["SPECIFY_FEATURE"].strip()
-        detection_method = "env_var"
+        if re.fullmatch(r"\d{3}", detected_slug):
+            resolved = _resolve_numeric_feature_slug(detected_slug, repo_root, mode=mode)
+            if resolved is None:
+                return None
+            detected_slug = resolved
+            detection_method = "env_var_number"
+        else:
+            detection_method = "env_var"
 
     # Priority 3: Git branch name
     elif (branch_slug := _detect_from_git_branch(repo_root)):

src/specify_cli/core/feature_detection.py

@@ -17,13 +17,20 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Location Pre-flight Check
 
-Verify you are in the main repository (not a worktree). Planning happens in main for ALL missions.
+Verify you are in the primary repository checkout (not a worktree). Planning happens on the feature target branch for all missions.
+
+1. Run `spec-kitty agent feature setup-plan --json` and capture:
+   - `target_branch` / `base_branch`
+   - `TARGET_BRANCH` / `BASE_BRANCH`
+   - `feature_dir`
+
+   Treat this JSON as the canonical branch contract.
 
 ```bash
-git branch --show-current  # Should show "main"
+git branch --show-current  # Should match TARGET_BRANCH from setup-plan output
 ```
 
-**Note**: Planning in main is standard for all spec-kitty missions. Implementation happens in per-WP worktrees.
+**Note**: Planning runs on the feature target branch. Implementation happens later in per-WP worktrees.
 
 ---
 
@@ -57,7 +64,7 @@ For documentation missions, planning interrogation is lighter than software-dev:
 
 ## Outline
 
-1. **Setup**: Run `spec-kitty agent feature setup-plan --json` to initialize plan.md
+1. **Setup**: Use the pre-flight `setup-plan --json` output to initialize plan.md and keep `target_branch/base_branch` in context.
 
 2. **Load context**: Read spec.md, meta.json (especially `documentation_state`)
 

src/specify_cli/missions/documentation/command-templates/plan.md

@@ -17,19 +17,26 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 ## Location Pre-flight Check
 
-Verify you are in the main repository (not a worktree). Task generation happens in main for ALL missions.
+Verify you are in the primary repository checkout (not a worktree). Task generation happens on the feature target branch for all missions.
+
+1. Run `spec-kitty agent feature check-prerequisites --json --paths-only --include-tasks` and capture:
+   - `target_branch` / `base_branch`
+   - `TARGET_BRANCH` / `BASE_BRANCH`
+   - `feature_dir`
+
+   Treat this JSON as the canonical branch contract for this command.
 
 ```bash
-git branch --show-current  # Should show "main"
+git branch --show-current  # Should match TARGET_BRANCH from check-prerequisites JSON
 ```
 
-**Note**: Task generation in main is standard for all spec-kitty missions. Implementation happens in per-WP worktrees.
+**Note**: Task generation happens on the feature target branch. Implementation happens later in per-WP worktrees.
 
 ---
 
 ## Outline
 
-1. **Setup**: Run `spec-kitty agent feature check-prerequisites --json --paths-only --include-tasks`
+1. **Setup**: Use the pre-flight `check-prerequisites` JSON and keep `feature_dir` plus `target_branch/base_branch` in context.
 
 2. **Load design documents**:
    - spec.md (documentation goals, selected Divio types)

src/specify_cli/missions/documentation/command-templates/tasks.md

@@ -95,7 +95,7 @@ Use language identifiers in code blocks: ````python`, ````bash`
 1. Scroll to the bottom of this file (Activity Log section below "Valid lanes")
 2. **APPEND the new entry at the END** (do NOT prepend or insert in middle)
 3. Use exact format: `- YYYY-MM-DDTHH:MM:SSZ – agent_id – lane=<lane> – <action>`
-4. Timestamp MUST be current time in UTC (check with `date -u "+%Y-%m-%dT%H:%M:%SZ"`)
+4. Timestamp MUST be current time in UTC (ISO-8601 `YYYY-MM-DDTHH:MM:SSZ`) and should be generated without shell commands (prefer `NOW_UTC_ISO` from `check-prerequisites --json --paths-only`)
 5. Lane MUST match the frontmatter `lane:` field exactly
 6. Agent ID should identify who made the change (claude-sonnet-4-5, codex, etc.)
 

src/specify_cli/missions/documentation/templates/task-prompt-template.md

@@ -16,7 +16,7 @@ cd /path/to/project/root  # Your planning repository
 
 # All planning artifacts are created in the planning repo and committed:
 # - kitty-specs/###-feature/spec.md → Created in planning repo
-# - Committed to target branch (meta.json → target_branch)
+# - Committed to target branch (from create-feature JSON: target_branch/base_branch)
 # - NO worktrees created
 ```
 
@@ -100,7 +100,7 @@ During discovery, you MUST ask:
 
 - Work in: **Planning repository** (not a worktree)
 - Creates: `kitty-specs/###-feature/spec.md`
-- Commits to: target branch (`meta.json` → `target_branch`)
+- Commits to: target branch (from `create-feature --json` → `target_branch`)
 
 ## Outline
 
@@ -123,36 +123,19 @@ When discovery is complete, run:
 spec-kitty agent feature create-feature "<slug>" --json
 ```
 
-Parse the JSON output for `feature` and `feature_dir`.
+Parse the JSON output for `feature`, `feature_dir`, `spec_file`, and `meta_file`.
 
-### 3. Create meta.json with deliverables_path
+### 3. Update existing meta.json with deliverables_path
 
-**CRITICAL**: Include `deliverables_path` in meta.json:
+`create-feature` already created `meta.json`. Read it first, then update only needed fields:
 
-```json
-{
-  "feature_number": "<number>",
-  "slug": "<full-slug>",
-  "friendly_name": "<Research Title>",
-  "mission": "research",
-  "deliverables_path": "<confirmed-path>",
-  "source_description": "$ARGUMENTS",
-  "created_at": "<ISO timestamp>"
-}
-```
+- `mission`: set to `"research"`
+- `deliverables_path`: set to the confirmed path
+- `friendly_name`: confirmed research title
+- optional `source_description`
 
-Example with default path:
-```json
-{
-  "feature_number": "018",
-  "slug": "018-market-research",
-  "friendly_name": "Market Research Analysis",
-  "mission": "research",
-  "deliverables_path": "docs/research/018-market-research/",
-  "source_description": "Research the competitive landscape",
-  "created_at": "2025-01-25T10:00:00Z"
-}
-```
+Preserve existing identity and timing fields (`feature_number`, `slug`, `created_at`, `target_branch`).
+Do **not** recreate the file or regenerate timestamps via shell commands.
 
 ### 4. Load Research Spec Template
 
@@ -168,7 +151,7 @@ Fill in:
 
 ### 6. Write Specification
 
-Write to `<feature_dir>/spec.md`
+Update the existing `<feature_dir>/spec.md`
 
 ### 7. Validation
 

src/specify_cli/missions/research/command-templates/specify.md

@@ -19,8 +19,15 @@ You **MUST** consider the user input before proceeding (if not empty).
 
 Verify you are in the planning repository (not a worktree). Task generation happens on the target branch for ALL missions.
 
+1. Run `spec-kitty agent feature check-prerequisites --json --paths-only --include-tasks` from the repository root and capture:
+   - `target_branch` / `base_branch`
+   - `TARGET_BRANCH` / `BASE_BRANCH`
+   - `feature_dir`
+
+   Treat this JSON as canonical branch context for this command. Do not infer from `meta.json`.
+
 ```bash
-git branch --show-current  # Should show the target branch (meta.json → target_branch)
+git branch --show-current  # Should match TARGET_BRANCH from check-prerequisites JSON
 ```
 
 **Note**: Task generation in the target branch is standard for all spec-kitty missions. Implementation happens in per-WP worktrees.
@@ -29,9 +36,12 @@ git branch --show-current  # Should show the target branch (meta.json → target
 
 ## Outline
 
-1. **Setup**: Run `spec-kitty agent feature check-prerequisites --json --paths-only --include-tasks`
+1. **Setup**: Use the `check-prerequisites` JSON from Location Pre-flight and capture:
+   - `feature_dir`
+   - `target_branch` / `base_branch`
 
-   **CRITICAL**: The command returns JSON with `FEATURE_DIR` as an ABSOLUTE path (e.g., `/Users/robert/Code/project/kitty-specs/015-research-topic`).
+   **CRITICAL**: The command returns JSON with `feature_dir` as an ABSOLUTE path (e.g., `/Users/robert/Code/project/kitty-specs/015-research-topic`).
+   It also returns `runtime_vars.now_utc_iso` (`NOW_UTC_ISO`) for deterministic timestamp fields.
 
    **YOU MUST USE THIS PATH** for ALL subsequent file operations.
 
@@ -108,7 +118,7 @@ git branch --show-current  # Should show the target branch (meta.json → target
    - **P3 (polish)**: Quality validation, external review
 
 5. **Write `tasks.md`**:
-   - Location: `FEATURE_DIR/tasks.md`
+   - Location: `feature_dir/tasks.md`
    - Use `templates/tasks-template.md` from research mission
    - Include work packages with subtasks
    - Mark parallel opportunities (`[P]`)
@@ -117,12 +127,14 @@ git branch --show-current  # Should show the target branch (meta.json → target
 
 6. **Generate prompt files**:
 
-   **CRITICAL PATH RULE**: All work package files MUST be created in a FLAT `FEATURE_DIR/tasks/` directory, NOT in subdirectories!
+   **CRITICAL PATH RULE**: All work package files MUST be created in a FLAT `feature_dir/tasks/` directory, NOT in subdirectories!
 
-   - Create flat `FEATURE_DIR/tasks/` directory (no subdirectories!)
+   - Use `artifact_dirs.tasks_dir` when available.
+   - Do **not** shell out with `mkdir -p`; `create-feature` already creates `tasks/` in normal flow.
+   - If `tasks/` is missing unexpectedly, report the mismatch instead of improvising shell directory setup.
    - For each work package:
      - Derive a kebab-case slug from the title; filename: `WPxx-slug.md`
-     - Full path: `FEATURE_DIR/tasks/WP01-literature-search.md`
+     - Full path: `feature_dir/tasks/WP01-literature-search.md`
      - Use `templates/task-prompt-template.md` to capture:
        - **YAML frontmatter with `lane: "planned"`** (CRITICAL - this is how review finds WPs!)
        - `work_package_id`, `subtasks` array, `dependencies`, history entry