issues.json

[
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/345",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/345/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/345/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/345/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/345",
    "id": 4905772837,
    "node_id": "I_kwDOR2RC5c8AAAABJGgnJQ",
    "number": 345,
    "title": "Improve todo list rendering in agent output for readability",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 0,
    "created_at": "2026-07-16T20:32:13Z",
    "updated_at": "2026-07-16T20:32:13Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## UX: Todo list output formatting improvement\\n\\nThe current todo list rendering in agent output is hard to read. It uses plain text with inline markdown checkboxes that get compressed and are difficult to scan.\\n\\n### Current Format (Problem)\\n\\n```\\nUpdated the to-do list\\nFix unconditional response.json() calls in App.tsx (root cause of JSON parse errors)\\\\n- [x] Create comprehensive Playwright E2E test suite for data correctness, UI elements, styling\\\\n- [-] Fix studio-data-and-ui.spec.ts syntax errors and service ID issues\\\\n - [x] Add missing `});` to close `navigateAndWait` function\\\\n - [x] Add missing `});` to close first test\\\\n - [x] Change `service-studio` → `service-api` (studio at index 0 is sliced out)\\\\n - [x] Fix `navigateAndWait` to pass hash URLs directly (was stripping `#`)\\\\n - [ ] Rebuild and re-run tests\\\\n - [ ] Fix remaining failures\\\\n- [ ] Verify against Specsmith governance\\n```\\n\\nIssues:\\n- Sub-items use inconsistent indentation (space vs tab)\\n- Long parent items run into child items\\n- No visual separation between top-level and nested items\\n- Status indicators (`[x]`, `[-]`, `[ ]`) are not visually distinct\\n- Paused state info is appended without clear formatting\\n\\n### Proposed Format (Solution)\\n\\n```\\n## Updated the to-do list\\n\\n### Fix unconditional response.json() calls in App.tsx\\n- [x] Create comprehensive Playwright E2E test suite\\n- [x] Add missing `});` to close `navigateAndWait` function\\n- [x] Add missing `});` to close first test\\n- [x] Change `service-studio` → `service-api`\\n- [x] Fix `navigateAndWait` to pass hash URLs directly\\n- [ ] Rebuild and re-run tests\\n- [ ] Fix remaining failures\\n\\n### Verify against Specsmith governance\\n- [ ] Run governance checkpoint\\n```\\n\\n### Acceptance Criteria\\n\\n- [ ] Each top-level todo item gets its own `###` heading or clear separator\\n- [ ] Sub-items use consistent 2-space indentation under parent\\n- [ ] Status badges or emoji indicators for visual distinction:\\n  - `[x]` → ✅ completed\\n  - `[-]` → 🔄 in progress\\n  - `[ ]` → ⏳ pending\\n- [ ] Paused/resumed state shown in a collapsible or clearly separated block\\n- [ ] Long item titles are truncated with ellipsis when exceeding 60 chars\\n- [ ] Format is consistent across all agent modes (code, architect, debug, etc.)\\n\\n### Implementation Notes\\n\\n- Modify the `update_todo_list` tool output formatting in agent response generation\\n- Consider a dedicated rendering function for todo lists in agent output\\n- Ensure markdown compatibility across all output surfaces (terminal, IDE, web UI)\\n- Test with deeply nested todo lists (3+ levels)\\n\\n### Labels\\n\\n`ux`, `enhancement`, `agent-output`, `readability`",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/345/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/345/timeline",
    "performed_via_github_app": null,
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/344",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/344/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/344/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/344/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/344",
    "id": 4905311566,
    "node_id": "I_kwDOR2RC5c8AAAABJGEdTg",
    "number": 344,
    "title": "Model generates malformed diff format: :start_line: marker in REPLACE section causes edit failures",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 0,
    "created_at": "2026-07-16T19:26:11Z",
    "updated_at": "2026-07-16T19:26:11Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Bug: Malformed diff format from model tool use\\n\\nZoo Code (and potentially other AI agents) is generating diffs with `:start_line:` markers in the **REPLACE** section instead of the **SEARCH** section, causing `apply_diff` failures.\\n\\n### Error Details\\n\\n```\\nERROR: Invalid line marker ':start_line:' found in REPLACE section at line 4\\n\\nLine markers (:start_line: and :end_line:) are only allowed in SEARCH sections.\\n\\nCORRECT FORMAT:\\n<<<<<<< SEARCH\\n:start_line:5\\ncontent to find\\n=======\\nreplacement content\\n>>>>>>> REPLACE\\n\\nINCORRECT FORMAT:\\n<<<<<<< SEARCH\\ncontent to find\\n=======\\n:start_line:5    <-- Invalid location\\nreplacement content\\n>>>>>>> REPLACE\\n```\\n\\n### Affected File\\n\\n- `c:\\\\Users\\\\trist\\\\Development\\\\Layer1Labs\\\\chronofabric\\\\chronofabric-ip\\\\scripts\\\\bootstrap.py`\\n- Truncation at line 538 inside `platform_map` dict\\n\\n### Environment\\n\\n- Date/time: 2026-07-16T19:22:19.431Z\\n- Extension version: 3.68.0\\n- Provider: litellm (proxy)\\n- Model: ChronoCortex-LLM\\n\\n### Root Cause Analysis Needed\\n\\n1. **Model training gap**: The model does not correctly associate `:start_line:` with the SEARCH block\\n2. **Tool-use instruction clarity**: The diff format spec may need reinforcement in system prompts\\n3. **Truncation handling**: When files are truncated, the model may lose context about where markers belong\\n\\n### Reproduction Steps\\n\\n1. Open a file with a large dict (e.g., `platform_map` with 500+ lines)\\n2. Ask the model to replace a truncated/incomplete section\\n3. Model generates diff with `:start_line:` in REPLACE block\\n4. `apply_diff` tool rejects the edit\\n\\n### Acceptance Criteria\\n\\n- [ ] System prompt or tool instructions explicitly reinforce `:start_line:` placement in SEARCH blocks only\\n- [ ] Model generates valid diff format for truncated file edits\\n- [ ] Fallback strategy documented (e.g., `write_to_file` when diffs fail repeatedly)\\n- [ ] Error recovery flow: on `apply_diff` failure, retry with corrected format or switch to full file write\\n\\n### Mitigation for Users (Workaround)\\n\\nUntil fixed, users can:\\n- Break large edits into smaller, targeted changes\\n- Use `write_to_file` for complete file rewrites instead of `apply_diff` for truncated sections\\n- Manually specify the exact content to search for without line markers\\n\\n### Labels\\n\\n`bug`, `tool-use`, `model-training`, `diff-format`, `zoo-code`",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/344/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/344/timeline",
    "performed_via_github_app": null,
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/343",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/343/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/343/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/343/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/343",
    "id": 4905299491,
    "node_id": "I_kwDOR2RC5c8AAAABJGDuIw",
    "number": 343,
    "title": "Define optimal invocation strategy: MCP vs /slash commands vs skills vs direct CLI",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 0,
    "created_at": "2026-07-16T19:24:33Z",
    "updated_at": "2026-07-16T19:24:33Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Epic: Invocation Strategy Optimization\\n\\nSpecsmith supports multiple invocation mechanisms. This ticket defines when each should be used for optimal UX, reliability, and cross-environment compatibility.\\n\\n### Invocation Mechanisms\\n\\n1. **MCP (Model Context Protocol)** — `governance_preflight`, `governance_audit`, `governance_checkpoint`, etc.\\n   - Best for: AI agent-to-agent communication, structured governance decisions, programmatic access\\n   - Environments: Cursor, VS Code extensions, any MCP-compatible client\\n   - Pros: Structured JSON I/O, governance-enforced, traceable\\n   - Cons: Requires MCP server running, limited to MCP-defined tools\\n\\n2. **Slash Commands** — `/specsmith save`, `/specsmith audit`, `/specsmith status`, etc. (REPL)\\n   - Best for: Interactive sessions, quick governance operations, human operators\\n   - Environments: Nexus REPL, any terminal with REPL mode\\n   - Pros: Simple syntax, built into specsmith CLI, no extra setup\\n   - Cons: REPL-bound, not scriptable in non-interactive contexts\\n\\n3. **Skills** — Loaded via `skill` tool (e.g., `execution`, `git`, `release`, `testing-*`)\\n   - Best for: Complex, multi-step workflows with specific domain procedures\\n   - Environments: AI agents with skill-loading capability\\n   - Pros: Rich procedural instructions, domain-specific guidance\\n   - Cons: Skill must be loaded first, adds context overhead\\n\\n4. **Direct CLI** — `specsmith preflight`, `specsmith audit`, `specsmith sync`, `specsmith checkpoint`, etc.\\n   - Best for: Scripting, CI/CD pipelines, automation, shell scripts\\n   - Environments: Any shell (bash, pwsh, cmd), CI runners\\n   - Pros: Fully scriptable, no server required, works in headless environments\\n   - Cons: Less structured output, no built-in governance enforcement without flags\\n\\n### Decision Matrix\\n\\n| Scenario | Preferred | Fallback |\\n|---|---|---|\\n| AI agent in IDE (Cursor/VS Code) | MCP tools | Slash commands |\\n| Interactive terminal session | Slash commands | Direct CLI |\\n| Complex domain workflow | Skill | Direct CLI |\\n| CI/CD pipeline | Direct CLI | MCP (if server available) |\\n| Headless/server environments | Direct CLI | — |\\n| Cross-platform automation | Direct CLI | — |\\n| Governance-enforced decisions | MCP tools | Direct CLI with `--json` |\\n\\n### Integration Considerations\\n\\n- **Zoo Code**: Prefers MCP for governance decisions, slash commands for quick ops\\n- **Local LLM agents**: Direct CLI (no MCP server needed)\\n- **Remote CI runners**: Direct CLI with `SPECSMITH_ALLOW_NON_PIPX=1` as needed\\n- **Multi-agent coordination**: MCP for structured handoffs\\n\\n### Acceptance Criteria\\n\\n- [ ] Decision matrix documented in AGENTS.md or docs/\\n- [ ] Clear guidance on when each mechanism is appropriate\\n- [ ] Fallback strategies documented\\n- [ ] Environment compatibility matrix (Windows/Linux/macOS, IDE/headless)\\n- [ ] Zoo Code integration notes included\\n\\n### Labels\\n\\n`epic`, `documentation`, `ux`, `cross-platform`",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/343/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/343/timeline",
    "performed_via_github_app": null,
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/342",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/342/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/342/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/342/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/342",
    "id": 4905261241,
    "node_id": "I_kwDOR2RC5c8AAAABJGBYuQ",
    "number": 342,
    "title": "Windows pipx CLI startup can hang in Click/gettext before command dispatch",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 0,
    "created_at": "2026-07-16T19:19:26Z",
    "updated_at": "2026-07-16T19:20:07Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nPrevent `specsmith` from hanging or taking unbounded time during CLI import and command registration on Windows before the requested subcommand is dispatched.\n\nThis was observed with a pipx-installed Specsmith using Python 3.12 on Windows PowerShell. It is not currently covered by another open issue. It is related to the cross-platform audit in #330, but is a distinct public-CLI startup defect. It follows the test-evidence contract in #337.\n\n## Observed reproduction\n\nWorking directory:\n\n```text\nC:\\Users\\trist\\Development\\Creative Racing\\crscale\n```\n\nCommand:\n\n```powershell\nspecsmith load\n```\n\nObserved stack at manual interruption:\n\n```text\nFile \"...\\specsmith\\cli.py\", line 13894, in <module>\n  from specsmith.commands.reporting import register_reporting_commands\nFile \"...\\specsmith\\commands\\reporting.py\", line 494, in <module>\n  @click.option(\"--project-dir\", type=click.Path(exists=True), default=\".\")\nFile \"...\\click\\types.py\", line 1073, in __init__\n  self.name = _(\"path\")\nFile \"...\\gettext.py\", line 617, in gettext\n  return dgettext(_current_domain, message)\nFile \"...\\gettext.py\", line 523, in translation\n  mofiles = find(domain, localedir, languages, all=True)\nFile \"...\\gettext.py\", line 507, in find\n  if os.path.exists(mofile):\nKeyboardInterrupt\n```\n\nEnvironment visible in the traceback:\n\n- Windows PowerShell\n- pipx executable: `C:\\Users\\trist\\.local\\bin\\specsmith.exe`\n- pipx environment: `C:\\Users\\trist\\AppData\\Local\\pipx\\pipx\\venvs\\specsmith`\n- Python 3.12 runtime under `AppData\\Local\\Python\\pythoncore-3.12-64`\n- repository path contains spaces\n\nThe final `KeyboardInterrupt` means the user manually stopped a startup hang; it is not the underlying error.\n\n## Current-state evidence\n\nOn current `main`:\n\n- `specsmith.cli` eagerly imports `specsmith.commands.reporting` during module initialization;\n- `reporting.py` constructs Click decorators such as `click.Path(exists=True)` at import time;\n- Click initializes translated type names through Python `gettext` while those decorators are created;\n- command registration occurs before Click can dispatch `load`;\n- therefore a slow or pathological locale lookup in an unrelated command module can block every CLI command.\n\nThe import is wrapped in `except Exception`, but `KeyboardInterrupt` derives from `BaseException`, not `Exception`, and the import has already blocked before normal command handling can proceed. Broadly swallowing import exceptions is also not an acceptable fix because it can silently remove commands.\n\n## Required investigation\n\nReproduce and profile startup using the same installation topology:\n\n1. Windows hosted runner or Windows VM;\n2. Python 3.12 and at least one other supported Python version;\n3. pipx installation, not only an editable virtual environment;\n4. PowerShell invocation;\n5. working directory containing spaces;\n6. representative `LANG`, `LC_ALL`, `LANGUAGE`, and Windows locale combinations;\n7. cold and warm filesystem/cache states.\n\nCapture timing and stack evidence for:\n\n- Python import time;\n- Click command-tree construction;\n- gettext domain/language resolution;\n- filesystem probes generated by gettext;\n- endpoint-security or unavailable-drive interactions where reproducible;\n- difference between importing `specsmith.cli`, importing `reporting.py`, and constructing one `click.Path` instance.\n\nDo not assume `click.Path` itself is defective until isolated. The stack shows where the thread was interrupted, not necessarily the sole root cause.\n\n## Required behavior\n\n- Every basic CLI command must dispatch within a bounded startup time under supported Windows/pipx configurations.\n- `specsmith load` must not import or construct unrelated heavyweight command modules before dispatch unless required by the chosen CLI architecture.\n- Command registration failures must be visible and actionable; commands must not disappear silently behind broad `except Exception: pass` blocks.\n- Locale initialization must be deterministic and must not trigger unbounded filesystem searches.\n- Startup behavior must remain compatible with supported localization behavior in Click.\n- The fix must not special-case the user's path or disable localization globally without evidence and documentation.\n- The implementation should prefer modular/lazy command loading or another bounded registration strategy if eager construction is the amplifying design flaw.\n- Add a startup diagnostic mode or documented profiling command that identifies slow command-module imports without requiring the CLI to finish normal dispatch.\n\n## Suggested implementation directions to evaluate\n\nThese are investigation candidates, not predetermined solutions:\n\n1. Lazy-load command groups/modules only when their command namespace is selected.\n2. Move decorator/type construction out of global import paths where practical.\n3. Replace the broad reporting import suppression with explicit registration and actionable failure reporting.\n4. Cache or constrain locale resolution only if profiling proves gettext lookup is the root cause.\n5. Pin or constrain Click only if an upstream regression is demonstrated and linked.\n6. Ensure packaged locale/environment metadata does not point gettext at invalid, network, or excessively broad paths.\n\n## Named tests and binary pass/fail conditions\n\n### CLI-START-001 — Windows pipx load startup\n\n**Fixture:** install the built wheel with pipx on Windows using Python 3.12; invoke `specsmith load` from a project path containing spaces.\n\n**Pass:** the process reaches command execution or a normal project-level response within the configured startup budget and never requires manual interruption.\n\n**Fail:** startup times out, remains in import/Click/gettext initialization, or produces no bounded diagnostic.\n\n### CLI-START-002 — Basic command startup matrix\n\n**Fixture:** invoke `--help`, `--version`, `load`, `save`, `doctor`, and one reporting command from a pipx install.\n\n**Pass:** every command dispatches within the startup budget; unrelated command modules cannot block `--version`, `--help`, or `load`.\n\n**Fail:** any command hangs during command-tree construction or imports unrelated optional functionality before dispatch.\n\n### CLI-START-003 — Locale matrix\n\n**Fixture:** supported Windows locale plus explicit unset, valid, invalid, and multi-entry values for `LANG`, `LC_ALL`, and `LANGUAGE`.\n\n**Pass:** startup is bounded and diagnostics identify unsupported locale values without hanging.\n\n**Fail:** any locale combination causes unbounded gettext path probing or silent command loss.\n\n### CLI-START-004 — Cold-start filesystem behavior\n\n**Fixture:** cold process with empty Python/Click caches and instrumentation of filesystem probes.\n\n**Pass:** locale and command registration perform a bounded number of local probes and do not enumerate unavailable/network roots.\n\n**Fail:** startup performs unbounded/repeated existence checks or depends on an unavailable drive/share.\n\n### CLI-START-005 — Reporting isolation\n\n**Fixture:** instrument imports while invoking `specsmith load`.\n\n**Pass:** either `reporting.py` is not imported before `load` dispatch, or its registration is proven bounded below the startup budget.\n\n**Fail:** an unrelated reporting command can block `load` indefinitely.\n\n### CLI-START-006 — Registration failure visibility\n\n**Fixture:** inject a deterministic import/registration error into an optional command module.\n\n**Pass:** the CLI reports the failed module and remediation while preserving commands that can safely operate; no bare `pass` hides the defect.\n\n**Fail:** the command silently disappears or all commands crash without identifying the registration failure.\n\n### CLI-START-007 — KeyboardInterrupt handling\n\n**Fixture:** interrupt during intentionally delayed command registration.\n\n**Pass:** the process exits promptly with a clear interruption status and no corrupted state.\n\n**Fail:** interruption is swallowed, misreported as a normal command error, or leaves persistent state half-written.\n\n### CLI-START-008 — Supported Python matrix\n\n**Fixture:** Windows pipx installs across supported Python versions, including 3.12.\n\n**Pass:** startup semantics and budgets are equivalent across the supported matrix.\n\n**Fail:** the defect is hidden by testing only editable installs or one Python version.\n\n### CLI-START-009 — Import-time performance budget\n\n**Fixture:** automated timing for `python -c \"import specsmith.cli\"` and real console-script dispatch.\n\n**Pass:** both remain under an explicitly documented CI budget with a reasonable hosted-runner tolerance; regressions fail CI with per-module timing evidence.\n\n**Fail:** no enforceable budget exists or timing failures provide no localization data.\n\n### CLI-START-010 — Packaged-wheel parity\n\n**Fixture:** compare source checkout, ordinary venv wheel install, and pipx wheel install.\n\n**Pass:** all use the same registered command surface and none hang; differences are recorded and justified.\n\n**Fail:** tests pass only in the source checkout while the published installation topology remains broken.\n\n### CLI-START-011 — Path-character coverage\n\n**Fixture:** working directories containing spaces, Unicode, parentheses, and long Windows paths within supported limits.\n\n**Pass:** CLI startup and command dispatch remain bounded and path-correct.\n\n**Fail:** path spelling changes locale lookup behavior or prevents dispatch.\n\n### CLI-START-012 — No silent command loss\n\n**Fixture:** enumerate the expected public command surface after startup.\n\n**Pass:** every expected command is present, or an unavailable optional command has an explicit recorded reason.\n\n**Fail:** broad exception handling silently removes a command group.\n\n## Acceptance criteria\n\n- [ ] The reported Windows/pipx reproduction no longer hangs.\n- [ ] Root cause is demonstrated with timing/stack evidence rather than inferred solely from the interrupted frame.\n- [ ] CLI dispatch has an explicit, automated startup budget.\n- [ ] Unrelated command modules cannot indefinitely block `load`, `--help`, or `--version`.\n- [ ] Command registration errors are not silently swallowed.\n- [ ] Published-wheel and pipx topology are tested on Windows.\n- [ ] CLI-START-001 through CLI-START-012 pass with machine-readable evidence under #337.\n\n## Relationship to other tickets\n\n- #330: include this regression in the broader cross-platform release/bootstrap audit, but do not close this ticket based only on release CI portability.\n- #313: shell selection happens after CLI startup and does not resolve this import-time hang.\n- #341: Zoo settings lifecycle is unrelated except that its CLI entry points also require bounded startup.\n\n## Non-goals\n\n- Do not treat activation of the repository's `tests\\.venv` after the failure as the fix; the failing `specsmith.exe` came from the pipx environment.\n- Do not close the issue merely because retrying after caches warm happens to succeed.\n- Do not remove reporting commands to make startup faster.\n- Do not disable all localization without a verified compatibility decision.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/342/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/342/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/341",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/341/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/341/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/341/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/341",
    "id": 4905038235,
    "node_id": "I_kwDOR2RC5c8AAAABJFzxmw",
    "number": 341,
    "title": "Automate Zoo Code settings lifecycle and document manual-only integration steps",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 0,
    "created_at": "2026-07-16T18:48:30Z",
    "updated_at": "2026-07-16T18:49:22Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nMake Specsmith automatically configure every Zoo Code setting required for governed operation whenever Zoo exposes a stable machine-editable interface. When a setting can only be changed manually, detect that limitation, report the exact remaining action to the user, and document it in both the main repository and Read the Docs.\n\nThis is a child of #335 and coordinates #329, #330, #331, #339, and #340. It follows the test contract in #337.\n\n## Current-state assessment\n\nSpecsmith already has a Zoo Code integration lifecycle that manages reusable global rules, commands, skills, and the repo-local `.roo/mcp.json`. The existing RTD page is `docs/site/zoo-code-roo.md`, and `mkdocs.yml` already exposes it under Agentic Runtime → Agentic Client → Zoo Code / Roo Code.\n\nHowever, Zoo Code also stores important behavior in extension/global settings, including:\n\n- `autoCondenseContext` and `autoCondenseContextPercent`;\n- `customCondensingPrompt`;\n- `enableCheckpoints` and checkpoint timeout;\n- `alwaysAllowMcp`, `alwaysAllowExecute`, and command allow/deny lists;\n- provider profiles and per-profile thresholds;\n- MCP enablement;\n- custom modes and prompts;\n- terminal-output/context settings.\n\nThe current Specsmith setup does not provide a complete settings ownership inventory, automated mutation plan, manual-only fallback report, or drift reconciliation for these settings.\n\n## Core policy\n\n1. **Automate by default.** If Zoo exposes a stable documented file, command, API, VS Code setting, extension storage adapter, or import format, Specsmith should configure it automatically.\n2. **Do not automate by guessing.** Never edit undocumented opaque extension storage directly unless the format and lifecycle are explicitly supported and tested.\n3. **Explain manual-only steps exactly.** When automation is unavailable, setup and doctor must show the precise UI path, setting name, required value, reason, verification step, and whether restart/reload is required.\n4. **Preserve user-owned settings.** Modify only required Specsmith-managed keys. Back up or transactionally merge settings, and never overwrite unrelated profiles, modes, MCP servers, prompts, or user preferences.\n5. **Make state explainable.** For every desired Zoo setting, report `managed`, `already-compliant`, `manual-required`, `unsupported-version`, `conflict`, or `not-applicable`.\n6. **Fail closed for governance-critical gaps.** A manual-only setting that is required for #340 must prevent “fully governed” status until verified.\n\n## Settings capability registry\n\nCreate a versioned registry describing each Zoo integration setting:\n\n```yaml\nsettings:\n  context.auto_condense:\n    desired: false\n    required_for: governed-context\n    discovery:\n      - zoo-settings-api\n      - vscode-settings\n      - import-export\n    automation: preferred\n    verification: runtime-probe\n    manual:\n      ui_path: Settings > Context Management\n      label: Auto Condense Context\n      expected: Off\n      reload_required: false\n```\n\nEach entry must include:\n\n- semantic Specsmith key;\n- applicable Zoo versions;\n- native Zoo key(s);\n- desired/default value;\n- whether required or recommended;\n- permitted automation mechanisms;\n- read-back verification method;\n- conflict policy;\n- rollback behavior;\n- manual instructions;\n- restart/reload requirement;\n- associated issue/test IDs.\n\nAvoid hard-coding scattered setting mutations throughout the integration module.\n\n## Required automation workflow\n\n`specsmith zoo-code setup` must:\n\n1. detect Zoo/Roo installation and version where possible;\n2. inventory available configuration surfaces;\n3. resolve desired values through #339 global/project/local configuration;\n4. apply all safely automatable settings;\n5. preserve unrelated user state;\n6. read back and verify applied values;\n7. create a machine-readable integration state manifest;\n8. output only remaining manual actions;\n9. state whether the integration is fully governed, partially configured, or unmanaged;\n10. recommend/reload the VS Code window only when necessary.\n\n`specsmith zoo-code doctor` must:\n\n- compare desired, detected, and applied values;\n- identify drift and version incompatibility;\n- automatically repair safe managed drift when `--fix` is used;\n- produce exact manual steps for unfixable gaps;\n- distinguish required failures from recommendations;\n- expose JSON output suitable for agents and CI.\n\nSuggested commands/options:\n\n```text\nspecsmith zoo-code setup --project-dir .\nspecsmith zoo-code setup --dry-run\nspecsmith zoo-code setup --json\nspecsmith zoo-code doctor --project-dir .\nspecsmith zoo-code doctor --fix\nspecsmith zoo-code settings show\nspecsmith zoo-code settings explain <key>\nspecsmith zoo-code settings export-instructions\n```\n\n## Manual-action contract\n\nWhen manual configuration is unavoidable, print a structured block such as:\n\n```text\nMANUAL ACTION REQUIRED: Disable Zoo Code Auto Condense\nReason: Zoo version 1.x does not expose this setting through a supported configuration API.\nRequired for: Specsmith governed context (#340)\n\n1. Open VS Code.\n2. Open Zoo Code.\n3. Select Settings.\n4. Open Context Management.\n5. Turn “Auto Condense Context” off.\n6. Reload the VS Code window only if Zoo requests it.\n7. Run: specsmith zoo-code doctor --project-dir .\n\nVerification: doctor must report context.auto_condense = compliant.\nUntil verified: integration status is PARTIALLY CONFIGURED; governed-context assurances are disabled.\n```\n\nRequirements:\n\n- use exact current UI labels for the detected Zoo version;\n- never say only “change this in settings”;\n- include keyboard-command-palette alternatives where useful;\n- include screenshots only when maintainable, with text instructions remaining authoritative;\n- avoid exposing secrets;\n- provide copyable values;\n- localize only when reliable; English instructions are the baseline.\n\n## Settings required for #340\n\nAt minimum, the registry/setup must manage or explicitly instruct for:\n\n- Zoo native autonomous semantic auto-condense disabled/bypassed;\n- Zoo default/custom CONDENSE prompt not used in healthy governed mode;\n- Zoo sliding-window fallback behavior gated by the Specsmith adapter;\n- MCP enabled and `specsmith-governance` installed;\n- Specsmith context MCP tools allowed for all governed modes;\n- all Specsmith custom modes routed through the context controller;\n- workspace checkpoints labeled/configured separately from semantic checkpoints;\n- profile thresholds coordinated so Specsmith receives telemetry before Zoo reaches a hard limit;\n- required executable/MCP permissions;\n- unmanaged opt-out clearly represented.\n\n## Provider/profile settings\n\nCoordinate with #331:\n\n- automatically create/update the Specsmith-managed local-LLM LiteLLM profile where Zoo's supported import/config mechanism allows it;\n- preserve user-created profiles;\n- do not write secrets directly into exportable settings;\n- use environment/keychain references where supported;\n- when API keys or UI-only secure fields require manual input, provide exact instructions and a verification probe that does not reveal the key;\n- detect endpoint reachability and model aliases separately from configuration presence.\n\n## Ownership and rollback\n\n- Record every key Specsmith changed and its prior value in a local managed-state manifest.\n- `uninstall` should restore prior values only when the current value still equals the Specsmith-managed value; otherwise preserve user modifications and report them.\n- Setup must be idempotent.\n- Upgrades must migrate registry/schema versions deterministically.\n- Concurrent VS Code/Specsmith writes must use conflict detection rather than blind overwrite.\n- Global, project, and profile settings must not be confused.\n\n## Documentation requirements\n\n### Main repository\n\nUpdate or add a prominent integration document in the repository, preferably:\n\n- `docs/site/zoo-code-roo.md` as the canonical user guide used by RTD;\n- a concise link/summary in `README.md` under Integrations or Agent Integrations;\n- optional developer architecture notes under `docs/` if the adapter/settings registry needs deeper implementation documentation.\n\nThe Zoo guide must document:\n\n1. supported Zoo/Roo versions;\n2. architecture and ownership boundary;\n3. what Specsmith configures automatically;\n4. what may require manual configuration;\n5. exact setup and doctor commands;\n6. governed-context behavior from #340;\n7. semantic checkpoint vs workspace snapshot terminology;\n8. local model/LiteLLM profile setup;\n9. global/project/local configuration ownership from #339;\n10. troubleshooting and recovery;\n11. uninstall/rollback behavior;\n12. privacy/secrets behavior;\n13. managed vs unmanaged status indicators.\n\n### Read the Docs\n\n- Keep the page under the existing `mkdocs.yml` Agentic Runtime → Agentic Client integration area.\n- Ensure navigation title remains clear: `Zoo Code / Roo Code`.\n- Add cross-links from `agent-integrations.md`, `configuration.md`, `doctor.md`, and relevant context/ESDB pages.\n- Validate internal links and build the docs in CI.\n- The RTD page and repository source must be the same canonical Markdown, not separately maintained copies.\n\n## Machine-readable status\n\nProduce status such as:\n\n```json\n{\n  \"integration\": \"zoo-code\",\n  \"zoo_version\": \"...\",\n  \"status\": \"partial_manual_required\",\n  \"governed_context\": false,\n  \"settings\": [\n    {\n      \"key\": \"context.auto_condense\",\n      \"desired\": false,\n      \"actual\": true,\n      \"state\": \"manual-required\",\n      \"required\": true,\n      \"instructions_id\": \"ZOO-MANUAL-CONTEXT-001\"\n    }\n  ]\n}\n```\n\nThis output should be consumable by agents without parsing prose.\n\n## Named tests and binary pass/fail conditions\n\n### ZSET-001 — Safe automatic configuration\n\n**Pass:** setup modifies every supported required key, preserves unrelated settings, reads back the values, and reports no unnecessary manual actions.\n\n**Fail:** required supported keys remain unset or unrelated user state changes.\n\n### ZSET-002 — Idempotent setup\n\n**Pass:** a second setup run produces zero semantic changes and identical managed-state output.\n\n**Fail:** repeated runs create duplicates, rewrite files, or reset user values.\n\n### ZSET-003 — Manual-only instruction quality\n\n**Pass:** an unsupported/UI-only fixture produces exact UI path, label, value, reason, verification command, reload requirement, and governed-status impact.\n\n**Fail:** instructions are vague, incomplete, or cannot be verified.\n\n### ZSET-004 — Required manual gap fails closed\n\n**Pass:** an unverified manual-only governance-critical setting results in `partial_manual_required` and no full #340 assurance.\n\n**Fail:** setup/doctor reports healthy governed mode despite the gap.\n\n### ZSET-005 — Version-specific mapping\n\n**Pass:** supported Zoo versions resolve the correct native key/UI label, and unknown versions produce a bounded unsupported-version result.\n\n**Fail:** Specsmith blindly writes an old key or presents stale instructions.\n\n### ZSET-006 — User-setting preservation\n\n**Pass:** custom profiles, unrelated MCP servers, prompts, modes, and preferences remain byte/semantically unchanged.\n\n**Fail:** setup replaces or removes unmanaged state.\n\n### ZSET-007 — Drift detection and repair\n\n**Pass:** changing a managed value is detected; `doctor --fix` repairs automatable drift and prints manual instructions otherwise.\n\n**Fail:** drift is missed or repaired through an unsupported mechanism.\n\n### ZSET-008 — Secrets\n\n**Pass:** secret values are never printed, committed, added to the managed manifest, or copied into non-secret Zoo settings.\n\n**Fail:** any credential leaks through logs/config/docs/tests.\n\n### ZSET-009 — Uninstall rollback\n\n**Pass:** uninstall restores recorded prior values when safe, preserves post-setup user edits, and removes only Specsmith-owned state.\n\n**Fail:** user changes are overwritten or unrelated state is removed.\n\n### ZSET-010 — Concurrent-write conflict\n\n**Pass:** an external settings change between read and write causes an explicit conflict/retry rather than silent overwrite.\n\n**Fail:** last writer silently wins.\n\n### ZSET-011 — Governed-context settings\n\n**Pass:** all #340-required settings are compliant or explicitly manual-blocked, and instrumentation proves Zoo native summarization is not reachable in a healthy governed session.\n\n**Fail:** settings appear configured while Zoo retains autonomous semantic control.\n\n### ZSET-012 — Provider profile automation\n\n**Pass:** the Specsmith LiteLLM profile is created/updated through a supported mechanism without exposing credentials and without altering user profiles.\n\n**Fail:** setup requires avoidable manual profile entry or overwrites profiles.\n\n### ZSET-013 — Cross-platform paths\n\n**Pass:** Linux, Windows, and macOS discover and modify only the correct supported config surfaces.\n\n**Fail:** path assumptions cause missed or wrong-user writes.\n\n### ZSET-014 — Repository documentation\n\n**Pass:** README links to the canonical Zoo guide and accurately distinguishes automatic and manual configuration.\n\n**Fail:** integration behavior exists without discoverable repository documentation.\n\n### ZSET-015 — RTD integration documentation\n\n**Pass:** `docs/site/zoo-code-roo.md` is in `mkdocs.yml`, cross-links resolve, and the documentation build succeeds.\n\n**Fail:** RTD omits the guide, uses stale duplicated content, or contains broken links.\n\n### ZSET-016 — Instruction verification loop\n\n**Pass:** after the user completes a manual step, doctor detects the compliant value and clears the action without requiring hidden state.\n\n**Fail:** the user cannot prove completion or the warning remains incorrectly.\n\n## Acceptance criteria\n\n- [ ] Every relevant Zoo setting has a registry entry and ownership classification.\n- [ ] Setup automatically applies all safely supported settings.\n- [ ] Manual-only requirements produce exact, version-aware, verifiable instructions.\n- [ ] Governance-critical manual gaps block full governed status.\n- [ ] Doctor detects drift and supports safe repair.\n- [ ] Setup/upgrade/uninstall preserve user-owned settings and secrets.\n- [ ] #340 context-controller requirements are represented explicitly.\n- [ ] `docs/site/zoo-code-roo.md` is expanded as the canonical repository/RTD guide.\n- [ ] README and related RTD pages cross-link to the guide.\n- [ ] ZSET-001 through ZSET-016 pass with #337 machine-readable evidence.\n\n## Non-goals\n\n- Do not edit opaque undocumented Zoo extension databases merely to avoid a manual step.\n- Do not promise automation where Zoo exposes no stable integration surface.\n- Do not maintain separate README and RTD copies of the full guide.\n- Do not store Zoo/provider credentials in tracked Specsmith configuration.\n- Do not silently claim the integration is governed when required settings cannot be verified.\n\n## Agent execution notes\n\nFirst create a complete matrix of Zoo settings, storage surfaces, supported versions, and ownership. Prefer official import/export or extension APIs over direct storage edits. Add read-back verification before enabling automatic writes. Implement the registry and dry-run report before mutation. Treat documentation and manual instructions as tested product behavior, not an afterthought.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/341/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/341/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/340",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/340/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/340/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/340/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/340",
    "id": 4905015118,
    "node_id": "I_kwDOR2RC5c8AAAABJFyXTg",
    "number": 340,
    "title": "Make Specsmith the authoritative Zoo Code checkpoint and context controller",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T18:45:05Z",
    "updated_at": "2026-07-16T18:49:30Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nIn Specsmith-governed Zoo Code sessions, make Specsmith the authoritative controller for semantic checkpoints, context-pressure decisions, condensation preparation, ESDB offloading, context-packet construction, rehydration, health validation, and resume integrity.\n\nZoo Code may remain the mechanical sensor/actuator because it owns the live message array, exact provider token accounting, API request assembly, UI, and optional shadow-Git workspace snapshot implementation. Zoo must not independently decide what semantic state survives or generate an ungoverned conversation summary.\n\nThis ticket coordinates #332, #333, #334, #336, #338, and #339 and is a child of #335. It follows the test contract in #337.\n\n## Findings from current implementations\n\n### Zoo Code currently owns too much semantic context behavior\n\nZoo currently:\n\n- calculates context pressure and condensation thresholds;\n- invokes its own LLM summarization prompt;\n- chooses what conversation content and folded file context enters the summary;\n- inserts the generated summary as the sole fresh-start message;\n- falls back to sliding-window truncation when summarization fails;\n- exposes independent `autoCondenseContext`, threshold, custom-condensing-prompt, and checkpoint settings.\n\nThis means a custom Specsmith prompt alone is not enough. Zoo would still own the decision, input selection, summary execution, fallback behavior, and final active-context replacement.\n\n### Specsmith already has the beginnings of the correct control plane\n\nSpecsmith already has:\n\n- a `ContextOrchestrator` with pressure tiers and ESDB awareness;\n- a durable chat handoff mechanism;\n- a Zoo-generated `specsmith-checkpoint` command;\n- an MCP `governance_checkpoint` tool;\n- ESDB/context residency, health, distributed merge, identity, and configuration tickets.\n\nHowever, the existing MCP checkpoint is only a compact governance anchor. It does not yet capture the complete active task state, exact constraints, decisions, evidence, commands/results, context selection, integrity digest, or replacement packet required for authoritative context management.\n\nThe current context orchestrator also directly summarizes/trims history and incorrectly tombstones some records during context eviction. Those behaviors must be replaced through #333/#334 rather than used as the final integration contract.\n\n## Required ownership boundary\n\n### Specsmith owns\n\n- context policy and thresholds;\n- task-fit prediction and checkpoint timing;\n- semantic checkpoint generation;\n- checkpoint schema, IDs, hashes, provenance, and ESDB persistence;\n- authority ranking and pinned invariants;\n- selection of information to keep resident, reference, offload, or exclude;\n- conflict/staleness/contamination checks;\n- generation of the bounded replacement context packet;\n- post-condensation validation and resume authorization;\n- fresh-task handoff contents and continuity validation;\n- audit evidence for all context lifecycle decisions.\n\n### Zoo Code owns only the adapter/mechanical layer\n\n- exact live token and provider-window telemetry;\n- live message/tool-result capture;\n- invoking Specsmith MCP/context APIs;\n- pausing task execution while a context transition is pending;\n- replacing or filtering the effective API history using the exact packet Specsmith returns;\n- displaying checkpoint/health/transition state in the UI;\n- preserving raw task history for UI rewind where desired;\n- emergency mechanical handling when the model API cannot accept another request;\n- optional workspace snapshots/rollback, clearly distinguished from semantic checkpoints.\n\n### Terminology must be explicit\n\nUse separate names:\n\n- **Semantic checkpoint**: Specsmith-authored epistemic/task continuity record.\n- **Context packet**: Specsmith-authored bounded input replacing older active context.\n- **Workspace snapshot**: Zoo/shadow-Git filesystem rollback point.\n- **Conversation rewind**: Zoo UI/history operation.\n\nZoo's existing native “checkpoint” must never be presented as equivalent to a Specsmith semantic checkpoint.\n\n## Governed-mode protocol\n\nImplement a protocol such as:\n\n1. Zoo emits `ContextTelemetry` to Specsmith before each nontrivial turn and after material tool results.\n2. Specsmith returns a signed/hashed `ContextDirective`:\n   - `continue`;\n   - `checkpoint`;\n   - `checkpoint_and_compact`;\n   - `replace_context`;\n   - `spawn_fresh_task`;\n   - `block_for_conflict`;\n   - `emergency_minimal_packet`.\n3. When checkpointing is required, Zoo supplies the required raw inputs/tool results to Specsmith.\n4. Specsmith constructs and persists the semantic checkpoint in ESDB.\n5. Specsmith generates a bounded `ContextPacket` with stable references and integrity digest.\n6. Zoo replaces effective model context with that exact packet, without running its own summary LLM call.\n7. Zoo reports the applied packet digest and resulting token count.\n8. Specsmith validates the transition and returns `resume_allowed=true|false`.\n9. Work resumes only when integrity and health gates pass.\n\nExample directive:\n\n```json\n{\n  \"schema_version\": 1,\n  \"directive_id\": \"CTXDIR-...\",\n  \"action\": \"replace_context\",\n  \"reason\": \"predicted task envelope exceeds safe headroom\",\n  \"checkpoint_required\": true,\n  \"checkpoint_id\": \"CHK-...\",\n  \"packet_id\": \"CTXPKT-...\",\n  \"expected_packet_digest\": \"sha256:...\",\n  \"resume_requires_validation\": true\n}\n```\n\n## Zoo configuration behavior\n\nWhen Specsmith governed-context mode is enabled:\n\n- disable Zoo autonomous semantic auto-condense;\n- disable Zoo custom/default condensation prompt execution;\n- prevent Zoo from independently inserting a generated conversation summary;\n- disable ordinary sliding-window truncation as a normal fallback;\n- configure all Specsmith Zoo modes to use the Specsmith context controller;\n- preserve native Zoo workspace snapshots only as optional rollback functionality;\n- mark any emergency Zoo fallback as degraded and require immediate Specsmith reconciliation before further work.\n\nDo not merely set `customCondensingPrompt` to a Specsmith-themed prompt. That leaves Zoo in control and is not sufficient.\n\nIf Zoo currently lacks an external context-controller hook, provide:\n\n1. an upstream Zoo Code change/PR specification; and\n2. a temporary compatibility mode that triggers Specsmith early enough to avoid Zoo's native threshold, while failing closed rather than silently reverting to Zoo semantic summarization.\n\n## Specsmith APIs/MCP tools\n\nAdd or evolve tools such as:\n\n```text\ncontext_observe\ncontext_preflight\ncontext_checkpoint_create\ncontext_packet_build\ncontext_packet_get\ncontext_transition_validate\ncontext_health\ncontext_rehydrate\ncontext_spawn_handoff\n```\n\nThe old `governance_checkpoint` may remain as a lightweight status anchor, but it must call or reference the authoritative semantic checkpoint subsystem rather than being the sole checkpoint implementation.\n\n### `context_observe` inputs\n\nAt minimum:\n\n- task/session/mode/profile IDs;\n- model/provider/context-window/output reserve;\n- exact current input tokens;\n- recent token growth;\n- turn count and meaningful-event count;\n- current user request;\n- active files and tool-result references;\n- current Zoo task ID;\n- current applied packet/checkpoint IDs;\n- unresolved errors/retries;\n- identity and replica information from #338.\n\n### Semantic checkpoint contents\n\nAt minimum:\n\n- exact current objective and latest user instruction;\n- accepted scope and exclusions;\n- immutable constraints and authority sources;\n- current proposal/plan;\n- decisions and rationale;\n- requirements/tests/acceptance criteria;\n- changed and relevant files with digests/refs;\n- commands, results, failures, and verification evidence;\n- unresolved questions, contradictions, risks, and hypotheses;\n- rejected paths and why;\n- current task/subtask graph;\n- exact next action;\n- identity/delegation/session/replica provenance;\n- context health report;\n- source references and packet selection explanation;\n- checkpoint/event-set digest.\n\n### Context packet rules\n\nThe packet must be:\n\n- generated by Specsmith, not Zoo's condensing LLM;\n- bounded by a token budget supplied by Zoo;\n- schema-validated;\n- authority-aware and provenance-preserving;\n- deterministic where inputs and model-free policies permit;\n- explicit about summaries versus exact quoted/reference material;\n- able to reference ESDB records instead of embedding all history;\n- validated against the checkpoint before use;\n- rejected if critical invariants cannot fit or be safely referenced.\n\n## Emergency behavior\n\nZoo must retain enough mechanical protection to avoid a provider hard failure, but emergency behavior cannot become a second semantic authority.\n\nRequired order:\n\n1. call Specsmith early using predictive thresholds from #332;\n2. if Specsmith is temporarily unavailable, pause and retry within a bounded policy;\n3. if the provider request would otherwise be impossible, use a minimal mechanically safe action that preserves raw history;\n4. mark the session `context_state=degraded_unreconciled`;\n5. block code changes, external writes, release actions, and completion claims;\n6. require Specsmith reconstruction/validation before normal operation resumes.\n\nZoo must never silently use its default summary/truncation and continue as healthy.\n\n## Workspace checkpoints\n\nZoo's native shadow-Git checkpoint capability can remain enabled for file rollback if useful, but:\n\n- it must be labeled `workspace snapshot` in Specsmith integration/UI;\n- semantic checkpoint creation may request a paired workspace snapshot ID;\n- the semantic checkpoint stores the workspace snapshot reference;\n- restoring a workspace snapshot triggers a new Specsmith context-health/reconciliation pass;\n- a workspace restore never rewinds or deletes ESDB evidence automatically.\n\n## Named tests and binary pass/fail conditions\n\n### ZCTX-001 — Specsmith checkpoint authority\n\n**Pass:** a checkpoint request in governed mode invokes Specsmith, produces a persisted semantic checkpoint ID/digest, and Zoo does not generate an independent checkpoint summary.\n\n**Fail:** Zoo's default/custom summarizer creates the authoritative continuity state.\n\n### ZCTX-002 — Specsmith-controlled condensation\n\n**Pass:** at the configured pressure boundary, Specsmith selects the action and returns the exact replacement packet applied by Zoo.\n\n**Fail:** Zoo independently chooses condensation timing, content, or summary.\n\n### ZCTX-003 — Native auto-condense disabled\n\n**Pass:** governed setup disables/bypasses Zoo's autonomous condensation path for every Specsmith mode and `doctor` verifies it.\n\n**Fail:** any governed mode can reach Zoo's normal `summarizeConversation` path without an explicit degraded emergency event.\n\n### ZCTX-004 — No silent sliding-window fallback\n\n**Pass:** a failed Specsmith transition pauses or enters degraded blocked state while preserving history.\n\n**Fail:** Zoo truncates half the conversation and continues as healthy.\n\n### ZCTX-005 — Exact packet integrity\n\n**Pass:** Zoo reports the applied packet digest and Specsmith verifies it before resume.\n\n**Fail:** the packet is altered, supplemented with an unapproved summary, or resumed without validation.\n\n### ZCTX-006 — Required state survival\n\nA fixture includes exact user constraints, accepted decision, failed command, file digest, unresolved contradiction, and next action.\n\n**Pass:** all required invariants are present or stably referenced after context replacement.\n\n**Fail:** any invariant is omitted, weakened, or converted from exact evidence into unsupported inference.\n\n### ZCTX-007 — Context health gate\n\n**Pass:** a contaminated or contradictory packet returns `resume_allowed=false` until #334 cleanup/resolution completes.\n\n**Fail:** Zoo continues because its local summary looks syntactically valid.\n\n### ZCTX-008 — ESDB offload and rehydration\n\n**Pass:** old material leaves active context but remains durable and can be loaded by stable ID through #333.\n\n**Fail:** records are tombstoned/deleted or raw history is blindly reinserted.\n\n### ZCTX-009 — Specsmith unavailable\n\n**Pass:** Zoo preserves raw history, enters explicit degraded state, blocks consequential work, and reconciles before resuming.\n\n**Fail:** native summary/truncation silently takes over.\n\n### ZCTX-010 — Provider hard-limit emergency\n\n**Pass:** emergency handling avoids the failed request, records a degraded event, preserves recoverability, and prevents normal claims/actions until validated.\n\n**Fail:** data is silently discarded or the session remains marked healthy.\n\n### ZCTX-011 — Manual condense action\n\n**Pass:** a user pressing Zoo's condense action in governed mode routes to Specsmith's checkpoint/packet workflow.\n\n**Fail:** the button invokes Zoo's built-in LLM summarizer.\n\n### ZCTX-012 — Workspace snapshot distinction\n\n**Pass:** native Zoo checkpoint creates/restores a workspace snapshot paired to, but distinct from, a Specsmith semantic checkpoint; restore triggers reconciliation.\n\n**Fail:** workspace rollback is treated as epistemic/context rollback or deletes evidence.\n\n### ZCTX-013 — Multi-mode/profile coverage\n\n**Pass:** orchestrator, architect, code, debug, ask, reviewer, and all Specsmith custom modes use the same context-controller contract.\n\n**Fail:** any mode falls back to unmanaged Zoo context behavior.\n\n### ZCTX-014 — Fresh-task handoff\n\n**Pass:** when Specsmith selects `spawn_fresh_task`, Zoo creates the task from the exact governed handoff packet and reports the new task ID for validation.\n\n**Fail:** Zoo creates a task from its own summary or loses task identity/provenance.\n\n### ZCTX-015 — Rewind/edit reconciliation\n\n**Pass:** Zoo conversation rewind/edit invalidates affected applied packets/checkpoints and requires Specsmith reconciliation before continuing.\n\n**Fail:** stale checkpoint authority remains active after history changes.\n\n### ZCTX-016 — Test double proves Zoo summarizer unused\n\n**Pass:** instrumented tests fail if Zoo's `summarizeConversation` or default `CONDENSE` prompt is called in a healthy governed session.\n\n**Fail:** the test suite cannot distinguish Specsmith-controlled context from themed Zoo summarization.\n\n### ZCTX-017 — Cross-platform adapter\n\n**Pass:** Linux, Windows, and macOS produce equivalent directives, packet digests, MCP behavior, and blocked/degraded semantics.\n\n**Fail:** shell/path/platform differences bypass governance or alter semantic results.\n\n### ZCTX-018 — Ungoverned opt-out\n\n**Pass:** users may explicitly disable Specsmith governed-context mode, after which Zoo native behavior is clearly reported as unmanaged and no Specsmith assurance is claimed.\n\n**Fail:** unmanaged sessions are represented as Specsmith-governed.\n\n## Acceptance criteria\n\n- [ ] Specsmith is the only semantic checkpoint generator in governed mode.\n- [ ] Specsmith decides context transitions and generates the exact context packet.\n- [ ] Zoo's normal summarization and sliding-window policies cannot silently run in healthy governed mode.\n- [ ] Zoo remains the live telemetry/message/UI actuator and optional workspace-snapshot provider.\n- [ ] Specsmith validates every applied packet before consequential work resumes.\n- [ ] Emergency fallback is explicit, recoverable, degraded, and blocking.\n- [ ] Existing `governance_checkpoint` evolves into or references the full semantic checkpoint subsystem.\n- [ ] ZCTX-001 through ZCTX-018 exist and pass with #337 machine-readable evidence.\n- [ ] Setup, doctor, export/import, migration, and uninstall preserve user-owned Zoo settings and clearly report governed/unmanaged state.\n\n## Non-goals\n\n- Do not fork all of Zoo's provider, UI, or message persistence logic into Specsmith.\n- Do not treat a custom Zoo condensing prompt as authoritative Specsmith control.\n- Do not disable useful workspace rollback merely because semantic checkpoints move to Specsmith.\n- Do not allow two independent context managers to race.\n- Do not claim perfect control where Zoo lacks the required adapter hook; fail closed and document the upstream dependency.\n\n## Agent execution notes\n\nStart with an architecture decision record and a sequence diagram. Instrument Zoo's current condense/truncation/checkpoint entry points before changing behavior. Build the Specsmith MCP/controller contract and deterministic fixtures first. Then add the Zoo adapter and hard tests proving native summarization is not invoked in healthy governed mode.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/340/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/340/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/339",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/339/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/339/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/339/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/339",
    "id": 4904907577,
    "node_id": "I_kwDOR2RC5c8AAAABJFrzOQ",
    "number": 339,
    "title": "Unify Specsmith global, project, and local configuration schemas",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 0,
    "created_at": "2026-07-16T18:30:26Z",
    "updated_at": "2026-07-16T18:30:57Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nCreate one documented, versioned configuration system for Specsmith that cleanly separates:\n\n1. global user and machine preferences;\n2. tracked project policy and metadata;\n3. untracked project-local/machine-local overrides;\n4. environment and command-line overrides.\n\nConsolidate the current fragmented configuration paths without losing backward compatibility. This is required by #338 and #336 and follows the test contract in #337.\n\n## Current-state assessment\n\nSpecsmith already has a substantial Pydantic `ProjectConfig` used for project scaffolding and a canonical tracked project manifest at `docs/SPECSMITH.yml`. However, other code separately reads `.specsmith/governance/config.yaml` and falls back to `.specsmith/config.yml`. There is no single versioned global user configuration schema or centralized precedence/resolution API.\n\nThe result is ambiguity over which file owns project metadata, governance policy, runtime preferences, ESDB settings, Zoo Code settings, identity, and machine-specific values.\n\n## Configuration layers and precedence\n\nDefine one resolver with this precedence, highest first:\n\n1. explicit CLI flags;\n2. environment variables;\n3. untracked project-local config;\n4. tracked project config;\n5. global user config;\n6. built-in defaults.\n\nEvery resolved value must expose its source layer through `config explain`.\n\n## Canonical locations\n\nUse platform-native global config directories:\n\n- Linux: `${XDG_CONFIG_HOME:-~/.config}/specsmith/config.yml`\n- macOS: `~/Library/Application Support/Specsmith/config.yml` unless XDG is explicitly selected\n- Windows: `%APPDATA%\\Specsmith\\config.yml`\n\nProject files:\n\n- `docs/SPECSMITH.yml` — tracked, reviewable project policy and metadata;\n- `.specsmith/local.yml` — untracked local overrides for one checkout/worktree;\n- secrets remain outside these files or use references to environment variables/keyrings.\n\nDo not use `.specsmith/config.yml` as a second ambiguous tracked project schema after migration. Preserve it only as a legacy input until migrated.\n\n## Schema separation\n\nCreate versioned Pydantic models such as:\n\n- `GlobalConfig`\n- `ProjectConfig`\n- `LocalConfig`\n- `ResolvedConfig`\n- nested sections for identity, ESDB, context governance, Zoo Code, providers, verification, paths, telemetry, and privacy.\n\nFields must explicitly declare which layers may set them. For example:\n\n- project name/type/requirements policy: tracked project layer;\n- preferred provider, prompt caching, default identity alias: global layer, locally overridable;\n- replica ID, local endpoint reachability, machine paths: local/global machine state, never tracked project policy;\n- API keys and credentials: secret references only, never plaintext tracked config.\n\n## Required behavior\n\n1. Add a single config loader/resolver used by CLI, governance, ESDB, context orchestration, Zoo integration, and identity resolution.\n2. Add schema versions and deterministic migrations.\n3. Detect duplicate/conflicting legacy files and fail with actionable diagnostics rather than silently selecting an arbitrary value.\n4. Preserve comments where practical; otherwise create backups and provide a migration report.\n5. Add commands:\n\n```text\nspecsmith config paths\nspecsmith config show [--resolved]\nspecsmith config get <key>\nspecsmith config set <key> <value> [--global|--project|--local]\nspecsmith config unset <key> [--global|--project|--local]\nspecsmith config explain <key>\nspecsmith config validate\nspecsmith config migrate\n```\n\n6. `show --resolved` must redact secrets and display source provenance for each value.\n7. Unknown keys must either fail validation or be preserved in an explicitly namespaced extensions section; never silently drop them.\n8. Project config must be deterministic and merge-friendly: stable key ordering, UTF-8, LF normalization, no timestamps or machine-specific paths.\n9. Local config must be automatically added to generated `.gitignore` files.\n10. Global and local writes must be atomic and permission-conscious.\n11. Support configuration profiles only when their semantics are explicit; avoid duplicating Zoo Code profile storage inside Specsmith.\n12. Document which values belong in each layer and provide minimal examples.\n\n## Migration mapping\n\n- canonical scaffold/project fields from `docs/SPECSMITH.yml` remain in the tracked project model;\n- legacy root `scaffold.yml` migrates to `docs/SPECSMITH.yml`;\n- `.specsmith/governance/config.yaml` governance-specific values migrate into a namespaced project section when tracked policy, or local section when machine-specific;\n- `.specsmith/config.yml` is classified field-by-field and migrated to project/global/local as appropriate;\n- conflicts require an explicit report and may not be silently overwritten.\n\n## Named tests and binary pass/fail conditions\n\n### CONFIG-001 — Precedence\n\n**Pass:** CLI > environment > local > project > global > defaults for every tested field, and `config explain` reports the winning source.\n\n**Fail:** a lower layer overrides a higher layer or source reporting is incorrect.\n\n### CONFIG-002 — Platform paths\n\n**Pass:** Linux, macOS, and Windows resolve canonical global paths without embedding another platform's separators or locations.\n\n**Fail:** platform paths differ from the declared policy or require manual path editing.\n\n### CONFIG-003 — Project determinism\n\n**Pass:** writing the same project config twice is byte-identical and produces no Git diff.\n\n**Fail:** ordering, timestamps, newline conversion, or machine values create drift.\n\n### CONFIG-004 — Local isolation\n\n**Pass:** `.specsmith/local.yml` overrides one worktree, is ignored by Git, and does not change another worktree's resolved config.\n\n**Fail:** local state is committed or leaks between worktrees.\n\n### CONFIG-005 — Legacy migration\n\n**Pass:** fixtures containing all legacy config locations migrate without value loss, create a report/backup, and a second migration is zero-diff.\n\n**Fail:** values disappear, move to the wrong layer, or migration is non-idempotent.\n\n### CONFIG-006 — Conflicting legacy values\n\n**Pass:** contradictory values in legacy files produce an explicit conflict requiring resolution.\n\n**Fail:** one value silently wins.\n\n### CONFIG-007 — Secret handling\n\n**Pass:** resolved output redacts secret values, tracked files contain only references, and doctor detects plaintext credentials in tracked config.\n\n**Fail:** credentials appear in output, logs, fixtures, or committed files.\n\n### CONFIG-008 — Unknown keys\n\n**Pass:** unknown keys are rejected with location-aware diagnostics or preserved under a documented extension namespace.\n\n**Fail:** unknown keys are silently ignored or removed.\n\n### CONFIG-009 — Concurrent project edits\n\n**Pass:** two branches changing different project fields merge cleanly; conflicting same-field changes remain normal visible Git conflicts and are never auto-resolved by machine-local precedence.\n\n**Fail:** generated rewrites cause whole-file conflicts or silently choose one branch.\n\n### CONFIG-010 — Consumer parity\n\n**Pass:** CLI, governance store, ESDB, context orchestration, Zoo integration, and identity resolver all receive the same resolved values and provenance.\n\n**Fail:** any subsystem reads a legacy file independently and obtains a different value.\n\n### CONFIG-011 — Atomic writes and recovery\n\n**Pass:** interrupted writes leave either the old or new valid file, with recovery diagnostics and no partial YAML.\n\n**Fail:** truncation or malformed configuration is accepted.\n\n### CONFIG-012 — Manual editing round-trip\n\n**Pass:** a documented hand-edited config validates and survives load/write without semantic changes.\n\n**Fail:** valid user changes are overwritten or normalized into different semantics.\n\n## Acceptance criteria\n\n- [ ] One resolver and precedence model governs all Specsmith configuration consumers.\n- [ ] Versioned global, project, and local schemas exist.\n- [ ] `docs/SPECSMITH.yml` remains the canonical tracked project file.\n- [ ] `.specsmith/local.yml` is the canonical ignored project-local override.\n- [ ] Global paths are platform-native.\n- [ ] Legacy config files migrate deterministically and idempotently.\n- [ ] Secrets are referenced/redacted, not stored in tracked config.\n- [ ] CONFIG-001 through CONFIG-012 exist and pass with machine-readable #337 evidence.\n- [ ] Documentation clearly explains ownership, precedence, paths, and examples.\n\n## Non-goals\n\n- Do not create one giant file containing secrets, runtime databases, and project policy.\n- Do not let global preferences silently override tracked project safety policy unless the field explicitly allows it.\n- Do not duplicate provider secrets or Zoo Code-managed credentials.\n- Do not retain multiple active project config files after migration.\n\n## Agent execution notes\n\nInventory every direct config-file read before implementing. Introduce the resolver first, migrate consumers incrementally, and add a temporary diagnostic for legacy direct reads. Keep configuration semantics separate from ESDB records: config determines policy; ESDB records actions and evidence.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/339/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/339/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/338",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/338/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/338/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/338/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/338",
    "id": 4904905962,
    "node_id": "I_kwDOR2RC5c8AAAABJFrs6g",
    "number": 338,
    "title": "Add layered Specsmith user, agent, and replica identity awareness",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 0,
    "created_at": "2026-07-16T18:30:13Z",
    "updated_at": "2026-07-16T18:31:36Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nGive Specsmith stable, explainable awareness of the human user, executing agent, service principal, replica/worktree, and session responsible for every governed action. Auto-detect useful identity signals, persist a global default, allow project-local overrides, and let users inspect or manually change the resolved identity without silently conflating display names with identity.\n\nThis is a focused child of #336 and depends on the layered configuration foundation in #339. It follows the verification contract in #337.\n\n## Identity model\n\nDefine distinct identity dimensions:\n\n- `actor_id`: stable human or service-principal identity responsible for the action;\n- `actor_display_name`: mutable human-readable label;\n- `provider_accounts`: linked external identities such as GitHub, GitLab, Bitbucket, Azure DevOps, or local Git identity;\n- `agent_id`: executing agent/model instance or named automation identity;\n- `delegation`: relationship showing that an agent acted for a human/service actor;\n- `replica_id`: stable machine/worktree writer identity used by distributed ESDB;\n- `session_id`: one bounded execution session;\n- `identity_confidence` and `verification_state`: explain how the identity was resolved.\n\nDo not use email addresses, Git display names, OS usernames, branch names, or provider usernames as the canonical actor ID by themselves.\n\n## Resolution precedence\n\nResolve each identity field independently using the configuration precedence from #339:\n\n1. explicit CLI/session override;\n2. environment override;\n3. project-local identity override;\n4. tracked project identity policy or permitted mapping;\n5. global Specsmith user identity;\n6. verified provider identity auto-detection;\n7. local Git identity;\n8. OS account fallback;\n9. anonymous/generated local identity with a warning.\n\nA lower-confidence source must not silently replace a higher-confidence configured identity.\n\n## Auto-detection providers\n\nSupport pluggable detection, initially including:\n\n- GitHub CLI authenticated user when `gh` is available;\n- repository GitHub remote owner/account context as supporting evidence only;\n- GitLab CLI/account where available;\n- Azure DevOps or other supported VCS identity where available;\n- `git config user.name` and `user.email` as low-confidence supporting metadata;\n- OS username as final low-confidence fallback.\n\nDetection must be read-only, bounded, timeout-safe, and work offline. Missing provider CLIs must not fail normal Specsmith operation.\n\n## Global and local configuration\n\nGlobal config may contain a default identity profile:\n\n```yaml\nidentity:\n  actor_id: USER-...\n  display_name: Example User\n  preferred_profile: default\n  provider_links:\n    github:\n      login: example\n      account_id: \"12345\"\n      verification: provider-detected\n  privacy:\n    include_email_in_events: false\n```\n\nProject-local `.specsmith/local.yml` may select or override the active profile for that checkout or worktree without changing the tracked project configuration.\n\nTracked `docs/SPECSMITH.yml` may define identity policy, organization IDs, required trust levels, and allowed actor mappings, but should not force every contributor to share one personal identity.\n\n## Required commands\n\nAdd operations such as:\n\n```text\nspecsmith identity show\nspecsmith identity detect\nspecsmith identity explain\nspecsmith identity list\nspecsmith identity create <name>\nspecsmith identity use <name> [--global|--local]\nspecsmith identity set <field> <value> [--global|--local]\nspecsmith identity link github\nspecsmith identity unlink github\nspecsmith identity verify\nspecsmith identity rotate-replica\n```\n\n`show` and `explain` must display the resolved source, confidence, verification state, delegation, replica, and session identity while redacting private data according to policy.\n\n## Stable ID requirements\n\n1. Generate opaque stable IDs rather than IDs derived directly from names or email addresses.\n2. Keep global actor identity stable across repositories and branch changes unless manually rotated.\n3. Keep `replica_id` stable for one installation/worktree writer, but allow explicit rotation and document whether clones receive a new replica.\n4. New worktrees should receive distinct replica IDs when they can write independently.\n5. Session IDs must be unique and non-reused.\n6. Agent IDs must distinguish separate agents/models where attribution matters.\n7. Identity aliases and provider links may change without rewriting historical events.\n\n## ESDB integration\n\nEvery canonical ESDB event introduced by #336 must include resolved identity provenance:\n\n- actor ID and display label at event time;\n- executing agent ID and model/provider metadata where applicable;\n- delegation relationship;\n- replica and session IDs;\n- resolution source and verification state;\n- optional provider-account references;\n- no unnecessary private fields.\n\nHistorical records must retain their original attribution even after a user changes their current display name or linked account.\n\n## Trust and privacy\n\n- Provider auto-detection establishes evidence, not absolute identity proof.\n- Organization policy may require a configured mapping, signed attestation, or verified account ID for privileged actions.\n- Do not expose email by default in committed canonical events.\n- Do not store provider tokens or credentials in Specsmith config or ESDB.\n- A user may disable provider detection or particular detectors.\n- Manual override must be visible in provenance.\n- Shared machines must support multiple named identity profiles without overwriting each other.\n\n## Named tests and binary pass/fail conditions\n\n### IDENTITY-001 — GitHub detection\n\n**Pass:** with a mocked/current GitHub CLI account, Specsmith links the account as provider evidence, creates or selects a stable actor profile, and records the detection source.\n\n**Fail:** the login string alone becomes the canonical ID or credentials are persisted.\n\n### IDENTITY-002 — Offline fallback\n\n**Pass:** without network/provider CLIs, configured global identity remains usable; otherwise Git/OS fallback is marked low-confidence with actionable guidance.\n\n**Fail:** normal commands fail solely because provider detection is unavailable.\n\n### IDENTITY-003 — Precedence\n\n**Pass:** explicit > environment > local > project policy/mapping > global > detected provider > Git > OS, with `identity explain` showing each candidate and winner.\n\n**Fail:** a lower layer silently replaces a higher configured identity.\n\n### IDENTITY-004 — Same display name, different users\n\n**Pass:** two profiles with the same display name retain different actor IDs and remain distinguishable after ESDB merge.\n\n**Fail:** profiles collapse because names match.\n\n### IDENTITY-005 — One user, multiple replicas\n\n**Pass:** one actor working in two independent worktrees has one actor ID and two distinct replica IDs; merged events retain both.\n\n**Fail:** replicas are conflated or actor identity changes by worktree.\n\n### IDENTITY-006 — Multiple agents for one user\n\n**Pass:** two agents acting for one human share the delegated actor ID but have distinct agent IDs and session IDs.\n\n**Fail:** agent actions cannot be attributed separately or appear as direct human actions without delegation.\n\n### IDENTITY-007 — Manual override\n\n**Pass:** a user can select a different local/global profile, provenance records the manual source, and historical events remain unchanged.\n\n**Fail:** changing identity rewrites history or silently affects another worktree.\n\n### IDENTITY-008 — Provider account change\n\n**Pass:** linking a new provider account updates the current identity profile without changing actor ID unless the user explicitly creates/selects another actor.\n\n**Fail:** provider username changes create accidental new identities or merge unrelated users.\n\n### IDENTITY-009 — Replica rotation\n\n**Pass:** explicit rotation creates a new replica ID with a recorded predecessor link; old events remain attributable.\n\n**Fail:** rotation rewrites old events or reuses the previous ID.\n\n### IDENTITY-010 — Shared machine profiles\n\n**Pass:** multiple named profiles coexist globally and project-local selection chooses one without modifying the others.\n\n**Fail:** detecting or selecting one user overwrites another user's profile.\n\n### IDENTITY-011 — Privacy\n\n**Pass:** email and private provider metadata are omitted/redacted by default from committed events and normal output.\n\n**Fail:** private fields appear without explicit policy opt-in.\n\n### IDENTITY-012 — Unauthorized claim\n\n**Pass:** an event or environment override claiming another configured actor without required mapping/attestation is marked unverified or blocked according to project policy.\n\n**Fail:** a matching string is treated as verified identity.\n\n### IDENTITY-013 — Cross-platform stability\n\n**Pass:** Linux, Windows, and macOS resolve the same configured actor profile semantics while maintaining platform-local replica identity.\n\n**Fail:** path, case, hostname, or username differences change actor identity unexpectedly.\n\n### IDENTITY-014 — ESDB merge attribution\n\n**Pass:** multi-user events merged under #336 retain actor, agent, replica, session, delegation, and verification fields with deterministic materialized results.\n\n**Fail:** attribution is dropped, overwritten, or changed by merge order.\n\n## Acceptance criteria\n\n- [ ] Centralized identity resolver exists and uses #339 configuration precedence.\n- [ ] Actor, agent, replica, and session identities are distinct.\n- [ ] GitHub and other provider detection is pluggable, read-only, optional, and explainable.\n- [ ] Global defaults and local overrides are supported.\n- [ ] Users can manually create, select, modify, link, and inspect identities.\n- [ ] ESDB events retain stable multi-user/multi-agent attribution.\n- [ ] Private data and credentials are not written by default.\n- [ ] IDENTITY-001 through IDENTITY-014 exist and pass with #337 machine-readable evidence.\n\n## Non-goals\n\n- Do not make GitHub mandatory for Specsmith identity.\n- Do not claim provider detection proves legal identity.\n- Do not use a mutable display name as a primary key.\n- Do not store authentication tokens.\n- Do not put personal local identity values into tracked project configuration by default.\n\n## Agent execution notes\n\nImplement #339's config resolver first. Keep identity detection adapters pure and independently testable. Reuse the resolved identity object everywhere instead of adding new environment lookups in individual subsystems. Coordinate the event envelope and multi-user tests with #336.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/338/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/338/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/337",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/337/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/337/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/337/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/337",
    "id": 4904837706,
    "node_id": "I_kwDOR2RC5c8AAAABJFniSg",
    "number": 337,
    "title": "Require traceable test cases and binary pass/fail evidence for the release and context epics",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T18:20:14Z",
    "updated_at": "2026-07-16T19:05:32Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nMake every child ticket in the CI-only release epic (#328) and Zoo/context lifecycle epic (#335) implementation-ready by requiring named test cases, explicit fixtures, and binary pass/fail conditions that can be traced from issue acceptance criteria to automated CI evidence.\n\nThis ticket is a governance and verification contract. It does not replace the feature-specific tests already listed in child issues; it standardizes how they must be specified, implemented, and reported.\n\n## Scope\n\nApplies to:\n\n- #318, #319, #321, #323, #324, #325, #326, #327, #328\n- #329, #330, #331, #332, #333, #334, #335, #336\n\nAny newly discovered child issue added to either epic inherits this contract.\n\n## Required ticket test contract\n\nBefore implementation is considered complete, each child ticket must contain or link to a test matrix with:\n\n1. stable test-case IDs;\n2. scenario and preconditions;\n3. exact operation under test;\n4. observable expected outputs/state;\n5. explicit pass condition;\n6. explicit fail condition;\n7. required fixture/data setup;\n8. operating systems and backends covered;\n9. whether the test is unit, integration, end-to-end, migration, security, or failure-injection;\n10. CI job/artifact that proves the result;\n11. requirement and acceptance-criterion traceability;\n12. cleanup/isolation expectations.\n\nA statement such as “add tests” or “CI passes” is insufficient.\n\n## Required test classes for every ticket\n\nEach ticket must identify applicable cases from this baseline:\n\n- happy path;\n- idempotent second run;\n- user-customized state preservation;\n- malformed input/configuration;\n- missing dependency or unavailable external service;\n- partial/interrupted operation;\n- rollback or safe failure;\n- stale/legacy migration;\n- duplicate input/event;\n- concurrent or repeated execution;\n- security/secret handling;\n- Linux, Windows, and macOS portability where filesystem or process behavior is involved;\n- SQLite and ChronoStore parity where ESDB semantics are involved;\n- deterministic output/hash behavior where generated or canonical artifacts are involved.\n\nTickets may mark classes not applicable, but must state why.\n\n## Binary result model\n\nEvery automated test must produce one of:\n\n- `PASS`: all specified observable invariants hold;\n- `FAIL`: at least one invariant is violated;\n- `SKIP-BLOCKED`: only for an explicitly unavailable licensed/external capability, with a mandatory contract-fixture test still executed;\n- `XFAIL-KNOWN`: temporary only, linked to a separate defect with an expiry/removal condition.\n\nA test must not report success when:\n\n- evidence is missing;\n- an exception is swallowed;\n- an external call was never exercised but was assumed successful;\n- a malformed record was silently ignored;\n- a partial publish/write/merge occurred;\n- unresolved authoritative conflicts remain;\n- generated state differs after an idempotence/fixed-point pass.\n\n## Required traceability artifact\n\nGenerate a machine-readable report, for example:\n\n```json\n{\n  \"schema_version\": 1,\n  \"issue\": 333,\n  \"requirement_ids\": [\"REQ-...\"],\n  \"test_cases\": [\n    {\n      \"id\": \"CTX-ESDB-001\",\n      \"result\": \"PASS\",\n      \"platform\": \"windows-latest\",\n      \"backend\": \"sqlite\",\n      \"evidence\": [\"pytest::...\", \"artifact:...\"]\n    }\n  ],\n  \"overall\": \"PASS\"\n}\n```\n\nCI should upload this artifact and fail when required cases are absent, duplicated, stale, or not passing.\n\n## Required epic-level end-to-end tests\n\n### E2E-REL-001 — Candidate release closure\n\n**Pass:** exact candidate wheel governs its own checkout, second pass is zero diff, tag workflow mutates no source, and the same artifact digests are tested and prepared for publication.\n\n**Fail:** stable/global Specsmith performs final governance, source changes after tagging, or rebuilt/published artifacts differ.\n\n### E2E-REL-002 — Duplicate version and partial publication\n\n**Pass:** existing PyPI version or partial/digest-mismatched publication fails closed with explicit evidence and no force-retag/skip-existing recovery.\n\n**Fail:** workflow reports success or mutates an existing release identity.\n\n### E2E-CTX-001 — Large task near capacity\n\n**Pass:** a high-cost task near 70% usable-context pressure is checkpointed and either condensed safely or delegated before broad execution; required invariants survive.\n\n**Fail:** large work starts without fit preflight or critical state is lost.\n\n### E2E-CTX-002 — ESDB offload and clean rehydration\n\n**Pass:** durable evidence leaves active context without deletion, a bounded relevant packet is rebuilt, and exact constraints/provenance remain retrievable.\n\n**Fail:** evidence is tombstoned, raw history is blindly restored, or authoritative constraints are missing.\n\n### E2E-CTX-003 — Contaminated context cleanup\n\n**Pass:** stale, duplicate, contradictory, and injected content is detected; cleanup preserves evidence, rebuilds a healthy packet, and blocks continuation when unresolved critical conflicts remain.\n\n**Fail:** cleanup silently deletes evidence or treats a contaminated packet as healthy.\n\n### E2E-ESDB-001 — Distributed multi-user convergence\n\n**Pass:** independent events from multiple branches/users/agents merge in all tested permutations to the same canonical root and conflict set, with complete attribution.\n\n**Fail:** merge order changes healthy state, any event is lost, or last-write-wins hides a conflict.\n\n## Multi-user ESDB minimum matrix\n\nThe #336 suite must include at least:\n\n- two humans, same display name, different stable actor IDs;\n- one human using two replicas/worktrees;\n- two agents acting for one human;\n- one autonomous service actor;\n- concurrent same-record edits;\n- concurrent independent edits;\n- user/agent delegation metadata;\n- unauthorized actor substitution;\n- merge after rebase and branch rename;\n- SQLite and ChronoStore materialization parity.\n\n## CI gates\n\nA PR closing any covered issue fails unless:\n\n- all required named tests exist;\n- all required test IDs appear in the report;\n- all non-exempt cases pass;\n- no undocumented skip exists;\n- fixed-point/idempotence tests leave no tracked or untracked drift;\n- platform/backend matrices meet the ticket’s declared coverage;\n- pass/fail evidence is uploaded and linked in the PR summary.\n\n## Acceptance criteria\n\n- [ ] Every covered child ticket has a named test matrix with explicit pass and fail conditions, either in its body or linked to a versioned test specification.\n- [ ] Feature PRs add tests and traceability records in the same change as implementation.\n- [ ] Epic-level E2E-REL-001..002, E2E-CTX-001..003, and E2E-ESDB-001 are automated.\n- [ ] Multi-user ESDB coverage meets the minimum matrix above.\n- [ ] CI rejects missing evidence, silent skips, swallowed failures, and non-idempotent outputs.\n- [ ] Test reports are machine-readable, archived, and mapped to issue/requirement IDs.\n\n## Agent execution notes\n\nDo not postpone tests to a later cleanup PR. Before coding a child ticket, add or refine its named test matrix. Prefer deterministic fixtures and failure injection over tests that depend on timing. Keep licensed ChronoStore execution optional only when unavailable, but always run backend-contract fixtures so semantic parity is still checked.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/337/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/337/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/336",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/336/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/336/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/336/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/336",
    "id": 4904828363,
    "node_id": "I_kwDOR2RC5c8AAAABJFm9yw",
    "number": 336,
    "title": "Make ESDB branch-merge-safe with replicated events, explicit conflicts, and multi-user identity",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 2,
    "created_at": "2026-07-16T18:18:53Z",
    "updated_at": "2026-07-16T18:31:51Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nMake Specsmith ESDB safe for distributed development where multiple users, agents, devices, worktrees, and Git branches independently create epistemic records and later merge them without data loss, silent last-write-wins behavior, broken audit chains, or ambiguous attribution.\n\nThis is foundational for #333 and #334 and must be included in epic #335.\n\n## Current-state assessment\n\nThe repository already makes two correct choices:\n\n1. `.specsmith/esdb.sqlite3` is ignored and treated as a local rebuildable index rather than a Git-merged database file.\n2. Canonical session events use immutable IDs and deterministic set-union merge semantics, rejecting the same event ID with different content.\n\nHowever, the overall ESDB model is not yet safely distributed:\n\n- `.chronomemory/events.wal` is a single tracked linear sequence/hash chain. Two branches extending the same head create divergent sequence numbers and `prev_hash` values.\n- `.chronomemory/snapshot.json` is a shared derived mutable file and can conflict or silently reflect only one branch.\n- mutable record IDs are upserted in SQLite with unconditional last-write-wins semantics.\n- the audit-event table is one local linear chain and cannot directly merge two independently extended branches.\n- actor identity is a display string derived from environment/Git name, not a stable user/agent/device identity.\n- no replica identity, branch observation, causal parents, conflict records, or deterministic merge protocol is defined.\n\n## Recommended architecture\n\nUse a **Git-mergeable immutable event set** as the canonical distributed representation and treat SQLite/snapshots/materialized records as local derived views.\n\nDo not attempt to Git-merge SQLite databases or splice two independent linear hash chains.\n\n### Canonical event model\n\nEvery mutation produces an immutable canonical event containing at least:\n\n```json\n{\n  \"schema_version\": 1,\n  \"event_id\": \"content-addressed-or-uuidv7-id\",\n  \"record_id\": \"REQ-001\",\n  \"operation\": \"create|revise|supersede|tombstone|link|resolve_conflict\",\n  \"payload\": {},\n  \"payload_hash\": \"...\",\n  \"actor_id\": \"USER-...|AGENT-...\",\n  \"agent_id\": \"AGENT-...\",\n  \"replica_id\": \"REPLICA-...\",\n  \"session_id\": \"...\",\n  \"work_item_id\": \"...\",\n  \"branch_observed\": \"feature/example\",\n  \"commit_observed\": \"...\",\n  \"causal_parents\": [\"EVENT-...\"],\n  \"timestamp_utc\": \"...\",\n  \"signature_or_attestation\": null\n}\n```\n\n`branch_observed` is provenance only and must not define identity or merge order because branches can be renamed or rebased.\n\n### Storage layout\n\nPrefer one of these Git-friendly layouts, selected through implementation analysis:\n\n1. one immutable event per file under `.chronomemory/events/<prefix>/<event-id>.json`; or\n2. append-only shard files partitioned by stable `replica_id`, such as `.chronomemory/replicas/<replica-id>/events.jsonl`.\n\nOne-event-per-file provides the cleanest Git set union and conflict isolation. Replica shards are acceptable only if concurrent writers never edit the same shard and deterministic shard repair exists.\n\nThe current monolithic WAL may remain as a generated export/compatibility artifact during migration, but it must not remain the authoritative merge surface.\n\n### Integrity model\n\nReplace one global linear chain with independently verifiable immutable events plus deterministic manifests/checkpoints:\n\n- content hash each event;\n- optionally maintain per-replica hash chains;\n- generate a deterministic Merkle/root manifest over the sorted canonical event set;\n- preserve original per-replica chain evidence after merging;\n- never rewrite historical event payloads to create an artificial global order;\n- materialize a deterministic replay order only for view construction.\n\n### Materialization and conflicts\n\nRebuild SQLite, snapshots, context indexes, and other views from the merged canonical event set.\n\nFor different records, merge by event-set union.\n\nFor the same record:\n\n- causally ordered revisions apply normally;\n- byte-identical duplicate events deduplicate by event ID/hash;\n- concurrent non-overlapping structured-field edits may auto-merge only through an explicit deterministic record-kind policy;\n- concurrent conflicting edits must create a first-class `conflict` record preserving both event IDs and both payloads;\n- no timestamp-only or branch-order last-write-wins resolution for governance data;\n- requirements, tests, user constraints, accepted decisions, tombstones, and security-sensitive records require explicit resolution when concurrent changes conflict.\n\nTombstones are events. A concurrent revise-versus-tombstone must remain conflicted unless an explicit kind policy says otherwise.\n\n### Stable identity and multiple users\n\nDefine stable identities separately:\n\n- `actor_id`: human or service principal responsible for the action;\n- `agent_id`: executing model/agent instance where applicable;\n- `replica_id`: persistent installation/worktree writer identity;\n- `session_id`: one bounded execution session;\n- Git author/committer metadata: supporting provenance, not the primary identity.\n\nRequirements:\n\n- generate a stable local `replica_id` outside tracked project state or through a user-specific ignored config;\n- allow explicit organization-managed actor IDs;\n- never infer two users are the same solely from display name;\n- preserve human-on-behalf-of-agent attribution;\n- prevent one user from silently overwriting another user’s unresolved conflicting evidence;\n- support optional event signing/attestation without making signatures mandatory for local use.\n\n### Merge and rebuild commands\n\nAdd portable operations such as:\n\n```text\nspecsmith esdb merge-check\nspecsmith esdb rebuild\nspecsmith esdb conflicts\nspecsmith esdb resolve <conflict-id>\nspecsmith esdb verify-distributed\n```\n\n`merge-check` must be read-only and suitable for CI. `rebuild` must regenerate all derived state deterministically.\n\n## Migration requirements\n\n1. Import the current monolithic ChronoMemory WAL without losing hashes, sequence information, or provenance.\n2. Assign legacy events to a stable migration replica and preserve the original chain as evidence.\n3. Stop tracking mutable SQLite databases.\n4. Decide whether `snapshot.json` becomes ignored/generated or a deterministic reviewed artifact. It must never be authoritative.\n5. Maintain backward-compatible read/export support for the existing WAL format during a documented transition.\n6. Detect and reject malformed duplicate event IDs with different payload hashes.\n7. Make migration idempotent and resumable.\n\n## Required test cases and binary pass/fail conditions\n\n### ESDB-DIST-001 — Independent branch additions\n\nGiven branches A and B from the same base, each adds ten unique events.\n\n**Pass:** merged canonical store contains all 20 events exactly once; distributed verification passes; both SQLite and snapshot rebuilds contain all records.\n\n**Fail:** any event is missing, duplicated, silently replaced, or verification depends on merge order.\n\n### ESDB-DIST-002 — Identical duplicate event\n\nBoth branches contain the exact same event ID and bytes.\n\n**Pass:** merge produces one logical event and no conflict.\n\n**Fail:** duplicate records appear or the merge is rejected.\n\n### ESDB-DIST-003 — Event-ID collision with different payload\n\nBranches contain the same event ID with different payload hashes.\n\n**Pass:** merge-check fails closed with an explicit collision diagnostic; neither payload is discarded.\n\n**Fail:** one payload wins, both are treated as one, or rebuild proceeds as healthy.\n\n### ESDB-DIST-004 — Concurrent same-record conflicting revision\n\nTwo users revise the same authoritative requirement field from the same causal parent.\n\n**Pass:** both revisions survive and a first-class unresolved conflict blocks use of a single resolved value.\n\n**Fail:** timestamp, Git merge order, actor priority, or SQLite upsert silently selects one.\n\n### ESDB-DIST-005 — Concurrent non-overlapping revision\n\nTwo branches change different mergeable fields under an explicit record-kind policy.\n\n**Pass:** deterministic merged materialization is identical regardless of input order and retains both source event IDs.\n\n**Fail:** result changes with replay order or provenance is lost.\n\n### ESDB-DIST-006 — Revise versus tombstone\n\nOne branch revises a record while another tombstones it from the same parent.\n\n**Pass:** conflict remains explicit until resolved and both operations remain auditable.\n\n**Fail:** deletion or revision silently wins.\n\n### ESDB-DIST-007 — Multi-user attribution\n\nTwo humans and two agents write from three replicas with overlapping sessions.\n\n**Pass:** every event retains correct actor, agent, replica, and session attribution; same display names do not collapse identities.\n\n**Fail:** attribution is missing, ambiguous, or derived only from mutable Git display names.\n\n### ESDB-DIST-008 — Rebase and branch rename\n\nEvents are created, then their branch is renamed and commits rebased.\n\n**Pass:** event identity and merge outcome remain unchanged; observed Git metadata remains provenance only.\n\n**Fail:** event IDs or causal identity depend on branch name or commit SHA alone.\n\n### ESDB-DIST-009 — Three-way and octopus merge convergence\n\nThree replicas independently add and revise records, then merge in every permutation.\n\n**Pass:** all permutations produce the same canonical event-set root, conflict set, and materialized view digest.\n\n**Fail:** any permutation produces a different healthy result.\n\n### ESDB-DIST-010 — Interrupted writer and malformed shard\n\nA partially written event/shard is introduced.\n\n**Pass:** atomic writes prevent normal partial files; verification quarantines malformed artifacts and refuses a healthy rebuild without deleting evidence.\n\n**Fail:** malformed data is silently skipped while reporting success.\n\n### ESDB-DIST-011 — Legacy WAL migration\n\nMigrate a fixture containing the existing linear WAL and snapshot.\n\n**Pass:** every legacy event is preserved, original chain verification remains available, migration is idempotent, and derived view digest is stable.\n\n**Fail:** sequence/hash provenance is lost or a second migration changes the event set.\n\n### ESDB-DIST-012 — Backend parity\n\nReplay the same merged canonical event fixture into SQLite and ChronoStore.\n\n**Pass:** logical records, statuses, conflicts, provenance links, and context-visible results match.\n\n**Fail:** backend selection changes governance semantics.\n\n### ESDB-DIST-013 — Cross-platform merge\n\nGenerate events on Linux, Windows, and macOS using paths and identities containing spaces and Unicode.\n\n**Pass:** canonical hashes, event-set root, and rebuilt logical state are identical.\n\n**Fail:** newline, path, encoding, or case behavior changes event identity.\n\n### ESDB-DIST-014 — Unauthorized identity substitution\n\nAn event claims another configured actor without valid delegation/attestation.\n\n**Pass:** policy marks attribution unverified or rejects it according to configured trust mode; original bytes remain evidence.\n\n**Fail:** claimed actor is accepted as verified solely because it is a string field.\n\n### ESDB-DIST-015 — Conflict resolution\n\nResolve a first-class conflict with an explicit resolution event referencing all alternatives.\n\n**Pass:** resolution is auditable, does not erase alternatives, and all replicas converge after merging the resolution event.\n\n**Fail:** resolution rewrites history or only updates one local database.\n\n## CI requirements\n\n- run deterministic merge permutations;\n- run SQLite tests unconditionally;\n- run ChronoStore parity where licensed/available and maintain contract fixtures otherwise;\n- run Linux, Windows, and macOS canonicalization tests;\n- fail CI on unresolved collisions, malformed canonical events, non-convergent roots, or stale derived artifacts;\n- report conflict IDs and involved event IDs without dumping secrets.\n\n## Non-goals\n\n- Do not merge SQLite files through Git.\n- Do not create a fake global linear history by rewriting branch events.\n- Do not use wall-clock timestamps as the sole conflict resolver.\n- Do not silently collapse multiple users or agents into one actor.\n- Do not make a mutable snapshot the source of truth.\n- Do not require an always-online central server for normal Git-based collaboration.\n\n## Acceptance criteria\n\n- [ ] Canonical ESDB state merges by immutable event-set union.\n- [ ] Derived SQLite and snapshot state rebuild deterministically from canonical events.\n- [ ] The existing monolithic linear WAL is no longer the sole authoritative merge surface.\n- [ ] Concurrent same-record edits never resolve through silent last-write-wins.\n- [ ] Stable actor, agent, replica, and session identities are captured.\n- [ ] All ESDB-DIST-001 through ESDB-DIST-015 tests exist and pass.\n- [ ] Merge order and platform do not change canonical roots or healthy materialized state.\n- [ ] Legacy WAL migration preserves original chain evidence.\n- [ ] Unresolved conflicts are queryable and block unsafe authoritative reads.\n- [ ] Documentation explains branch, worktree, multi-user, merge, rebuild, and conflict-resolution workflows.\n\n## Agent execution notes\n\nStart with an architecture decision record and fixtures demonstrating the current divergent-WAL failure. Keep immutable canonical events separate from local materialized indexes. Coordinate schema changes with #333 context residency and #334 context-health records so they use the same distributed event envelope.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/336/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/336/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/335",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/335/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/335/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/335/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/335",
    "id": 4904775302,
    "node_id": "I_kwDOR2RC5c8AAAABJFjuhg",
    "number": 335,
    "title": "Epic: Zoo Code local-agent defaults and epistemic context lifecycle",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 4,
    "created_at": "2026-07-16T18:11:05Z",
    "updated_at": "2026-07-16T18:49:38Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Goal\n\nMake Specsmith-generated Zoo Code environments immediately usable with a local LiteLLM proxy while proactively managing context as a governed, evidence-backed working set rather than an ever-growing transcript.\n\nThe finished system must:\n\n- default Zoo Code to a local LiteLLM profile with prompt caching;\n- allow all auto-execute commands by default while preserving user customization;\n- predict whether new work fits before execution;\n- create cheap checkpoints without excessive token use;\n- preserve important state before condensation;\n- offload durable information to ESDB/ChronoMemory;\n- load only relevant, authoritative evidence into active model context;\n- detect and clean contaminated context without deleting evidence;\n- start a fresh bounded task when the current context cannot be made safe.\n\n## Child tickets and implementation order\n\n### Zoo defaults\n\n- [ ] #329 — Default Zoo Code auto-approved executable commands to wildcard\n- [ ] #331 — Generate a default Zoo Code Local-LLM LiteLLM profile with prompt caching enabled\n\nThese may proceed in parallel but must share one ownership/preservation model for Zoo settings.\n\n### Context decision layer\n\n- [ ] #332 — Add predictive context-risk preflight and dynamic governance checkpoint policy\n\nThis establishes telemetry, task-envelope estimation, micro-checkpoints, semantic checkpoints, pressure states, condensation decisions, and fresh-task fallback.\n\n### Durable context and retrieval\n\n- [ ] #333 — Implement ESDB-backed context residency, offloading, and smart rehydration\n\nThis separates active-context residency from durable evidence lifecycle, fixes destructive eviction semantics, migrates session continuity toward structured ESDB records, and introduces bounded retrieval.\n\n### Context integrity and cleanup\n\n- [ ] #334 — Add epistemic context-health checks and governed context cleanup\n\nThis detects contamination, staleness, contradiction, provenance loss, duplication, and missing invariants, then rebuilds a verified working packet from authoritative sources.\n\n### Platform completion gate\n\n- [ ] #330 — Audit and harden Specsmith release/bootstrap workflows across Linux, Windows, and macOS\n\nApply its platform requirements to all Zoo settings, context storage, file paths, virtual environments, temporary state, encodings, and tests introduced by this epic.\n\n## Architectural model\n\n### Zoo Code owns\n\n- live provider/model context telemetry;\n- actual context condensation;\n- task creation and boomerang returns;\n- API profile persistence and mode/profile association;\n- execution approval behavior;\n- prompt-cache request/usage support exposed by the provider;\n- user-visible warnings and controls.\n\n### Specsmith owns\n\n- governance and checkpoint policy;\n- task-fit estimation;\n- context pressure states;\n- semantic checkpoint schema;\n- durable ESDB/ChronoMemory evidence;\n- context residency and retrieval ranking;\n- source authority and provenance;\n- context health and cleanup policy;\n- post-condensation integrity verification;\n- fresh-task handoff requirements.\n\n### ESDB/ChronoMemory owns\n\n- durable records and immutable/provenance-linked events;\n- decisions, constraints, requirements, tests, evidence, checkpoints, handoffs, and health events;\n- retrieval indexes and graph relationships;\n- long-term state that does not need continuous residence in the LLM context.\n\n## Required invariants\n\n1. **Leaving context is not deletion.** Removing a record from the active LLM packet must not tombstone or delete durable evidence.\n2. **Active constraints remain explicit.** Exact user constraints, accepted decisions, current proposal, active requirements, critical risks, and next action remain pinned while relevant.\n3. **Summaries are references, not authority.** A summary or handoff must retain source IDs and cannot replace exact authoritative evidence when precision matters.\n4. **No large task starts blindly.** Medium/high tasks receive task-fit preflight before broad reads, edits, or expensive tools.\n5. **Condensation is transactional.** Checkpoint first, condense, verify required state, recalculate capacity, then continue or start a fresh task.\n6. **Cleanup is non-destructive.** Context cleanup changes residency and the working packet, not durable evidence lifecycle state.\n7. **Contradictions remain visible.** Conflicting evidence is preserved and labeled until resolved by authoritative evidence or explicit decision.\n8. **Settings preserve user intent.** Specsmith may migrate its untouched generated defaults but must not silently overwrite user-edited Zoo profiles, mappings, caching choices, or command allowlists.\n9. **No secrets in generated settings.** Local-LLM configuration contains no real API key.\n10. **Cross-platform behavior is real.** Generated settings and context lifecycle tests pass on Linux, Windows, and macOS.\n\n## Default operational flow\n\n```text\nUser requests work\n  -> context health check\n  -> proposal and task-envelope estimate\n  -> compare envelope with usable remaining capacity\n  -> micro-checkpoint material state\n  -> if safe: load bounded relevant context and execute\n  -> if pressured: semantic checkpoint and Zoo condensation\n  -> verify checkpoint/invariants and recalculate\n  -> if still unsafe: create fresh bounded Zoo task\n  -> execute and verify\n  -> persist evidence/checkpoint/health telemetry to ESDB\n  -> release irrelevant residency while preserving durable records\n```\n\n## Default context policy\n\nUse configurable defaults approximately equivalent to:\n\n```yaml\ncontext_governance:\n  checkpoint:\n    token_growth_trigger_pct: 12\n    min_meaningful_turns: 6\n    max_meaningful_turns: 12\n    material_event_trigger: 5\n    failure_trigger: 3\n    cooldown_turns: 4\n  pressure:\n    yellow_pct_of_usable: 50\n    orange_pct_of_usable: 65\n    red_pct_of_usable: 78\n  preflight:\n    uncertainty_margin_pct: 25\n    minimum_post_task_headroom_pct: 20\n  actions:\n    yellow: checkpoint_at_boundary\n    orange: checkpoint_then_evaluate\n    red: checkpoint_condense_recalculate\n    insufficient_after_condense: spawn_fresh_task\n```\n\nTune through measured telemetry rather than treating these as immutable constants.\n\n## Program-level acceptance criteria\n\n- [ ] New Zoo setup creates `Local-LLM` at `http://127.0.0.1:4000`, maps every Specsmith mode to it, and enables supported prompt caching.\n- [ ] New Zoo setup uses a literal wildcard as the sole generated auto-execute allowlist entry.\n- [ ] User-edited Zoo settings survive upgrade/sync.\n- [ ] A large task arriving near 70% context is intercepted before execution and either safely condensed or delegated to a fresh task.\n- [ ] Micro-checkpointing does not require an LLM call.\n- [ ] Semantic checkpoints preserve exact constraints, evidence, decisions, failures, and next action.\n- [ ] ESDB-backed context offloading reduces active context without deleting/tombstoning evidence.\n- [ ] Session resume loads a bounded relevant packet rather than a large raw transcript.\n- [ ] Context-health checks detect stale, contradictory, duplicate, unsupported, or provenance-deficient content.\n- [ ] Governed cleanup can rebuild a verified clean packet and refuses to continue when critical information is missing.\n- [ ] Context retrieval and cleanup are auditable and explainable.\n- [ ] Linux, Windows, and macOS integration tests cover generation, migration, checkpointing, condensation handoff, offload/rehydration, cleanup, and fresh-task fallback.\n\n## Instructions for local AI agents\n\n1. Read this epic and the assigned child ticket in full.\n2. Inspect current Zoo Code schema and current Specsmith implementations before editing; do not trust old example field names.\n3. Implement deterministic, testable policy functions before wiring them to Zoo or LLM calls.\n4. Never use ESDB deletion/tombstoning to mean temporary context eviction.\n5. Never replace exact user constraints or accepted decisions with an unverified prose summary.\n6. Keep public/user customization preservation explicit and tested.\n7. Add migration tests for prior generated settings and legacy session files.\n8. Do not add broad LLM health checks to every turn; use deterministic gates and bounded semantic review.\n9. Do not tag, publish, force-push, or modify branch protection while implementing these tickets.\n10. Keep PRs aligned to child-ticket boundaries unless an interface must land atomically.\n\n## Suggested PR order\n\n1. #329 and #331\n2. #332\n3. #333, beginning with non-destructive residency correction\n4. #334\n5. #330 cross-platform completion and end-to-end matrix\n\nEach PR must leave existing behavior passing and document any temporary interface dependency.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/335/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/335/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/334",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/334/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/334/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/334/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/334",
    "id": 4904772301,
    "node_id": "I_kwDOR2RC5c8AAAABJFjizQ",
    "number": 334,
    "title": "Add epistemic context-health checks and governed context cleanup",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T18:10:40Z",
    "updated_at": "2026-07-16T18:22:28Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nAdd a proactive context-health subsystem that detects contamination, stale assumptions, contradictions, duplication, provenance gaps, and task-irrelevant residue before they degrade agent decisions. Provide a governed cleanup path that preserves authoritative evidence in ESDB/ledgers while rebuilding a clean, bounded working context.\n\nDepends on #332 and #333.\n\n## Definition: context contamination\n\nTreat the active model context as contaminated when one or more of these are present:\n\n- stale facts superseded by newer authoritative evidence;\n- contradictory claims without explicit conflict labeling;\n- speculative/inferred claims presented as accepted facts;\n- summaries with missing or unverifiable provenance;\n- user constraints omitted or weakened;\n- completed/abandoned task residue influencing the active task;\n- duplicate copies of the same source or summary;\n- old errors/results retained after the underlying state changed;\n- untrusted external or agent-generated instructions competing with repository authority;\n- references to files, branches, versions, requirements, or tests that no longer match the current repository state;\n- excessive low-value context crowding out active invariants.\n\n## Required work\n\n1. Define a structured `ContextHealthReport` with at least:\n   - overall status: healthy, warning, degraded, contaminated, unsafe;\n   - context pressure and token budget;\n   - authoritative constraints present/missing;\n   - duplicate groups;\n   - stale records;\n   - contradictions;\n   - unsupported claims;\n   - provenance gaps;\n   - task-irrelevant residue;\n   - source-of-truth mismatches;\n   - recommended cleanup actions;\n   - records that must remain pinned.\n2. Run a cheap deterministic health check:\n   - at task intake/preflight;\n   - after semantic checkpoint creation;\n   - after condensation;\n   - after a fresh-task handoff;\n   - when scope changes;\n   - after three failed attempts;\n   - before high-risk or externally visible actions.\n3. Use an optional LLM epistemic review only when deterministic checks detect ambiguity or conflict. Do not spend tokens on a full semantic audit every turn.\n4. Validate active context against authoritative sources in this precedence order unless project governance defines otherwise:\n   - current explicit user instruction;\n   - accepted proposal and active work item;\n   - repository governance/rules;\n   - requirements/tests/architecture and current code state;\n   - verified tool/test evidence;\n   - durable ESDB records with provenance/confidence;\n   - summaries/handoffs;\n   - unverified inference.\n5. Detect contradictions by identity and scope rather than string similarity alone. Preserve both sides as evidence and mark unresolved conflicts; never silently choose one.\n6. Detect staleness using source digest/version/commit/file metadata and record supersession edges.\n7. Detect missing invariants after condensation, including exact user constraints, acceptance criteria, destructive-action boundaries, unresolved risks, changed files, and next action.\n8. Add a governed cleanup operation with dry-run and apply modes that:\n   - creates a semantic checkpoint first;\n   - persists all important active evidence to ESDB;\n   - removes duplicate and irrelevant resident context only;\n   - excludes stale/superseded items from the new working packet without deleting durable evidence;\n   - rehydrates pinned/current records from authoritative sources;\n   - creates a new bounded context packet and digest;\n   - verifies the rebuilt packet against the checkpoint and active work item;\n   - aborts if critical information cannot be recovered.\n9. Provide cleanup strategies:\n   - deduplicate;\n   - replace raw bulk history with provenance-preserving references;\n   - remove completed-task residue;\n   - refresh changed file summaries;\n   - resolve or explicitly surface contradictions;\n   - reload missing authoritative constraints;\n   - spawn a fresh Zoo task when in-place cleanup cannot produce safe headroom.\n10. Add context quarantine for suspicious or prompt-injection-like content. Quarantined content remains retrievable evidence but is not treated as instruction or authority.\n11. Record health-check and cleanup events in ESDB with before/after packet digests, findings, actions, token estimates, and verification result.\n12. Add agent/Zoo commands or MCP operations such as:\n   - context health;\n   - context cleanup --dry-run;\n   - context cleanup --apply;\n   - context explain <record-id>;\n   - context contradictions;\n   - context rebuild <work-item-id>.\n13. Add a post-cleanup rule: no implementation resumes until required invariants are present and the health status is healthy/warning or explicitly approved with known unresolved conflicts.\n14. Ensure generated Zoo condensation prompts preserve source IDs, work-item IDs, exact constraints, rejected approaches, verification results, and next action.\n\n## Health metrics\n\nInclude explainable component metrics rather than relying only on one score:\n\n- authority coverage;\n- provenance coverage;\n- contradiction burden;\n- stale-context ratio;\n- duplicate-token ratio;\n- active-task relevance ratio;\n- unresolved-risk coverage;\n- checkpoint integrity;\n- compression loss indicators;\n- available post-cleanup headroom.\n\nA composite score may be displayed, but decisions must expose the triggering conditions.\n\n## Non-goals\n\n- Do not delete durable ESDB evidence during context cleanup.\n- Do not allow an LLM summary to overwrite authoritative source facts.\n- Do not automatically resolve genuine contradictions without evidence.\n- Do not run expensive semantic health analysis after every trivial turn.\n- Do not treat lower-confidence evidence as malicious solely because it is uncertain.\n- Do not continue from a failed cleanup or missing critical checkpoint.\n\n## Acceptance criteria\n\n- [ ] Health checks detect missing constraints, stale file/version references, duplicate context, provenance gaps, and explicit contradictions.\n- [ ] Cleanup persists a checkpoint before modifying residency.\n- [ ] Cleanup changes only the active working set, not durable evidence lifecycle state.\n- [ ] A rebuilt context packet contains all pinned invariants and has a verifiable digest.\n- [ ] Post-condensation integrity checks fail when critical facts were lost.\n- [ ] Suspicious embedded instructions can be quarantined without deleting source evidence.\n- [ ] Deterministic checks are cheap enough for frequent boundary use; optional LLM review is gated.\n- [ ] Tests cover contaminated summaries, stale code facts, conflicting decisions, omitted user constraints, duplicate records, prompt-injection content, failed rehydration, and successful fresh-task rebuild.\n- [ ] Before/after health and cleanup events are auditable in ESDB.\n\n## Agent execution notes\n\nBuild this on the residency and retrieval model from #333. Reuse requirement/test edges, source digests, handoff provenance, checkpoint records, current Git state, and context usage telemetry. Implement deterministic validators first, then add optional epistemic-model review behind a clearly bounded interface.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/334/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/334/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/333",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/333/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/333/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/333/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/333",
    "id": 4904769270,
    "node_id": "I_kwDOR2RC5c8AAAABJFjW9g",
    "number": 333,
    "title": "Implement ESDB-backed context residency, offloading, and smart rehydration",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 2,
    "created_at": "2026-07-16T18:10:15Z",
    "updated_at": "2026-07-16T18:46:20Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nUse ESDB/ChronoMemory as the durable epistemic memory layer while keeping only the minimum task-relevant working set in the LLM context. Persist important information once, replace bulky repeated context with compact references, and rehydrate evidence on demand under explicit token and relevance budgets.\n\nDepends on #332 for context-pressure and task-fit policy.\n\n## Critical correction\n\nContext eviction must be separate from evidence lifecycle. The current orchestrator's low-confidence eviction path calls store deletion/tombstoning even though the stated intent is only to remove records from the in-context representation. Fix this boundary before expanding offloading.\n\nA record may be:\n\n- durable and active in ESDB;\n- resident in the current LLM context;\n- referenced by a compact context pointer;\n- temporarily suppressed from context;\n- superseded or tombstoned only through an explicit evidence-lifecycle action.\n\nRemoving a record from LLM context must never delete or tombstone the durable evidence record.\n\n## Required work\n\n1. Define separate durable and residency state models:\n   - ESDB record status/lifecycle;\n   - context residency state;\n   - relevance score for the current work item;\n   - pin/protect status;\n   - last loaded/last used metadata;\n   - token cost estimate;\n   - source/provenance identifiers.\n2. Replace destructive `_evict_low_confidence_records` behavior with a non-destructive context-residency operation.\n3. Add an explicit ESDB context index/view that can mark records as resident, referenced, cold, pinned, stale, or excluded without modifying the underlying evidence status.\n4. Persist micro-checkpoints and semantic checkpoints as structured ESDB records with stable IDs, hashes, provenance, work-item links, and confidence.\n5. Migrate legacy session-state and conversation-history persistence toward ESDB-backed session/checkpoint records. Do not automatically inject up to 200 raw historical turns into a resumed model context.\n6. Store full conversation/session evidence durably, but construct resumed context from:\n   - current objective and approved proposal;\n   - exact user constraints;\n   - active work-item state;\n   - unresolved decisions/risks;\n   - recent relevant tool/test results;\n   - compact references to older records;\n   - a small bounded number of recent raw turns only when needed.\n7. Implement smart retrieval using a hybrid ranking model containing at least:\n   - work-item/requirement/test graph relationship;\n   - explicit pin/protection;\n   - recency;\n   - semantic relevance when available;\n   - epistemic confidence;\n   - source authority;\n   - unresolved/active status;\n   - contradiction relevance;\n   - estimated token cost;\n   - diversity/duplication penalty.\n8. Retrieve into a declared token budget, not a fixed record count. Include fewer high-value records when they are large.\n9. Add context pointers that contain stable record IDs, labels, compact claims, provenance, confidence, and a tool/command for expanding the source on demand.\n10. Add agent-callable retrieval operations, for example:\n    - context search by objective/query;\n    - load record by ID;\n    - load work-item bundle;\n    - load requirement/test evidence bundle;\n    - explain why a record was selected or omitted;\n    - release/unpin residency after task completion.\n11. Deduplicate records and avoid loading both a summary and all source records unless verification requires both.\n12. Pin invariants that must remain available during active work, including exact user constraints, accepted decisions, current proposal, active requirements, critical risks, and latest verified state.\n13. Never rely on an inferred summary as the sole source for exact commands, file contents, error text, user constraints, or acceptance criteria; retain a verifiable pointer to authoritative evidence.\n14. Add bounded prefetch after proposal approval, then incremental load only when task execution reaches a dependency.\n15. Record retrieval decisions and token costs as telemetry so ranking can be evaluated against successful task outcomes.\n16. Support both ChronoStore/ChronoMemory and the free SQLite ESDB backend with equivalent residency semantics.\n\n## Suggested context packet\n\nA generated working-context packet should include:\n\n```json\n{\n  \"work_item_id\": \"...\",\n  \"objective\": \"...\",\n  \"constraints\": [],\n  \"accepted_decisions\": [],\n  \"active_requirements\": [],\n  \"checks_and_results\": [],\n  \"open_risks\": [],\n  \"next_action\": \"...\",\n  \"resident_record_ids\": [],\n  \"expandable_record_refs\": [],\n  \"token_budget\": 0,\n  \"packet_digest\": \"...\"\n}\n```\n\n## Non-goals\n\n- Do not use ESDB as an excuse to omit exact active constraints from context.\n- Do not tombstone evidence merely because it is not currently relevant.\n- Do not blindly retrieve the highest-confidence records without task relevance.\n- Do not restore all historical conversation turns on every session resume.\n- Do not let semantic similarity override explicit work-item links or authoritative sources.\n\n## Acceptance criteria\n\n- [ ] Context eviction no longer deletes or tombstones durable ESDB evidence.\n- [ ] Session resume injects a bounded task-relevant packet rather than up to 200 raw turns.\n- [ ] Full evidence remains retrievable by stable IDs after offloading.\n- [ ] Retrieval respects a token budget and records why each item was selected.\n- [ ] Active constraints, decisions, requirements, risks, and next action are pinned.\n- [ ] Duplicate summaries/source records are not simultaneously loaded without justification.\n- [ ] Both ChronoStore and SQLite backends pass equivalent residency/retrieval tests.\n- [ ] Tests cover offload, rehydrate, pinning, stale records, contradictions, backend parity, unavailable semantic embeddings, and deterministic fallback ranking.\n- [ ] No important information is considered discarded solely because it left the model context.\n\n## Agent execution notes\n\nInspect `context_orchestrator.py`, `session_store.py`, `chat_handoff.py`, ESDB stores, ChronoMemory adapters, MCP tools, requirement/test graph edges, and existing context commands. Start by fixing destructive eviction semantics. Keep durable evidence lifecycle APIs separate from ephemeral context-residency APIs.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/333/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/333/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/332",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/332/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/332/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/332/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/332",
    "id": 4904764258,
    "node_id": "I_kwDOR2RC5c8AAAABJFjDYg",
    "number": 332,
    "title": "Add predictive context-risk preflight and dynamic governance checkpoint policy",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 3,
    "created_at": "2026-07-16T18:09:31Z",
    "updated_at": "2026-07-16T19:05:21Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nReplace fixed context-percentage-only behavior with a dynamic controller that decides when to micro-checkpoint, create a semantic governance checkpoint, condense, or start a fresh Zoo task based on remaining context, task size, recent token growth, meaningful turns, material state changes, and uncertainty.\n\n## Background\n\nSpecsmith already tracks context fill and has tiered optimization, but it does not reliably answer the key preflight question: **will the next approved task fit in the remaining usable context with safe headroom?** A large task requested near 70% context must be intercepted before broad reads or edits begin.\n\n## Required work\n\n1. Separate three concepts:\n   - cheap deterministic micro-checkpoints after material state changes;\n   - semantic governance checkpoints before condensation, handoff, major mode changes, or risky operations;\n   - Zoo-native context condensation, which may consume additional model tokens.\n2. Add context telemetry contract support for:\n   - model context limit;\n   - current prompt/input tokens;\n   - reserved output tokens;\n   - safety reserve;\n   - usable remaining tokens;\n   - context pressure;\n   - tokens and meaningful turns since checkpoint;\n   - last condensation before/after token counts.\n3. Extend the proposal/preflight model with task-envelope estimation using:\n   - low/medium/high task class;\n   - expected meaningful turns;\n   - recent p90 token growth per meaningful turn;\n   - expected file-read and tool-result payload;\n   - expected verification/build output;\n   - uncertainty margin.\n4. Compute:\n\n```text\nremaining_work_capacity = context_limit - current_input - output_reserve - safety_reserve - checkpoint_reserve\n\ntask_envelope = expected_reasoning + expected_reads + expected_tool_output + expected_verification + uncertainty\n```\n\n5. Refuse to start medium/high work when the task envelope does not fit with configured post-task headroom.\n6. Implement explicit context states rather than one opaque score:\n   - green: continue and micro-checkpoint material events;\n   - yellow: semantic checkpoint at the next natural boundary;\n   - orange: checkpoint and run task-fit preflight before non-trivial work;\n   - red: checkpoint, request condensation, recalculate, and spawn a fresh task if still insufficient.\n7. Use context percentage as a pressure signal, meaningful turns as a starvation guard, and material events as semantic triggers. No single input should independently control all checkpoint behavior.\n8. Suggested defaults, configurable per project/model:\n   - yellow at 50% of usable capacity;\n   - orange at 65%;\n   - red at 78%;\n   - token-growth checkpoint trigger at 12%;\n   - checkpoint after 8-12 meaningful turns if no earlier boundary occurred;\n   - checkpoint after 5 material state changes or 3 failed attempts;\n   - 25% task-estimate uncertainty margin;\n   - minimum 20% post-task headroom;\n   - four-turn semantic-checkpoint cooldown, overridden by hard events.\n9. Define meaningful turns so approvals, empty acknowledgements, and status-only messages do not inflate the count.\n10. Define material events including accepted decisions, file mutations, test results, requirement state changes, scope changes, errors, commits, and completed subtasks.\n11. Before condensation, persist a semantic checkpoint containing objective, exact user constraints, approved proposal, decisions, evidence, files inspected/changed, checks/results, rejected approaches, unresolved risks, and exact next action.\n12. After condensation, verify the checkpoint survived, recalculate available capacity, and perform a resume-integrity check before continuing.\n13. If the task still does not fit, generate a bounded fresh-task handoff and use Zoo's task delegation/boomerang path rather than proceeding in a depleted parent context.\n14. Expose dry-run diagnostics explaining why the controller selected each action.\n\n## Zoo integration boundary\n\nSpecsmith owns policy, task estimation, checkpoint schema, handoff requirements, and post-condensation verification. Zoo Code owns accurate live token telemetry, model limits/reserves, actual condensation, child-task creation, and user-visible notifications.\n\nWhere Zoo lacks an agent-callable API, generate the strongest supported settings/rules/commands and document the upstream integration needed. Do not fabricate telemetry from percentages when exact values are available.\n\n## Non-goals\n\n- Do not checkpoint every fixed number of turns regardless of activity.\n- Do not use turn count as the primary context measurement.\n- Do not begin large repository reads before task-fit preflight.\n- Do not silently continue after failed or incomplete condensation.\n- Do not treat a Zoo file checkpoint as a semantic governance checkpoint.\n\n## Acceptance criteria\n\n- [ ] Medium/high proposals receive a task-fit decision before execution.\n- [ ] A simulated large task at approximately 70% context triggers checkpoint/condense or fresh-task handoff before broad work begins.\n- [ ] Small near-complete work is not interrupted unnecessarily at yellow pressure.\n- [ ] Micro-checkpoints require no LLM summarization call.\n- [ ] Semantic checkpoints occur at hard boundaries and are rate-limited elsewhere.\n- [ ] After condensation, capacity and checkpoint integrity are revalidated.\n- [ ] Insufficient post-condensation capacity creates a fresh bounded task rather than risking overflow.\n- [ ] Decisions are deterministic from captured telemetry/config and have actionable diagnostics.\n- [ ] Tests cover green/yellow/orange/red states, cooldown, hard-event overrides, estimation error, failed condensation, and child-task fallback.\n\n## Agent execution notes\n\nInspect `context_window.py`, `context_orchestrator.py`, proposal/preflight handling, Zoo asset generation, task delegation, session persistence, and handoff code. Reuse existing token events and context-usage records. Keep policy pure/testable and isolate Zoo-specific adapters behind an interface.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/332/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/332/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/331",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/331/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/331/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/331/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/331",
    "id": 4904756309,
    "node_id": "I_kwDOR2RC5c8AAAABJFikVQ",
    "number": 331,
    "title": "Generate a default Zoo Code Local-LLM LiteLLM profile with prompt caching enabled",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T18:08:31Z",
    "updated_at": "2026-07-16T18:22:05Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nMake Specsmith-generated Zoo Code settings immediately usable with a local LiteLLM proxy by creating a default API configuration profile named **`Local-LLM`**, pointing it to `http://127.0.0.1:4000`, enabling prompt-caching behavior by default where the selected model/provider supports it, and assigning every Specsmith/Zoo Code mode to that profile.\n\nThis complements #329. Preserve user customization during upgrades.\n\n## Current external behavior to account for\n\nZoo Code supports a dedicated LiteLLM provider, discovers models from the proxy, supports API configuration profiles, and allows profiles to be explicitly associated with modes. The exact exported/imported settings schema may change, so inspect the currently supported Zoo Code schema before implementing.\n\n## Required work\n\n1. Identify the canonical Zoo Code settings import/export schema and the supported automatic-import mechanism.\n2. Generate or merge a provider profile with:\n   - display name: `Local-LLM`;\n   - provider: dedicated LiteLLM provider, not generic OpenAI-compatible unless the current Zoo schema requires otherwise;\n   - base URL: `http://127.0.0.1:4000`;\n   - API key: omit when optional; use only Zoo's documented dummy placeholder when the schema requires a value;\n   - model: auto-discovered or clearly marked placeholder, never invent a real model ID.\n3. Enable every supported prompt-caching switch in the generated profile/global settings by default.\n4. Respect model capability discovery. Request/use prompt caching when supported, but do not falsely claim cache support or send incompatible cache controls when LiteLLM reports the model as unsupported.\n5. Associate all built-in and Specsmith-generated Zoo modes with the `Local-LLM` profile, including at least:\n   - orchestrator;\n   - architect;\n   - code;\n   - debug;\n   - ask;\n   - reviewer;\n   - any additional Specsmith custom modes present at generation time.\n6. Ensure orchestrator-created child tasks inherit the same profile through Zoo's normal profile persistence.\n7. Optimize generated prompt structure for cache reuse:\n   - keep stable governance/system content in a deterministic prefix;\n   - place volatile task state after the stable prefix where possible;\n   - avoid timestamps, current cost, random IDs, and changing diagnostics in the cacheable prefix;\n   - disable Zoo system-prompt current-time/current-cost injections by default when the supported schema permits and they are not required by governance.\n8. Extend Zoo setup/doctor/uninstall lifecycle handling:\n   - create the profile when absent;\n   - validate profile URL, provider, caching defaults, and mode mappings;\n   - preserve unrelated profiles;\n   - preserve user-edited `Local-LLM` settings unless ownership/provenance proves they are still Specsmith-managed defaults;\n   - uninstall only Specsmith-owned settings.\n9. Never serialize real API keys into repository files or generated examples.\n10. Add cross-platform tests for Linux, Windows, and macOS settings paths and automatic import behavior.\n\n## Migration behavior\n\n- New setup: create `Local-LLM` and map every Specsmith mode to it.\n- Existing Specsmith-managed default: migrate safely to the new profile.\n- Existing user-modified profile or mode mapping: preserve it and report the divergence through `doctor` rather than silently overwriting it.\n- LiteLLM unavailable: settings generation still succeeds; doctor reports the endpoint as unreachable without destroying configuration.\n\n## Prompt-cache verification\n\nAdd an integration or fixture-based test that verifies:\n\n- cache support metadata from LiteLLM is interpreted correctly;\n- generated settings enable caching controls where supported;\n- a stable repeated system/governance prefix remains byte-identical between tasks;\n- cache-read/cache-write usage fields are captured when the provider returns them;\n- unsupported models fail gracefully without malformed requests.\n\n## Non-goals\n\n- Do not bundle or start a LiteLLM server.\n- Do not choose a downstream model for the user.\n- Do not store secrets in generated JSON.\n- Do not overwrite user-created profiles.\n- Do not route codebase embeddings through LiteLLM unless separately configured and supported.\n\n## Suggested files to inspect\n\n- `src/specsmith/commands/zoo_code_assets.py`\n- Zoo settings/profile generators and fixtures\n- mode generation and mode/profile mapping code\n- Zoo setup/doctor/uninstall tests\n- documentation for Zoo Code integration\n\n## Acceptance criteria\n\n- [ ] New Specsmith Zoo setup contains a `Local-LLM` LiteLLM profile at `http://127.0.0.1:4000`.\n- [ ] All generated Specsmith/Zoo modes point to that profile.\n- [ ] Prompt caching is enabled by default where supported and is not falsely forced for unsupported models.\n- [ ] Stable governance prompt prefixes are deterministic and cache-friendly.\n- [ ] User-modified profiles and mappings are preserved.\n- [ ] No real API key is written to disk by Specsmith.\n- [ ] Doctor detects missing, unreachable, mismatched, or partially mapped configurations with actionable diagnostics.\n- [ ] Tests cover generation, migration, idempotence, user preservation, unavailable proxy, cache capability, and three operating systems.\n\n## Agent execution notes\n\nDo not hard-code field names from old Roo/Zoo settings examples. Export a current Zoo Code configuration or inspect the current schema first, then add a regression fixture representing that exact schema. Keep profile IDs deterministic only if Zoo supports stable imported IDs; otherwise resolve generated IDs and write mode mappings consistently.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/331/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/331/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/330",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/330/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/330/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/330/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/330",
    "id": 4904699786,
    "node_id": "I_kwDOR2RC5c8AAAABJFfHig",
    "number": 330,
    "title": "Audit and harden Specsmith release/bootstrap workflows across Linux, Windows, and macOS",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T18:00:40Z",
    "updated_at": "2026-07-16T18:22:00Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nPerform a comprehensive cross-platform audit of the Specsmith self-bootstrap, governance-generation, packaging, validation, and release workflows so they behave correctly and deterministically on Linux, Windows, and macOS.\n\nThis ticket supplements #321, #323, #324, #325, and #327. It should identify and eliminate platform assumptions before the new release architecture is considered complete.\n\n## Scope\n\nAudit both the existing repository and the implementations delivered by the release-bootstrap tickets. The goal is not merely to make GitHub-hosted Linux CI pass; the repository-local tools and public generic project operations must behave correctly when run by maintainers and users on all three supported desktop platforms.\n\n## Required audit areas\n\n### 1. Python and executable resolution\n\n- Never hard-code POSIX virtualenv paths such as `.venv/bin/python` or `.venv/bin/specsmith`.\n- Resolve interpreters and console scripts correctly on Windows (`Scripts/python.exe`, `Scripts/specsmith.exe`), Linux, and macOS.\n- Prefer invoking the selected interpreter as `python -m ...` when that avoids console-script path differences.\n- Use `sys.executable`, `venv.EnvBuilder`, `pathlib.Path`, and platform-aware helpers rather than shell activation.\n- Verify paths containing spaces, Unicode characters, parentheses, ampersands, and long directory names.\n\n### 2. Shell independence\n\n- Avoid relying on Bash-only syntax, `sed`, `grep`, `awk`, `cp`, `mv`, `rm`, `chmod`, `test`, process substitution, or POSIX environment-variable assignment in Python-managed workflows.\n- Use Python APIs or explicit GitHub Actions shells where shell use is unavoidable.\n- Ensure PowerShell quoting and exit-code behavior are correct on Windows.\n- Do not require users to activate a virtual environment before running repository scripts.\n- Use subprocess argument arrays with `shell=False` unless a narrowly justified shell command is required.\n\n### 3. Paths and filesystem semantics\n\n- Use `pathlib` and avoid manual `/` or `\\\\` concatenation.\n- Handle Windows drive letters, UNC paths, reserved names, path length limits, and case-insensitive filesystems.\n- Detect case-only filename collisions that succeed on Linux but fail on default Windows/macOS filesystems.\n- Verify temporary directories and cleanup when files are read-only, open, antivirus-scanned, or briefly locked.\n- Avoid assumptions that an open file can be renamed or deleted on Windows.\n- Verify atomic-write and backup behavior on NTFS, APFS, and common Linux filesystems.\n\n### 4. Permissions, symlinks, and executable bits\n\n- Do not assume symlink creation is available on Windows without developer mode or elevated permissions.\n- Ensure tests either avoid symlinks or skip with an explicit reason when unsupported.\n- Preserve or intentionally normalize executable bits in source distributions and generated scripts.\n- Verify read-only files and directory permission failures produce actionable diagnostics.\n- Ensure no workflow depends on Unix `chmod` to make Python entry points usable.\n\n### 5. Newlines, encoding, and deterministic hashing\n\n- Normalize or explicitly define newline handling for generated governance files and JSON manifests.\n- Prevent CRLF/LF conversion from causing false bootstrap drift or different artifact digests.\n- Define UTF-8 encoding explicitly for every text read/write operation.\n- Decide whether generated tracked text uses canonical LF regardless of host, and enforce it through `.gitattributes` and tests.\n- Use binary reads for artifact hashing.\n- Use canonical JSON serialization so hashes are stable across platforms.\n- Verify UTF-8 paths and document content.\n\n### 6. Git behavior\n\n- Make dirty-tree checks robust to `core.autocrlf`, file-mode differences, case folding, and ignored temporary files.\n- Ensure bootstrap status parsing does not depend on localized human-readable Git output.\n- Prefer machine-readable Git commands such as porcelain v2 and NUL-delimited path output.\n- Verify branch/ref ancestry checks work identically on all platforms and do not depend on shell glob expansion.\n- Document required Git configuration where repository invariants depend on it.\n\n### 7. Packaging and artifact reproducibility\n\n- Build sdist and wheel on each OS or prove that the canonical release build is intentionally Linux-only while the artifacts install and run on all supported platforms.\n- Verify wheel tags and contents are platform-independent where expected.\n- Compare sdist and wheel file lists across operating systems.\n- Ensure timestamps, file modes, archive path separators, and ordering do not introduce unexplained differences.\n- Test installation from the exact wheel into clean environments on Linux, Windows, and macOS.\n- Test public CLI help, migration, upgrade, sync, audit, strict validation, and generic release verification on each OS.\n\n### 8. Process, locking, and cleanup behavior\n\n- Ensure subprocesses are awaited and handles are closed before deleting temporary environments on Windows.\n- Add bounded retry/backoff only for known transient Windows file-lock cleanup cases; do not hide persistent failures.\n- Ensure interrupted runs leave diagnosable temporary state and cannot be mistaken for successful closure.\n- Verify signal/termination handling on POSIX and process termination behavior on Windows.\n\n### 9. Time and locale independence\n\n- Avoid locale-sensitive parsing of dates, numbers, Git output, and command output.\n- Use UTC and explicit ISO 8601 formats for operational evidence.\n- Ensure deterministic pre-release artifacts do not vary by local timezone or locale.\n- Test non-English locale settings where practical.\n\n### 10. Zoo Code and generated integration files\n\n- Validate generated Zoo Code JSON and command settings on all platforms.\n- Ensure the literal wildcard `\"*\"` from #329 is not shell-expanded or rewritten.\n- Verify generated command examples do not assume `/bin/bash`, Unix paths, or PowerShell unless marked platform-specific.\n- Preserve user-customized settings across operating systems and newline conventions.\n\n## CI matrix\n\nAdd or expand CI to include, at minimum:\n\n```yaml\nos:\n  - ubuntu-latest\n  - windows-latest\n  - macos-latest\npython-version:\n  - \"3.11\"\n  - \"3.12\"\n```\n\nUse the project's actual supported Python range if different. At least one Python version must run the full integration/bootstrap closure suite on every OS. Faster unit subsets may cover the broader version matrix.\n\nThe matrix should test:\n\n1. clean source checkout;\n2. package build;\n3. isolated wheel installation;\n4. generated-project smoke test;\n5. migration and full upgrade;\n6. sync/audit/strict validation;\n7. fixed-point second pass;\n8. dirty-tree detection;\n9. paths containing spaces and Unicode;\n10. platform-specific cleanup and locking cases.\n\n## Deliverables\n\n1. A written audit checklist or report committed under `docs/` or `plans/` identifying each discovered assumption and its resolution.\n2. Code changes removing platform-specific assumptions.\n3. A reusable platform/path helper module where appropriate rather than scattered `os.name` checks.\n4. A three-OS CI matrix with focused platform regression tests.\n5. Documentation for intentionally unsupported platform features, if any, with graceful failure behavior.\n\n## Non-goals\n\n- Do not require Docker, WSL, MSYS2, Git Bash, Homebrew, or a particular shell for normal operation.\n- Do not make Windows users enable symlink developer mode as a baseline requirement.\n- Do not declare cross-platform support based only on mocked path tests.\n- Do not add platform-specific public commands where one portable implementation is possible.\n- Do not weaken deterministic fixed-point checks to ignore real content drift.\n\n## Acceptance criteria\n\n- [ ] Full required CI passes on `ubuntu-latest`, `windows-latest`, and `macos-latest`.\n- [ ] No repository-local Python tool hard-codes `bin/`, `Scripts/`, `.exe`, `/tmp`, `/bin/bash`, or POSIX-only utilities without a tested platform abstraction.\n- [ ] Bootstrap and closure checking work from a repository path containing spaces and Unicode on all three operating systems.\n- [ ] Generated tracked text and JSON produce stable content independent of host newline defaults.\n- [ ] Dirty-tree detection is robust to CRLF configuration and uses machine-readable Git output.\n- [ ] Temporary virtual environments and artifacts clean up reliably, including Windows file-lock cases.\n- [ ] No required test assumes symlink support or executable-bit semantics without platform-aware handling.\n- [ ] The exact candidate wheel installs and its public generic operations pass smoke tests on all three platforms.\n- [ ] Case-collision and path-separator regressions are covered.\n- [ ] Platform-specific failures return actionable diagnostics rather than tracebacks from missing shell tools.\n- [ ] The audit report records any remaining intentional limitations.\n\n## Agent execution notes\n\nBegin with an inventory, not immediate patching. Search for shell invocations, literal path separators, `bin`, `Scripts`, `.exe`, `sed`, `rm`, `chmod`, `mktemp`, `/tmp`, `os.system`, `shell=True`, implicit text encodings, `NamedTemporaryFile`, symlink usage, and manual Git-output parsing.\n\nRun real tests on each GitHub-hosted OS. Avoid broad exception swallowing and platform branches that are not exercised in CI. Cross-reference discovered problems with the existing release tickets and update those implementations rather than creating duplicate competing code paths.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/330/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/330/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/329",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/329/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/329/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/329/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/329",
    "id": 4904693628,
    "node_id": "I_kwDOR2RC5c8AAAABJFevfA",
    "number": 329,
    "title": "Default Zoo Code auto-approved executable commands to wildcard",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T17:59:47Z",
    "updated_at": "2026-07-16T18:21:53Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nEnsure Specsmith-generated Zoo Code project configuration defaults the **allowed auto-execute command list** to exactly one wildcard entry, `\"*\"`, so generated projects permit all commands without repeated approval prompts. Users may then narrow or customize this setting according to their own security requirements and workflow.\n\n## Background\n\nSpecsmith is intended to generate a complete, immediately usable local-agent environment. A restrictive, incomplete, or platform-specific auto-execute allowlist causes unnecessary approval prompts and can prevent Zoo Code agents from completing governed workflows autonomously.\n\nThe generated default should be permissive and simple:\n\n```json\n{\n  \"allowedAutoExecuteCommands\": [\"*\"]\n}\n```\n\nThe exact property name and nesting must be confirmed against the currently supported Zoo Code configuration schema. Do not assume the illustrative key above is exact.\n\n## Required work\n\n1. Identify every Zoo Code configuration generator, template, migration, and fixture in the repository.\n2. Confirm the current Zoo Code setting name and schema for auto-approved/allowed auto-execute commands.\n3. Set the generated default to an array containing only `\"*\"`.\n4. Remove narrower built-in command entries that become redundant when wildcard access is enabled.\n5. Preserve explicit user customization during upgrades and migrations:\n   - new projects receive `[\"*\"]`;\n   - existing user-modified allowlists are not silently replaced;\n   - an existing generated/default allowlist may be migrated to `[\"*\"]` only when ownership/provenance proves it has not been user-edited.\n6. Ensure generated JSON remains valid and uses the canonical Zoo Code filename and schema currently supported by the integration.\n7. Update documentation to state clearly:\n   - the generated default permits every command;\n   - users should narrow the setting if desired;\n   - command approval is a Zoo Code execution control and is separate from Specsmith governance, validation, and ledgering.\n8. Add tests for initial generation, idempotent regeneration, user-customized preservation, migration from the previous generated default, and JSON/schema validity.\n9. Test representative commands containing spaces, arguments, quoted paths, PowerShell syntax, POSIX shell syntax, and executable paths to ensure the wildcard is emitted literally and is not expanded by the generator or shell.\n\n## Security boundary\n\nThis is an intentional permissive default requested for generated Zoo Code environments. The implementation must not falsely describe `\"*\"` as restrictive or safe for untrusted repositories.\n\nSpecsmith must preserve the user's ability to replace the wildcard with a narrower allowlist. Documentation should advise users to review this setting before running agents in untrusted codebases.\n\n## Non-goals\n\n- Do not hard-code a list of individual commands.\n- Do not add shell-specific wildcard variants.\n- Do not disable Specsmith governance, validation, or audit controls.\n- Do not overwrite an existing user-customized Zoo Code allowlist.\n- Do not modify unrelated agent integrations.\n\n## Suggested files to inspect\n\n- Zoo Code integration/generator modules under `src/specsmith/`\n- Zoo Code JSON or settings templates\n- upgrade and migration logic\n- generated project fixtures\n- documentation for editor/agent integrations\n- tests that validate generated agent configuration\n\n## Acceptance criteria\n\n- [ ] A newly generated Zoo Code configuration contains exactly one auto-execute allowlist value: `\"*\"`.\n- [ ] The value is emitted as a literal string and remains valid JSON.\n- [ ] Existing user-customized command allowlists remain unchanged during upgrade/sync.\n- [ ] The previous untouched Specsmith-generated default can migrate cleanly to `[\"*\"]`.\n- [ ] Re-running generation produces no diff.\n- [ ] Tests cover Linux, Windows, and macOS command examples without platform-specific wildcard changes.\n- [ ] Documentation explains the permissive default and how users can restrict it.\n- [ ] Relevant tests, lint, format, and mypy pass.\n\n## Agent execution notes\n\nSearch the repository before choosing the configuration path or property name. Zoo Code configuration names may have changed between versions. Implement against the current supported schema and add a regression fixture containing the exact generated JSON. Do not perform a broad replacement of all command allowlists in unrelated integrations.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/329/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/329/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/328",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/328/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/328/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/328/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/328",
    "id": 4904546841,
    "node_id": "I_kwDOR2RC5c8AAAABJFVyGQ",
    "number": 328,
    "title": "Epic: CI-only self-hosted release bootstrap and immutable publication",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 2,
    "created_at": "2026-07-16T17:39:11Z",
    "updated_at": "2026-07-16T18:20:28Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Goal\n\nMake Specsmith release itself under the governance of the exact candidate being released, while keeping all Specsmith-specific release and publishing authority out of the public CLI.\n\nThe release is complete only when the candidate reaches a self-governance fixed point before tagging and the immutable tagged artifacts are then published without source mutation.\n\n## Core invariant\n\nAt pre-release closure:\n\n```text\ncandidate package version\n= pyproject.toml version\n= docs/SPECSMITH.yml version\n= docs/SPECSMITH.yml spec_version\n= expected tag without the v prefix\n```\n\nAnd:\n\n```text\ncandidate wheel applied to candidate source = zero repository change\n```\n\n## Child tickets and order\n\n### Foundation\n\n- [ ] #318 — Remove Specsmith self-publishing operations from the public CLI\n- [ ] #319 — Separate project version from Specsmith governance schema version\n- [ ] #321 — Make governance regeneration deterministic and fixed-point safe\n\nThese can begin in parallel where their code paths do not overlap, but #319 and #321 must settle their contracts before bootstrap integration is finalized.\n\n### Candidate bootstrap\n\n- [ ] #323 — Add repository-local candidate bootstrap and closure checker\n\nRequires the version contract and deterministic generation behavior.\n\n### CI workflows\n\n- [ ] #324 — Add CI-only release preparation workflow for self-bootstrap closure\n- [ ] #325 — Harden tag-triggered release workflow to publish only closed immutable artifacts\n\n#324 prepares and optionally updates only a trusted release branch. #325 is strictly read-only with respect to source and publishes only already-closed artifacts.\n\n### Evidence and documentation\n\n- [ ] #326 — Define pre-release governance seal and post-publication receipt model\n- [ ] #327 — Rewrite release documentation and plans around CI-only self-bootstrap\n\nDocumentation should be finalized after scripts and workflows stabilize, though stale dangerous guidance may be removed earlier.\n\n## Architectural boundaries\n\n### Public installed Specsmith\n\nMay:\n\n- migrate and upgrade user projects;\n- synchronize governed state;\n- audit and validate projects;\n- verify generic release readiness.\n\nMust not:\n\n- publish Specsmith;\n- create or move Specsmith tags;\n- deploy Specsmith to PyPI;\n- promote Specsmith release environments;\n- expose a replacement private release command under another public name.\n\n### Repository-local CI and scripts\n\nMay:\n\n- build and install the exact candidate in isolation;\n- use that candidate to govern the Specsmith repository;\n- create a reviewed bootstrap commit on a trusted release branch;\n- verify zero-diff closure;\n- tag through the documented maintainer process;\n- publish immutable verified artifacts;\n- attach external post-publication evidence.\n\nMust not:\n\n- push generated changes directly to `main`;\n- mutate tagged source during publication;\n- force-move published tags;\n- treat `skip-existing` as successful repair;\n- commit post-publication evidence into an already released commit.\n\n## Program-level acceptance criteria\n\n- [ ] Normal users cannot invoke any command that releases Specsmith itself.\n- [ ] The candidate wheel, not the previously installed stable version, performs final self-governance.\n- [ ] Governance generation reaches a deterministic zero-diff second pass.\n- [ ] Release-branch writes are explicit, trusted, allowlisted, reviewable, and never target `main` directly.\n- [ ] Tag publication performs no source mutation.\n- [ ] The wheel is built from the canonical sdist, and the same files are tested and published.\n- [ ] Tags and PyPI versions are immutable.\n- [ ] Pre-release and post-publication evidence are causally separated and digest-linked.\n- [ ] Release documentation and local-agent guidance match the implemented workflow.\n- [ ] End-to-end tests include expected drift, unexpected drift, version mismatch, non-main tag, duplicate version, partial publication, and artifact tampering paths.\n\n## Instructions for local AI agents\n\n1. Read this epic and the assigned child ticket completely before editing.\n2. Inspect current implementations and tests; do not assume filenames or interfaces from the ticket are exact.\n3. Preserve the public/private boundary even when a public CLI shortcut seems easier.\n4. Add focused tests before or with behavior changes.\n5. Do not combine unrelated child tickets into one oversized PR unless unavoidable because of atomic interface changes.\n6. Reference the child issue in commits and PR descriptions.\n7. Report any discovered conflict between tickets before silently choosing a different architecture.\n8. Never publish, tag, force-push, or modify branch protection as part of implementing these tickets.\n\n## Suggested PR sequence\n\n1. #318\n2. #319\n3. #321\n4. #323\n5. #324\n6. #325\n7. #326\n8. #327\n\nSmall compatibility adjustments may be grouped, but each PR should leave the repository passing CI and should clearly identify which acceptance criteria it closes.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/328/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/328/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/327",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/327/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/327/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/327/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/327",
    "id": 4904544952,
    "node_id": "I_kwDOR2RC5c8AAAABJFVquA",
    "number": 327,
    "title": "Rewrite release documentation and plans around CI-only self-bootstrap",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T17:38:55Z",
    "updated_at": "2026-07-16T18:21:19Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nReplace the current release instructions, plans, and agent guidance with one coherent process in which Specsmith's candidate version governs its own repository to a fixed point before merge/tag, while all Specsmith-specific publishing operations remain private to repository CI.\n\nDepends on #318, #319, #321, #323, #324, #325, and #326.\n\n## Required work\n\n1. Rewrite the canonical release runbook to use this ordering:\n   1. prepare release branch and version metadata;\n   2. build candidate sdist and wheel;\n   3. install exact candidate wheel in isolation;\n   4. run candidate self-governance preparation;\n   5. commit candidate-governed changes to the release branch;\n   6. rebuild candidate and require a zero-diff second pass;\n   7. complete changelog, README, migration notes, API surface, and pre-release governance seal;\n   8. merge the fixed-point release PR to `main`;\n   9. tag the exact approved `main` commit;\n   10. run non-mutating publication workflow;\n   11. generate and attach the post-publication receipt.\n2. Remove instructions that tag or publish before README, changelog, milestone, governance, or release-seal updates are complete.\n3. Remove all guidance that permits force-moving or recreating a published tag.\n4. Remove or correct guidance that treats `skip-existing` as safe idempotence.\n5. Document the public/private boundary:\n   - public CLI governs user projects and may verify release readiness;\n   - repository-local scripts and GitHub Actions bootstrap and publish Specsmith itself.\n6. Rewrite `.agents/skills/release-pilot/SKILL.md` and any other repository-local agent instructions so a local AI agent follows the new dependency order and never invokes a public `specsmith release` command.\n7. Add a concise maintainer checklist and a failure-recovery matrix covering:\n   - candidate produces expected changes;\n   - candidate produces unexpected files;\n   - second pass is dirty;\n   - version parity failure;\n   - tag not on main;\n   - PyPI version already exists;\n   - GitHub Release succeeds but PyPI fails;\n   - published digest mismatch.\n8. Clarify which artifacts are committed before tagging, which are workflow artifacts, and which are GitHub Release attachments.\n9. Update historical/reusable release-plan templates so future plans cannot place documentation or governance changes after publication.\n10. Add documentation tests or repository assertions for forbidden patterns where practical.\n\n## Files to inspect\n\n- `docs/site/releasing.md`\n- `.agents/skills/release-pilot/SKILL.md`\n- any `.agents/skills/release*/` content\n- `plans/*release-plan*.md`\n- README contributor/release sections\n- changelog process documentation\n- workflow comments and repository templates\n\n## Forbidden guidance\n\nThe finished repository must not instruct maintainers or agents to:\n\n- use a public `specsmith release` command;\n- tag before self-bootstrap closure;\n- modify release source after tagging;\n- move a published tag;\n- rely on `skip-existing` to repair or validate a release;\n- publish artifacts built from a source tree modified inside the tag workflow;\n- add the post-publication receipt back into the released commit.\n\n## Acceptance criteria\n\n- [ ] One canonical runbook describes the complete fixed-point release process.\n- [ ] Repository-local agent instructions match the workflow implementation exactly.\n- [ ] No active release plan puts README, changelog, governance, or sealing work after tagging/publication.\n- [ ] Published tags and versions are documented as immutable.\n- [ ] Failure recovery always uses a new commit and, after publication, a new version.\n- [ ] Public CLI and private CI responsibilities are clearly separated.\n- [ ] Seal versus receipt causality is clearly explained.\n- [ ] Repository search finds no stale active instructions for the old process.\n- [ ] Documentation lint/link checks pass.\n\n## Agent execution notes\n\nTreat implementation as the source of truth: inspect the completed scripts and workflows before finalizing examples. Do not document commands that do not exist. Mark historical release plans as historical or update reusable templates without falsifying prior release history.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/327/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/327/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/326",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/326/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/326/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/326/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/326",
    "id": 4904543200,
    "node_id": "I_kwDOR2RC5c8AAAABJFVj4A",
    "number": 326,
    "title": "Define pre-release governance seal and post-publication receipt model",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T17:38:38Z",
    "updated_at": "2026-07-16T18:21:12Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nImplement a causally correct release evidence model that distinguishes evidence available before publication from evidence created only after GitHub Release and PyPI publication.\n\nDepends on #323 and #325.\n\n## Background\n\nA release cannot contain proof of its own future publication. Specsmith therefore needs two linked evidence objects:\n\n1. **Pre-release governance seal**: generated before tagging and included in the tagged source/artifact closure.\n2. **Post-publication receipt**: generated after publication and attached externally to the GitHub Release or transparency/provenance channel.\n\nThe receipt must reference the immutable pre-release seal and published artifact digests without modifying the released source tree or moving the tag.\n\n## Required work\n\n1. Define a versioned JSON schema for the pre-release governance seal containing at least:\n   - schema version;\n   - package version;\n   - source commit;\n   - expected tag;\n   - project `version` and `spec_version`;\n   - governed file manifest and digests;\n   - bootstrap closure result;\n   - sdist and wheel SHA-256 values when available in the final pre-publication build;\n   - relevant test/gate identifiers;\n   - creation mechanism and deterministic metadata.\n2. Define a versioned JSON schema for the post-publication receipt containing at least:\n   - reference/digest of the pre-release seal;\n   - immutable tag and source commit;\n   - GitHub Release identity;\n   - PyPI project/version identity;\n   - published artifact filenames and SHA-256 values;\n   - publication workflow run identity;\n   - publication timestamp as external operational evidence;\n   - verification status and failure details.\n3. Decide and document canonical locations:\n   - seal inside the source tree or release artifact set before tagging;\n   - receipt attached to GitHub Release and optionally uploaded as workflow attestation/provenance, but not committed back into the released tag.\n4. Implement schema validation and digest-link verification.\n5. Integrate seal generation with candidate bootstrap/closure preparation.\n6. Integrate receipt generation only after publication succeeds.\n7. Verify downloaded PyPI artifacts against the exact pre-publish artifact digests before marking the receipt successful.\n8. Include failure behavior for partial publication, artifact mismatch, missing PyPI files, or GitHub Release creation failure.\n9. Document how the receipt is carried into the next operational ledger or subsequent release without pretending it was part of the prior immutable source release.\n10. Add tests for schema validation, digest linking, tampering, partial publication, and mismatched remote artifacts.\n\n## Non-goals\n\n- Do not commit post-publication receipts into the already tagged release commit.\n- Do not move or recreate tags to add evidence.\n- Do not claim the pre-release seal proves successful publication.\n- Do not expose Specsmith publishing controls through the public CLI.\n\n## Acceptance criteria\n\n- [ ] Seal and receipt schemas are documented and versioned.\n- [ ] The pre-release seal is generated before tagging and included in release closure.\n- [ ] The post-publication receipt cryptographically references the seal and exact published artifacts.\n- [ ] Published PyPI artifacts are independently fetched or inspected and digest-verified before receipt success.\n- [ ] Partial or mismatched publication produces a failed/incomplete receipt, not false success.\n- [ ] No source mutation or tag movement occurs after publication.\n- [ ] Tests demonstrate tamper detection and causal separation between seal and receipt.\n- [ ] Release documentation explains which claims each evidence object can and cannot support.\n\n## Agent execution notes\n\nKeep operational timestamps out of deterministic source-generation inputs unless they are explicitly external receipt fields. Use canonical JSON serialization before hashing. Treat filenames, versions, commit SHAs, and artifact digests as exact identities rather than descriptive metadata.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/326/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/326/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/325",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/325/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/325/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/325/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/325",
    "id": 4904541406,
    "node_id": "I_kwDOR2RC5c8AAAABJFVc3g",
    "number": 325,
    "title": "Harden tag-triggered release workflow to publish only closed immutable artifacts",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T17:38:21Z",
    "updated_at": "2026-07-16T18:21:05Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nRefactor the tag-triggered release workflow so it is strictly non-mutating, verifies that the tagged commit already passed self-bootstrap closure, and publishes exactly the artifacts built and verified from that immutable commit.\n\nDepends on #323 and #324.\n\n## Background\n\nThe current release workflow triggers on `v*` tags, rebuilds and publishes artifacts, mutates `pyproject.toml` during packaging with `sed`, and has a tag/main condition that does not actually prove the tag belongs to `main`. Published PyPI artifacts cannot be corrected by force-moving a tag, especially when publishing uses `skip-existing`.\n\n## Required work\n\n1. Remove all source-tree mutation from the tag workflow, including dependency-line deletion or metadata rewriting before build.\n2. Fail the release if package metadata is not publishable exactly as committed.\n3. Verify the tag format and parse its semantic version.\n4. Verify all version anchors match the tag:\n   - `pyproject.toml`;\n   - installed package metadata;\n   - `docs/SPECSMITH.yml` `version`;\n   - `docs/SPECSMITH.yml` `spec_version`;\n   - any intentionally retained compatibility anchors.\n5. Verify the tagged commit is reachable from the protected `main` branch and, preferably, equals the current expected main release commit according to the documented release model.\n6. Run the repository-local bootstrap tool in read-only `check` mode against the tag checkout.\n7. Build one canonical sdist, build the wheel from that sdist, and preserve those exact files through test, attestation, GitHub Release, and PyPI jobs.\n8. Test the installed wheel in a fresh environment, including package import, CLI help, public command surface, strict validation, and a minimal governed-project smoke test.\n9. Generate SHA-256 digests and a provenance manifest tying tag, commit, sdist, wheel, and bootstrap manifest together.\n10. Publish to GitHub Releases and PyPI only after every verification gate succeeds.\n11. Replace `skip-existing` behavior with explicit preflight checks and fail safely when the target version already exists. Never treat a conflicting existing artifact as success.\n12. Use trusted publishing/OIDC and least-privilege job permissions.\n13. Add workflow concurrency keyed by tag/version to prevent duplicate racing publications.\n14. Ensure reruns reuse or deterministically recreate the same verified artifacts and cannot publish a different wheel for the same version.\n\n## Immutable release policy\n\n- Tags are immutable after publication.\n- A published version is immutable.\n- Never force-move a release tag.\n- Never overwrite or silently skip a conflicting PyPI version.\n- Any source correction requires a new version.\n\n## Non-goals\n\n- Do not generate or commit governance changes in this workflow.\n- Do not update README, changelog, ledgers, or milestones after tagging.\n- Do not expose publishing operations in the public Specsmith CLI.\n- Do not build GitHub Release and PyPI artifacts through separate source mutation paths.\n\n## Acceptance criteria\n\n- [ ] The workflow performs no tracked source mutation.\n- [ ] The workflow fails if committed metadata cannot be packaged as-is.\n- [ ] Tag/version/project/governance parity is enforced.\n- [ ] The tagged commit is proven reachable from protected `main`.\n- [ ] Candidate self-bootstrap `check` passes with zero diff.\n- [ ] The wheel is built from the canonical sdist.\n- [ ] The exact same artifact files are used for testing, GitHub Release, and PyPI publishing.\n- [ ] Existing conflicting PyPI versions cause a hard failure, not a skipped-success release.\n- [ ] Digests and provenance metadata are attached to the GitHub Release.\n- [ ] Tests or workflow fixtures cover malformed tags, version mismatch, non-main tags, dirty bootstrap state, package mutation attempts, and duplicate versions.\n- [ ] Documentation explicitly forbids moving published tags.\n\n## Suggested files to inspect\n\n- `.github/workflows/release.yml`\n- release verification scripts\n- package build configuration\n- `docs/site/releasing.md`\n- `.agents/skills/release-pilot/SKILL.md`\n- any scripts that currently retag, promote, or use `skip-existing`\n\n## Agent execution notes\n\nTreat the tagged commit and built artifacts as immutable identities. Prefer explicit artifact upload/download between jobs over rebuilding in each job. Verify checksums after every transfer. Do not make the workflow appear successful when publication was skipped or when an existing version differs.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/325/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/325/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/324",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/324/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/324/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/324/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/324",
    "id": 4904536896,
    "node_id": "I_kwDOR2RC5c8AAAABJFVLQA",
    "number": 324,
    "title": "Add CI-only release preparation workflow for self-bootstrap closure",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T17:37:41Z",
    "updated_at": "2026-07-16T18:20:59Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nAdd a manually triggered GitHub Actions workflow that prepares a Specsmith release branch using the repository-local bootstrap tooling from #323, updates only the release branch when governance changes are required, and proves a clean second-pass fixed point before merge.\n\nDepends on #318, #319, #321, and #323.\n\n## Workflow contract\n\nCreate a workflow such as `.github/workflows/prepare-release.yml` with `workflow_dispatch` inputs for at least:\n\n- target semantic version;\n- release branch/ref;\n- write mode (`check` by default, explicitly enabled `prepare` when a branch update is desired).\n\n## Required work\n\n1. Check out the exact requested release branch with full history.\n2. Refuse to operate on `main`, `develop`, detached tags, pull-request merge refs, or an untrusted fork.\n3. Validate branch naming and version metadata before executing any write-capable step.\n4. Run the repository-local bootstrap tool from #323 in `prepare` mode.\n5. If no governed changes are required, continue directly to the closure check.\n6. If changes are required:\n   - permit only an explicit allowlist of generated/governance/version files;\n   - display and archive the patch;\n   - commit with a deterministic message such as `chore(release): close Specsmith vX.Y.Z bootstrap`;\n   - push only to the same release branch;\n   - never force-push.\n7. Protect against workflow loops by distinguishing bot-generated preparation commits and by exiting cleanly when no diff exists.\n8. Rebuild the candidate from the resulting commit and run the bootstrap tool in `check` mode.\n9. Require the second pass to have:\n   - zero tracked diff;\n   - zero untracked files outside declared temporary paths;\n   - matching source, sdist, wheel, project, and governance versions.\n10. Upload the bootstrap manifest, artifact digests, and generated patch as workflow artifacts.\n11. Use least-privilege permissions. Default to read-only contents; grant write access only to the branch-update job.\n12. Add concurrency protection keyed by release branch/version so two preparation runs cannot race.\n13. Make the closure-check job reusable or callable from pull-request CI for release branches.\n\n## Security and safety constraints\n\n- Do not expose this as a public Specsmith CLI command.\n- Do not publish packages or create GitHub Releases.\n- Do not create, delete, or move tags.\n- Do not push to `main` or `develop`.\n- Do not execute write mode for pull requests from forks.\n- Do not commit arbitrary files generated by compromised or unexpected tooling.\n- Do not use `git add -A`; stage only the approved file allowlist after verifying the complete status output.\n\n## Acceptance criteria\n\n- [ ] Workflow is manually dispatchable with validated version and release branch inputs.\n- [ ] Default invocation is read-only/check-only.\n- [ ] Write mode can update only the originating trusted release branch.\n- [ ] Main, develop, tags, merge refs, and forks are rejected for write mode.\n- [ ] Generated changes are constrained to an explicit allowlist and archived for review.\n- [ ] A candidate-generated commit triggers or performs a fresh rebuild and clean second-pass closure check.\n- [ ] Concurrent preparation runs for the same release are serialized or cancelled safely.\n- [ ] Workflow permissions follow least privilege.\n- [ ] Tests or workflow-validation fixtures cover no-change, expected-change, unexpected-file, invalid-ref, and dirty-second-pass cases.\n- [ ] Documentation explains how a maintainer invokes and reviews the workflow.\n\n## Agent execution notes\n\nImplement branch/ref validation before any step receives write credentials. Keep write and verification jobs separate. Use pinned action versions or immutable SHAs according to repository policy. Preserve complete status and manifest output for diagnosis. The workflow must remain safe if the candidate produces an unexpected file.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/324/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/324/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/323",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/323/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/323/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/323/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/323",
    "id": 4904527528,
    "node_id": "I_kwDOR2RC5c8AAAABJFUmqA",
    "number": 323,
    "title": "Add repository-local candidate bootstrap and closure checker",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T17:36:22Z",
    "updated_at": "2026-07-16T18:20:52Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nImplement CI-only repository tooling that builds a Specsmith candidate from source, installs the exact candidate wheel in isolation, applies that candidate to the Specsmith repository, and verifies self-governance closure.\n\nDepends on #319 and #321. This tooling must not be packaged as a public `specsmith` CLI command.\n\n## Required work\n\nCreate repository-local tooling, for example:\n\n- `scripts/release_bootstrap.py`\n- supporting modules under `scripts/` or `.github/scripts/`\n\nProvide two explicit modes:\n\n1. `prepare`: may regenerate candidate-owned governance state and produce a reviewable repository diff.\n2. `check`: read-only; fails if the same candidate would change the repository.\n\nThe implementation must:\n\n1. Validate the requested semantic version and expected release branch/ref.\n2. Build an sdist from the checked-out source.\n3. Build the wheel from that sdist, not independently from a different tree.\n4. Create an isolated virtual environment and install only the exact candidate wheel plus required build/test dependencies.\n5. Invoke the candidate executable from that environment, never a globally installed Specsmith.\n6. Set narrowly scoped CI variables needed to bypass pipx enforcement and disable network/automatic update behavior.\n7. Run the canonical self-governance sequence using public generic operations, such as migration, full upgrade, sync, audit, strict validation, and release-readiness verification.\n8. Enforce the release invariant:\n   - candidate package version == `pyproject.toml` version;\n   - candidate package version == project `version`;\n   - candidate package version == project `spec_version` after preparation;\n   - expected tag text is `v<version>`.\n9. Emit a machine-readable manifest containing source commit, sdist digest, wheel digest, candidate version, governed file list, and check result.\n10. In `check` mode, leave the worktree byte-for-byte unchanged and fail on tracked or untracked drift.\n11. Add focused unit and integration tests, including deliberate version mismatch and generated drift failures.\n\n## Non-goals\n\n- Do not publish to PyPI or GitHub Releases.\n- Do not create, move, or delete tags.\n- Do not push commits.\n- Do not register a public `specsmith release` command.\n- Do not rely on the previously installed stable Specsmith to generate final candidate governance.\n\n## Acceptance criteria\n\n- [ ] Tooling lives outside the packaged public CLI surface.\n- [ ] The candidate wheel is derived from the candidate sdist and installed in an isolated environment.\n- [ ] `prepare` produces only expected, reviewable candidate-governed changes.\n- [ ] `check` is read-only and fails on any resulting diff or untracked file.\n- [ ] Version and artifact identity invariants are enforced with actionable diagnostics.\n- [ ] A JSON manifest records commit and artifact SHA-256 values.\n- [ ] Tests prove the globally installed Specsmith is not used.\n- [ ] Tests cover clean closure, migration-required state, version mismatch, and dirty second pass.\n- [ ] Lint, format, mypy, and relevant test suites pass.\n\n## Agent execution notes\n\nUse subprocess argument arrays, checked return codes, explicit paths, and temporary directories. Avoid shell interpolation. Preserve logs needed for CI diagnosis but do not leak credentials. The same implementation must back both prepare and check modes to prevent validation drift.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/323/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/323/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/321",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/321/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/321/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/321/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/321",
    "id": 4904421153,
    "node_id": "I_kwDOR2RC5c8AAAABJFOHIQ",
    "number": 321,
    "title": "Make governance regeneration deterministic and fixed-point safe",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T17:21:19Z",
    "updated_at": "2026-07-16T18:20:47Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nMake candidate-driven governance regeneration deterministic and idempotent so CI can prove that a Specsmith release candidate governs its own repository to a clean fixed point.\n\nDepends on #319 for the final `version` / `spec_version` contract.\n\n## Background\n\nThe self-bootstrap release gate will run a candidate wheel against the Specsmith repository, commit any candidate-generated governance changes, rebuild the wheel, and run the same process again. The second pass must produce zero tracked changes.\n\nCurrent upgrade behavior can overwrite managed files and create timestamped adjacent `.bak` files even when rendered content is unchanged. Template context may also include runtime-dependent values such as the current date. Those behaviors prevent a reliable fixed-point assertion.\n\n## Required work\n\n1. Audit every candidate self-governance operation that can write tracked or untracked files, including:\n   - project migration;\n   - `upgrade --full`;\n   - governance template rendering;\n   - `sync` output;\n   - API-surface generation;\n   - migration state and backup creation;\n   - ledger or ESDB side effects.\n2. Change safe overwrite behavior so identical content is a no-op before any backup is created.\n3. Store backups under an ignored repository-local path such as `.specsmith/backups/governance/`, rather than adjacent to tracked governance documents.\n4. Introduce a CI/bootstrap mode or equivalent internal controls that suppress nondeterministic operational side effects while preserving the canonical generated source state.\n5. Remove or inject deterministic values for template inputs that vary by wall-clock time. Candidate bootstrap output must be reproducible for the same source commit and declared release metadata.\n6. Ensure managed generation has an explicit, reviewable ownership list. The bootstrap must not overwrite user-owned files such as README, architecture, requirements source, tests source, or ledger content unless a separate canonical generator explicitly owns them.\n7. Add a fixed-point test that:\n   - copies a representative Specsmith project fixture;\n   - runs the migration/upgrade/sync generation pass;\n   - records the resulting tree;\n   - runs the same pass again;\n   - verifies byte-for-byte equality and no new files.\n8. Add tests for identical safe writes, changed safe writes, backup placement, deterministic dates/metadata, and cleanup behavior.\n\n## Non-goals\n\n- Do not add release publishing functionality to the public CLI.\n- Do not weaken corruption-resistant atomic writes.\n- Do not suppress legitimate content differences.\n- Do not make the bootstrap ignore tracked drift; it must fail or produce a reviewable patch.\n\n## Suggested files to inspect\n\n- `src/specsmith/safe_write.py`\n- `src/specsmith/upgrader.py`\n- `src/specsmith/updater.py`\n- `src/specsmith/sync.py`\n- migration runner and migration implementations\n- governance templates under `src/specsmith/templates/`\n- ledger/ESDB write paths invoked during migration\n- `.gitignore`\n- related upgrade, migration, and safe-write tests\n\n## Acceptance criteria\n\n- [ ] Writing identical content creates no backup and leaves file metadata/content stable enough for a clean Git check.\n- [ ] Changed managed content is written atomically and backups are placed only in an ignored backup directory.\n- [ ] Running the canonical self-governance generation pass twice with the same inputs produces no differences on the second pass.\n- [ ] No timestamped or session-dependent tracked files are created by bootstrap/check mode.\n- [ ] User-owned files remain protected.\n- [ ] A focused fixed-point integration test covers migration, full upgrade, and sync.\n- [ ] Existing non-CI safety guarantees remain intact.\n- [ ] Relevant tests, lint, formatting, and mypy pass.\n\n## Agent execution notes\n\nStart by instrumenting or listing every file created or modified by a full migration/upgrade/sync pass. Do not patch only `safe_overwrite`; prove the whole operation reaches a fixed point. Keep deterministic bootstrap controls narrowly scoped so ordinary interactive usage retains appropriate backup and audit behavior.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/321/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/321/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/319",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/319/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/319/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/319/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/319",
    "id": 4904411254,
    "node_id": "I_kwDOR2RC5c8AAAABJFNgdg",
    "number": 319,
    "title": "Separate project version from Specsmith governance schema version",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T17:19:58Z",
    "updated_at": "2026-07-16T18:20:41Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nMake Specsmith's own repository a correctly versioned Specsmith project by representing both:\n\n- the package/project release version; and\n- the Specsmith governance schema/tool version that last migrated the repository.\n\nThe self-bootstrap workflow must be able to detect when the Specsmith repository requires migration by the candidate version.\n\n## Background\n\n`docs/SPECSMITH.yml` currently records `version`, while project migration/version checks read `spec_version`. As a result, Specsmith may fail to recognize its own repository as needing a governance migration. For Specsmith itself, the two values will normally match at release closure, but they represent different concepts and must remain explicit.\n\n## Required work\n\n1. Define and document the metadata contract:\n   - `version`: Specsmith package/project release version.\n   - `spec_version`: governance schema/tool version that last generated or migrated the project.\n2. Update `docs/SPECSMITH.yml` to contain both fields.\n3. Update config normalization so legacy self-project files containing only `version` can be interpreted/migrated safely.\n4. Ensure migration checks, `needs_migration`, auto-update checks, and project version reporting use `spec_version`, not `version`.\n5. Ensure release/version consistency checks validate the correct relationships:\n   - package metadata equals project `version`;\n   - candidate governance version equals `spec_version` at release closure.\n6. Remove stale duplicated or conflicting version anchors where possible; retain only explicit compatibility fallbacks that tests enforce.\n7. Add tests for:\n   - current two-field format;\n   - legacy `version`-only self-project format;\n   - `spec_version` behind installed candidate;\n   - project `spec_version` ahead of installed version;\n   - version mismatch diagnostics.\n\n## Non-goals\n\n- Do not merge `version` and `spec_version` into one ambiguous field.\n- Do not add Specsmith publishing behavior.\n- Do not silently rewrite arbitrary user project versions.\n- Do not weaken backward-migration rejection.\n\n## Suggested files to inspect\n\n- `docs/SPECSMITH.yml`\n- `src/specsmith/_config_schema.py`\n- `src/specsmith/config.py`\n- `src/specsmith/updater.py`\n- `src/specsmith/upgrader.py`\n- release/version validation scripts\n- version parity tests\n\n## Acceptance criteria\n\n- [ ] `docs/SPECSMITH.yml` has explicit `version` and `spec_version` fields.\n- [ ] Specsmith's migration detection recognizes when its own `spec_version` is behind the candidate package version.\n- [ ] Legacy self-project metadata can be normalized without data loss.\n- [ ] Backward migration remains a hard failure with actionable remediation.\n- [ ] Release parity checks distinguish package version from governance schema version.\n- [ ] Tests cover current, legacy, forward-migration, and backward-migration cases.\n- [ ] No public CLI behavior gains private self-release semantics.\n- [ ] Full relevant test suite, lint, format, and mypy pass.\n\n## Agent execution notes\n\nTrace every reader and writer of `version` and `spec_version` before changing schema behavior. Avoid a broad string replacement. Preserve compatibility for normal user projects, and include focused migration fixtures that demonstrate the intended self-hosted repository behavior.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/319/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/319/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/318",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/318/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/318/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/318/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/318",
    "id": 4904409732,
    "node_id": "I_kwDOR2RC5c8AAAABJFNahA",
    "number": 318,
    "title": "Remove Specsmith self-publishing operations from the public CLI",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 1,
    "created_at": "2026-07-16T17:19:45Z",
    "updated_at": "2026-07-16T18:20:36Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nRemove any user-facing CLI capability that can create, tag, deploy, promote, or otherwise publish **Specsmith itself**. The installed `specsmith` package is used by external projects and must not expose Layer1Labs' private release orchestration.\n\nThis ticket establishes the product boundary before the CI-only bootstrap work is added.\n\n## Background\n\nThe current public CLI surface includes a top-level `release` command, and bundled release skills/documentation advertise operations such as creating GitHub releases, deploying to PyPI, managing tags, and promoting environments. Those operations must not be available to normal Specsmith users.\n\nGeneric project release **verification** is still valid public functionality. The distinction is:\n\n- Public: govern and verify whether a user's project is release-ready.\n- Private repository CI: bootstrap, tag, and publish Specsmith itself.\n\n## Required work\n\n1. Locate every registration path for the public `specsmith release` command.\n2. Remove the command from the Click command tree and API surface.\n3. Remove or rewrite packaged skills that instruct users to run commands such as:\n   - `specsmith release create`\n   - `specsmith release deploy`\n   - tag creation/modification\n   - release promotion\n4. Keep `specsmith verify-release` public, provided it remains a generic read-only project verification command.\n5. Update public command documentation, help snapshots, API-surface fixtures, tests, examples, generated integrations, and changelog entries.\n6. Search the entire repository for stale `specsmith release` examples and classify each occurrence:\n   - remove if it refers to private Specsmith publishing;\n   - retain only if it clearly refers to a generic governance concept and is not executable publishing functionality.\n\n## Non-goals\n\n- Do not add a replacement public self-release command.\n- Do not move private release logic into another packaged command.\n- Do not remove generic user-project release readiness checks.\n- Do not implement CI bootstrap orchestration in this ticket.\n\n## Suggested files to inspect\n\n- `src/specsmith/cli.py`\n- any release command modules under `src/specsmith/`\n- `.agents/skills/release/SKILL.md`\n- `.agents/skills/release-pilot/SKILL.md`\n- `docs/site/commands.md`\n- `docs/site/releasing.md`\n- `tests/fixtures/api_surface.json`\n- command registration tests and release-related tests\n\n## Acceptance criteria\n\n- [ ] `specsmith --help` does not list a top-level `release` command.\n- [ ] `specsmith release ...` fails as an unknown command.\n- [ ] `specsmith verify-release` remains available and documented as a generic validation operation.\n- [ ] The generated API-surface fixture no longer contains `release`.\n- [ ] No packaged skill tells a normal user how to publish Specsmith, modify Specsmith tags, or deploy Specsmith to PyPI.\n- [ ] Repository-wide search finds no stale executable examples for the removed command.\n- [ ] Existing public behavior unrelated to self-publishing remains compatible.\n- [ ] Unit tests, CLI tests, API-surface tests, lint, formatting, and mypy pass.\n\n## Agent execution notes\n\nBefore editing, run repository search for `@main.command`, `release`, `release create`, `release deploy`, and `specsmith release`. Trace registration rather than deleting only documentation. Update generated fixtures using the repository's canonical generation command, then verify the resulting diff is limited to this scope.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/318/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/318/timeline",
    "performed_via_github_app": {
      "id": 1144995,
      "client_id": "Iv23liVemv8A9if9v0F2",
      "slug": "chatgpt-codex-connector",
      "node_id": "A_kwHOAOQ6Gs4AEXij",
      "owner": {
        "login": "openai",
        "id": 14957082,
        "node_id": "MDEyOk9yZ2FuaXphdGlvbjE0OTU3MDgy",
        "avatar_url": "https://avatars.githubusercontent.com/u/14957082?v=4",
        "gravatar_id": "",
        "url": "https://api.github.com/users/openai",
        "html_url": "https://github.com/openai",
        "followers_url": "https://api.github.com/users/openai/followers",
        "following_url": "https://api.github.com/users/openai/following{/other_user}",
        "gists_url": "https://api.github.com/users/openai/gists{/gist_id}",
        "starred_url": "https://api.github.com/users/openai/starred{/owner}{/repo}",
        "subscriptions_url": "https://api.github.com/users/openai/subscriptions",
        "organizations_url": "https://api.github.com/users/openai/orgs",
        "repos_url": "https://api.github.com/users/openai/repos",
        "events_url": "https://api.github.com/users/openai/events{/privacy}",
        "received_events_url": "https://api.github.com/users/openai/received_events",
        "type": "Organization",
        "user_view_type": "public",
        "site_admin": false
      },
      "name": "ChatGPT Codex Connector",
      "description": "Bring ChatGPT and Codex to your GitHub repositories.",
      "external_url": "https://www.chatgpt.com",
      "html_url": "https://github.com/apps/chatgpt-codex-connector",
      "created_at": "2025-02-14T01:37:05Z",
      "updated_at": "2026-04-20T16:37:15Z",
      "permissions": {
        "actions": "write",
        "checks": "read",
        "contents": "write",
        "emails": "read",
        "issues": "write",
        "metadata": "read",
        "pull_requests": "write",
        "statuses": "read",
        "workflows": "write"
      },
      "events": [
        "check_run",
        "check_suite",
        "commit_comment",
        "issues",
        "issue_comment",
        "pull_request",
        "pull_request_review",
        "pull_request_review_comment",
        "pull_request_review_thread",
        "repository",
        "status",
        "sub_issues"
      ]
    },
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/316",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/316/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/316/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/316/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/316",
    "id": 4904381428,
    "node_id": "I_kwDOR2RC5c8AAAABJFLr9A",
    "number": 316,
    "title": "Prevent stale or transient paths from polluting the MCP project registry",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 0,
    "created_at": "2026-07-16T17:15:32Z",
    "updated_at": "2026-07-16T19:04:38Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nMake the persistent MCP project registry contain only intentional, valid project roots. Prevent pytest temporary directories, deleted worktrees, duplicate path spellings, and transient invocation directories from becoming durable registry entries.\n\nThis issue is unique. It is related to #339 configuration ownership and #338 replica identity, but it is not duplicated by them. It follows the verification contract in #337.\n\n## Current defect\n\n`register_project()` currently resolves a path and appends it to `mcp-projects.json` without validating that it is a real Specsmith project, distinguishing explicit user registration from test/server startup, or pruning paths that no longer exist. Tests and temporary environments can therefore leave stale absolute paths in the user's registry.\n\n## Required behavior\n\n- Only explicit registration actions may persist a project by default.\n- Starting an MCP server for a path must not automatically persist that path unless explicitly requested.\n- Validate that a registered path exists, is a directory, and contains a recognized Specsmith project marker or an explicit `--allow-uninitialized` override.\n- Canonicalize paths consistently, including Windows case/drive handling and symlink policy.\n- Deduplicate equivalent paths.\n- Add bounded registry pruning for missing, inaccessible, temporary, or invalid entries.\n- Never prune a currently valid project merely because it is temporarily offline without reporting the reason and policy.\n- Use atomic writes and recover safely from malformed registry files.\n- Keep test state isolated through `SPECSMITH_HOME` fixtures; tests must never touch the real user registry.\n- Provide inspectable commands such as `specsmith mcp projects list`, `register`, `unregister`, and `prune --dry-run` or equivalent existing command names.\n- Return structured JSON status for agent/CI use.\n\n## Named tests and binary pass/fail conditions\n\n### MCPREG-001 — Explicit registration only\n\n**Pass:** MCP server startup with a project directory does not add a persistent entry unless the user invokes registration or an explicit persist option.\n\n**Fail:** ordinary startup mutates the registry.\n\n### MCPREG-002 — Pytest isolation\n\n**Pass:** test runs using temporary project roots leave the real/default registry byte-for-byte unchanged.\n\n**Fail:** any pytest temp directory appears in the user's registry.\n\n### MCPREG-003 — Project validation\n\n**Pass:** valid Specsmith roots register; missing files, regular files, and uninitialized directories are rejected unless an explicit allowed override is used.\n\n**Fail:** arbitrary temporary directories persist silently.\n\n### MCPREG-004 — Canonical deduplication\n\n**Pass:** relative, absolute, symlink-equivalent, case-equivalent Windows, and trailing-separator forms produce one canonical entry under the documented policy.\n\n**Fail:** equivalent paths create duplicates.\n\n### MCPREG-005 — Stale pruning\n\n**Pass:** dry-run reports stale entries without mutation; confirmed prune removes only entries meeting the configured stale policy and reports every removal.\n\n**Fail:** pruning is silent, overly broad, or cannot preview changes.\n\n### MCPREG-006 — Offline/inaccessible path safety\n\n**Pass:** temporarily inaccessible paths are classified distinctly from confirmed deleted paths and are preserved unless policy explicitly authorizes removal.\n\n**Fail:** transient access failure destroys registration state.\n\n### MCPREG-007 — Atomic writes and recovery\n\n**Pass:** interrupted writes preserve either the prior or complete new registry; malformed JSON produces diagnostics and a recoverable backup path.\n\n**Fail:** the registry becomes partially written or is silently reset.\n\n### MCPREG-008 — Concurrent registration\n\n**Pass:** two concurrent register/unregister operations do not lose unrelated entries and detect write conflicts.\n\n**Fail:** last-writer-wins drops valid projects.\n\n### MCPREG-009 — Cross-platform paths\n\n**Pass:** Linux, macOS, and Windows path fixtures produce stable canonical entries and equivalent list/unregister behavior.\n\n**Fail:** a project cannot be removed using an equivalent path representation.\n\n### MCPREG-010 — Structured status\n\n**Pass:** list/register/prune operations expose machine-readable path, state, provenance, and reason fields without parsing prose.\n\n**Fail:** agents cannot distinguish valid, stale, inaccessible, and rejected entries.\n\n## Acceptance criteria\n\n- [ ] Transient/test paths cannot silently persist.\n- [ ] Registration is explicit, validated, canonical, atomic, and explainable.\n- [ ] Existing valid user registrations migrate without loss.\n- [ ] Pruning is safe and previewable.\n- [ ] MCPREG-001 through MCPREG-010 pass with #337 machine-readable evidence.\n\n## Non-goals\n\n- Do not use the registry as a source of personal identity.\n- Do not store per-project secrets in the registry.\n- Do not automatically delete inaccessible remote-volume projects without an explicit policy.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/316/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/316/timeline",
    "performed_via_github_app": null,
    "state_reason": null,
    "pinned_comment": null
  },
  {
    "url": "https://api.github.com/repos/layer1labs/specsmith/issues/313",
    "repository_url": "https://api.github.com/repos/layer1labs/specsmith",
    "labels_url": "https://api.github.com/repos/layer1labs/specsmith/issues/313/labels{/name}",
    "comments_url": "https://api.github.com/repos/layer1labs/specsmith/issues/313/comments",
    "events_url": "https://api.github.com/repos/layer1labs/specsmith/issues/313/events",
    "html_url": "https://github.com/layer1labs/specsmith/issues/313",
    "id": 4903824449,
    "node_id": "I_kwDOR2RC5c8AAAABJEpsQQ",
    "number": 313,
    "title": "Resolve cross-platform execution shells and prefer PowerShell 7 on Windows",
    "user": {
      "login": "tbitcs",
      "id": 98970594,
      "node_id": "U_kgDOBeYr4g",
      "avatar_url": "https://avatars.githubusercontent.com/u/98970594?v=4",
      "gravatar_id": "",
      "url": "https://api.github.com/users/tbitcs",
      "html_url": "https://github.com/tbitcs",
      "followers_url": "https://api.github.com/users/tbitcs/followers",
      "following_url": "https://api.github.com/users/tbitcs/following{/other_user}",
      "gists_url": "https://api.github.com/users/tbitcs/gists{/gist_id}",
      "starred_url": "https://api.github.com/users/tbitcs/starred{/owner}{/repo}",
      "subscriptions_url": "https://api.github.com/users/tbitcs/subscriptions",
      "organizations_url": "https://api.github.com/users/tbitcs/orgs",
      "repos_url": "https://api.github.com/users/tbitcs/repos",
      "events_url": "https://api.github.com/users/tbitcs/events{/privacy}",
      "received_events_url": "https://api.github.com/users/tbitcs/received_events",
      "type": "User",
      "user_view_type": "public",
      "site_admin": false
    },
    "labels": [

    ],
    "state": "open",
    "locked": false,
    "assignees": [

    ],
    "milestone": null,
    "comments": 0,
    "created_at": "2026-07-16T15:59:49Z",
    "updated_at": "2026-07-16T19:03:44Z",
    "closed_at": null,
    "assignee": null,
    "author_association": "CONTRIBUTOR",
    "issue_field_values": [

    ],
    "type": null,
    "active_lock_reason": null,
    "sub_issues_summary": {
      "total": 0,
      "completed": 0,
      "percent_completed": 0
    },
    "issue_dependencies_summary": {
      "blocked_by": 0,
      "total_blocked_by": 0,
      "blocking": 0,
      "total_blocking": 0
    },
    "body": "## Objective\n\nReplace the hard-coded Windows `cmd.exe` execution path in `src/specsmith/executor.py` with a deterministic, configurable, cross-platform shell resolver. Prefer PowerShell 7 (`pwsh.exe`) when available, provide safe fallbacks, and preserve timeout, PID tracking, output capture, exit-code propagation, and abort behavior.\n\nThis is the canonical ticket for the duplicate concern in #314. It is related to, but not duplicated by, the broader release portability audit in #330 and the Zoo MCP portability ticket #317. It follows the verification contract in #337.\n\n## Current defect\n\n`run_tracked()` currently selects `[\"cmd\", \"/c\", command]` for every Windows command and `[\"bash\", \"-c\", command]` for every POSIX command.\n\nThis ignores PowerShell 7 even when installed, assumes Bash exists on every POSIX environment, does not expose the selected shell or its provenance, and makes shell-specific syntax unpredictable.\n\n## Required behavior\n\nImplement one central shell-resolution function used by all governed string-command execution.\n\nResolution order:\n\n1. explicit CLI/call-site shell override;\n2. resolved Specsmith configuration from #339;\n3. `SPECSMITH_SHELL` environment override;\n4. Windows: `pwsh.exe`, then `powershell.exe`, then `cmd.exe`;\n5. POSIX: configured shell, then `bash`, then `sh`;\n6. fail with an actionable diagnostic if no supported shell exists.\n\nThe resolver must return a structured result containing executable path, shell family, argv prefix, source/provenance, and detected version where available.\n\nUse argument-vector execution directly whenever the caller supplies argv. Shell parsing must be used only for intentionally shell-authored command strings.\n\nPowerShell invocation must use non-interactive, non-profile behavior and a command form that preserves exit codes. Do not silently rewrite shell syntax between shell families.\n\nRecord the selected shell family/path in execution evidence without leaking command secrets.\n\n## Compatibility and safety\n\n- Preserve existing timeout, PID-file, stdout/stderr capture, and abort semantics.\n- Keep Windows process-tree termination behavior.\n- Handle paths containing spaces and non-ASCII characters.\n- Reject an explicit shell override that does not exist instead of silently falling back.\n- Document shell-specific command portability expectations.\n- Do not add unsafe interpolation or `shell=True`.\n\n## Named tests and binary pass/fail conditions\n\n### EXEC-SHELL-001 — Windows prefers PowerShell 7\n\n**Pass:** with `pwsh.exe`, `powershell.exe`, and `cmd.exe` discoverable, the resolver selects `pwsh.exe` and reports the automatic-detection source.\n\n**Fail:** `cmd.exe` or Windows PowerShell is selected first.\n\n### EXEC-SHELL-002 — Windows fallback chain\n\n**Pass:** fixtures with successively missing executables select `powershell.exe`, then `cmd.exe`; no-shell fixture fails with an actionable error.\n\n**Fail:** selection is nondeterministic or an unavailable executable is launched.\n\n### EXEC-SHELL-003 — Explicit override precedence\n\n**Pass:** CLI/config/environment overrides follow the documented precedence and the selected source is reported.\n\n**Fail:** an automatic default overrides an explicit valid choice.\n\n### EXEC-SHELL-004 — Invalid override fails closed\n\n**Pass:** a nonexistent explicit executable produces a nonzero result and does not fall back silently.\n\n**Fail:** another shell runs without telling the user.\n\n### EXEC-SHELL-005 — POSIX fallback\n\n**Pass:** Linux/macOS fixtures select configured shell, `bash`, or `sh` in order and work when Bash is absent.\n\n**Fail:** execution requires Bash unconditionally.\n\n### EXEC-SHELL-006 — Exit-code propagation\n\n**Pass:** each supported shell returns the original command's nonzero exit code through `ExecResult`.\n\n**Fail:** wrapper success masks command failure.\n\n### EXEC-SHELL-007 — Timeout and process-tree abort\n\n**Pass:** timed-out commands and child processes are terminated, PID state is removed, and `timed_out=true` is preserved for all shell families.\n\n**Fail:** child processes survive or PID files remain stale.\n\n### EXEC-SHELL-008 — Paths and quoting\n\n**Pass:** commands and working directories containing spaces, Unicode, quotes, and metacharacters execute according to the selected shell's documented syntax.\n\n**Fail:** arguments are split, corrupted, or interpreted by a different shell.\n\n### EXEC-SHELL-009 — Argv bypasses shell\n\n**Pass:** argv-based execution launches directly without shell parsing and preserves every argument exactly.\n\n**Fail:** argv is joined into a command string or interpreted by a shell.\n\n### EXEC-SHELL-010 — Evidence and secret safety\n\n**Pass:** execution evidence records shell family/path/provenance but redacts configured secret-bearing command fields.\n\n**Fail:** shell choice is untraceable or credentials appear in logs/manifests.\n\n### EXEC-SHELL-011 — Cross-platform CI matrix\n\n**Pass:** focused tests run on Windows, Linux, and macOS with equivalent result semantics.\n\n**Fail:** behavior is covered only through platform mocks when a hosted runner is available.\n\n## Acceptance criteria\n\n- [ ] No hard-coded unconditional `cmd /c` or `bash -c` selection remains.\n- [ ] PowerShell 7 is the default Windows shell when available.\n- [ ] Resolution is centralized, configurable, explainable, and deterministic.\n- [ ] Direct argv execution is available and preferred where possible.\n- [ ] Existing executor lifecycle behavior remains intact.\n- [ ] EXEC-SHELL-001 through EXEC-SHELL-011 pass with #337 machine-readable evidence.\n\n## Non-goals\n\n- Do not translate arbitrary Bash commands into PowerShell or vice versa.\n- Do not require PowerShell 7 on systems where it is absent.\n- Do not fold Zoo MCP executable-path configuration into this ticket; that remains #317/#341.",
    "closed_by": null,
    "reactions": {
      "url": "https://api.github.com/repos/layer1labs/specsmith/issues/313/reactions",
      "total_count": 0,
      "+1": 0,
      "-1": 0,
      "laugh": 0,
      "hooray": 0,
      "confused": 0,
      "heart": 0,
      "rocket": 0,
      "eyes": 0
    },
    "timeline_url": "https://api.github.com/repos/layer1labs/specsmith/issues/313/timeline",
    "performed_via_github_app": null,
    "state_reason": null,
    "pinned_comment": null
  }
]