troven 0.1.0__tar.gz

troven-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.py[cod]
+*$py.class
+.pytest_cache/
+*.egg-info/
+dist/
+build/
+.venv/

troven-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 rdarder
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

troven-0.1.0/PKG-INFO

@@ -0,0 +1,75 @@
+Metadata-Version: 2.5
+Name: troven
+Version: 0.1.0
+Summary: Git-native CLI for tracking change intents and speculative development
+Author: rdarder
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Troven
+
+> **Troven** is a Git-native CLI for tracking **change intents** and speculative development in software projects.
+
+It maintains both **positive knowledge** (accepted changes) and **rejection knowledge** (dead ends, discarded hypotheses, benchmark findings) in structured, conflict-free records.
+
+---
+
+## The Four Verbs
+
+| Command | Action |
+| :--- | :--- |
+| `troven create <name> [--from <base>]` | Start a new troven worktree and initialize its record. |
+| `troven open [<id>]` | Open an active or rejected troven in a worktree. |
+| `troven accept [<id>] [--into <branch>]` | Fast-forward merge changes into target branch, recording outcome. |
+| `troven reject [<id>]` | Archive branch to `refs/archive/troven/<id>`, recording rejection verdict. |
+
+### Exploration & Visibility
+
+| Command | Action |
+| :--- | :--- |
+| `troven list [--status <state>]` | Hierarchical DAG view of all active, accepted, and rejected trovens. |
+| `troven show [<id>]` | Print full markdown record for a troven. |
+
+---
+
+## Installation
+
+```bash
+# Editable install via pip or uv:
+pip install -e .
+# or
+uv tool install --editable .
+```
+
+---
+
+## Record Format (`.troven/<id>.md`)
+
+Every troven is backed by a conflict-free markdown file:
+
+```markdown
+---
+version: 1
+id: 2026-08-30-fast-lexer-simd
+parent: 2026-08-30-fast-lexer
+forked_from: null
+status: active
+base_branch: master
+base_commit: 8f3c1a2d
+target_ref: null
+created_at: "2026-08-30T14:22:00-03:00"
+resolved_at: null
+---
+
+## Summary
+
+<!-- REQUIRED before accept or reject. Agent or user fills this in. -->
+
+---
+
+## Details
+
+<!-- Optional append-only log. -->
+```

troven-0.1.0/README.md

@@ -0,0 +1,65 @@
+# Troven
+
+> **Troven** is a Git-native CLI for tracking **change intents** and speculative development in software projects.
+
+It maintains both **positive knowledge** (accepted changes) and **rejection knowledge** (dead ends, discarded hypotheses, benchmark findings) in structured, conflict-free records.
+
+---
+
+## The Four Verbs
+
+| Command | Action |
+| :--- | :--- |
+| `troven create <name> [--from <base>]` | Start a new troven worktree and initialize its record. |
+| `troven open [<id>]` | Open an active or rejected troven in a worktree. |
+| `troven accept [<id>] [--into <branch>]` | Fast-forward merge changes into target branch, recording outcome. |
+| `troven reject [<id>]` | Archive branch to `refs/archive/troven/<id>`, recording rejection verdict. |
+
+### Exploration & Visibility
+
+| Command | Action |
+| :--- | :--- |
+| `troven list [--status <state>]` | Hierarchical DAG view of all active, accepted, and rejected trovens. |
+| `troven show [<id>]` | Print full markdown record for a troven. |
+
+---
+
+## Installation
+
+```bash
+# Editable install via pip or uv:
+pip install -e .
+# or
+uv tool install --editable .
+```
+
+---
+
+## Record Format (`.troven/<id>.md`)
+
+Every troven is backed by a conflict-free markdown file:
+
+```markdown
+---
+version: 1
+id: 2026-08-30-fast-lexer-simd
+parent: 2026-08-30-fast-lexer
+forked_from: null
+status: active
+base_branch: master
+base_commit: 8f3c1a2d
+target_ref: null
+created_at: "2026-08-30T14:22:00-03:00"
+resolved_at: null
+---
+
+## Summary
+
+<!-- REQUIRED before accept or reject. Agent or user fills this in. -->
+
+---
+
+## Details
+
+<!-- Optional append-only log. -->
+```

troven-0.1.0/pyproject.toml

@@ -0,0 +1,21 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "troven"
+version = "0.1.0"
+description = "Git-native CLI for tracking change intents and speculative development"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [
+    { name = "rdarder" }
+]
+dependencies = []
+
+[project.scripts]
+troven = "troven.cli:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/troven"]

troven-0.1.0/skills/troven/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: troven
+description: >-
+  Manages speculative changes, experiments, and feature spikes using the Troven workflow.
+  Use when operating inside a troven worktree, accepting changes into master/target branch,
+  rejecting discarded changes with negative knowledge logs, opening past trovens, or inspecting change DAGs.
+license: MIT
+---
+
+# Troven Workflow Guide
+
+**Troven** tracks change intents and speculative software changes. It preserves both **positive knowledge** (accepted changes) and **rejection knowledge** (dead ends, discarded hypotheses, benchmark findings) in structured, conflict-free records.
+
+The four core verbs are:
+- `troven create <name> [--from <base>]` (CLI only, outside agent)
+- `troven open [<id>]`
+- `troven accept [<id>] [--into <branch>]`
+- `troven reject [<id>]`
+
+---
+
+## 1. Operating Inside an Active Troven Worktree
+
+When an agent session runs inside a troven worktree:
+
+1. **Check `README.md` First**:
+   - Consult `README.md` for project environment setup, dependencies, build, and test/validation procedures.
+   - Run required setup and verification commands per project documentation.
+
+2. **Strict Workspace Confinement**:
+   - All code modifications, tests, and Git commits must stay confined to the troven worktree directory.
+   - Never modify or checkout `master` or other branches directly.
+
+3. **Track Outcome in `.troven/<id>.md`**:
+   - The troven's record file lives at `.troven/<id>.md`.
+   - While working, optionally append notes, dismissed alternatives, or benchmark logs to the `## Details` section.
+
+---
+
+## 2. Transitioning: Accepting a Troven (`troven accept`)
+
+When the user asks to accept, merge, or ship the troven (e.g. *"accept this"*, *"ship it"*, *"looks good, merge it"*):
+
+1. **Validate**:
+   - Run the project's test suite per `README.md` to ensure all tests pass.
+2. **Synthesize Summary**:
+   - Write a concise 1-paragraph summary into the `## Summary` section of `.troven/<id>.md`:
+     - What was attempted
+     - What was implemented
+     - Verification/validation results
+3. **Execute Accept**:
+   - Run `troven accept` in the shell.
+   - Troven will fast-forward merge the changes into the target branch (rebasing if necessary), squash the `.troven/<id>.md` record update, and clean up the worktree and branch.
+
+---
+
+## 3. Transitioning: Rejecting a Troven (`troven reject`)
+
+When an approach fails, performance degrades, or the user decides to abandon the troven (e.g. *"reject this"*, *"discard"*, *"this didn't work"*):
+
+1. **Synthesize Rejection Knowledge** (Crucial Step):
+   - Write a clear, informative summary into `## Summary` of `.troven/<id>.md`:
+     - What hypothesis was tested
+     - What was found (e.g., benchmark numbers, architectural hurdles, regressions)
+     - The explicit reason why the approach was rejected
+2. **Record Follow-up Details (Optional)**:
+   - Add notes to `## Details` regarding alternatives that might work, or where useful prototype snippets live.
+3. **Execute Reject**:
+   - Run `troven reject` in the shell.
+   - Troven will archive the branch to `refs/archive/troven/<id>`, commit the rejection record to the base branch, and clean up the worktree and branch.
+
+---
+
+## 4. Opening and Inspecting Past Trovens
+
+- **`troven list`**: View the full hierarchical tree of active, accepted, and rejected trovens.
+- **`troven show <id>`**: Read the complete markdown record for any past troven.
+- **`troven open <id>`**: Mount an active or rejected troven in a worktree to inspect code or run benchmarks.
+- **`troven create <name> --from <id>`**: Fork a new active troven starting from an existing or rejected troven.

troven-0.1.0/src/troven/__init__.py

@@ -0,0 +1,3 @@
+"""Troven - Git-native CLI for tracking change intents and speculative development."""
+
+__version__ = "0.1.0"

troven-0.1.0/src/troven/__main__.py

@@ -0,0 +1,7 @@
+"""Entry point for python -m troven."""
+
+import sys
+from troven.cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

troven-0.1.0/src/troven/cli.py

@@ -0,0 +1,144 @@
+"""CLI argument parsing and command dispatch for Troven."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from troven import __version__
+from troven.commands.accept import execute_accept
+from troven.commands.create import execute_create
+from troven.commands.list_cmd import execute_list
+from troven.commands.open_cmd import execute_open
+from troven.commands.reject import execute_reject
+from troven.commands.show import execute_show
+from troven.errors import TrovenError
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="troven",
+        description="Git-native CLI for tracking change intents and speculative development.",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+
+    subparsers = parser.add_subparsers(dest="subcommand", title="subcommands", required=True)
+
+    # create
+    create_p = subparsers.add_parser(
+        "create",
+        help="Create a new troven worktree and initialize its change intent record.",
+    )
+    create_p.add_argument("name", help="Dash-separated name for the troven (e.g. 'fast-lexer-simd')")
+    create_p.add_argument("--from", dest="from_ref", help="Base branch, commit, or parent troven ID")
+    create_p.add_argument("--repo", dest="repo_url", help="Git repository URL to clone first")
+    create_p.add_argument("-f", "--force", action="store_true", help="Skip confirmation prompts")
+    create_p.add_argument("--no-exec", action="store_true", help="Initialize worktree without launching agent")
+    create_p.add_argument("command", nargs="*", help="Custom command to run in worktree (after --)")
+
+    # open
+    open_p = subparsers.add_parser(
+        "open",
+        help="Open an existing active or rejected troven in a worktree.",
+    )
+    open_p.add_argument("id", nargs="?", help="Troven ID (defaults to current branch/worktree)")
+    open_p.add_argument("--no-exec", action="store_true", help="Mount worktree without launching agent")
+    open_p.add_argument("command", nargs="*", help="Custom command to run in worktree (after --)")
+
+    # accept
+    accept_p = subparsers.add_parser(
+        "accept",
+        help="Incorporate an active troven's changes into the target branch.",
+    )
+    accept_p.add_argument("id", nargs="?", help="Troven ID (defaults to current worktree/branch)")
+    accept_p.add_argument("--into", dest="into_branch", help="Target branch (defaults to base_branch)")
+    accept_p.add_argument("-f", "--force", action="store_true", help="Bypass foreign repo confirmation")
+
+    # reject
+    reject_p = subparsers.add_parser(
+        "reject",
+        help="Close an active troven without merging; preserve rejection knowledge in archive ref.",
+    )
+    reject_p.add_argument("id", nargs="?", help="Troven ID (defaults to current worktree/branch)")
+
+    # list
+    list_p = subparsers.add_parser(
+        "list",
+        help="List all trovens in a hierarchical tree view.",
+    )
+    list_p.add_argument("--status", choices=["active", "accepted", "rejected"], help="Filter by status")
+
+    # show
+    show_p = subparsers.add_parser(
+        "show",
+        help="Print the full markdown record for a troven.",
+    )
+    show_p.add_argument("id", nargs="?", help="Troven ID (defaults to current worktree/branch)")
+
+    # install-skill
+    install_skill_p = subparsers.add_parser(
+        "install-skill",
+        help="Install the troven agent skill to ~/.agents/skills/troven and ~/.gemini/config/skills/troven.",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.subcommand == "create":
+            cmd = args.command
+            if cmd and cmd[0] == "--":
+                cmd = cmd[1:]
+            execute_create(
+                name=args.name,
+                from_ref=args.from_ref,
+                repo_url=args.repo_url,
+                force=args.force,
+                command=cmd,
+                no_exec=args.no_exec,
+            )
+        elif args.subcommand == "open":
+            cmd = args.command
+            if cmd and cmd[0] == "--":
+                cmd = cmd[1:]
+            execute_open(
+                troven_id=args.id,
+                command=cmd,
+                no_exec=args.no_exec,
+            )
+        elif args.subcommand == "accept":
+            execute_accept(
+                troven_id=args.id,
+                into_branch=args.into_branch,
+                force=args.force,
+            )
+        elif args.subcommand == "reject":
+            execute_reject(
+                troven_id=args.id,
+            )
+        elif args.subcommand == "list":
+            execute_list(
+                status_filter=args.status,
+            )
+        elif args.subcommand == "show":
+            execute_show(
+                troven_id=args.id,
+            )
+        elif args.subcommand == "install-skill":
+            from troven.commands.install_skill import execute_install_skill
+            execute_install_skill()
+        return 0
+    except TrovenError as err:
+        print(f"\033[31mError:\033[0m {err}", file=sys.stderr)
+        return 1
+    except KeyboardInterrupt:
+        print("\nAborted.", file=sys.stderr)
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

troven-0.1.0/src/troven/commands/__init__.py

@@ -0,0 +1 @@
+"""Troven command implementations."""

troven-0.1.0/src/troven/commands/accept.py

@@ -0,0 +1,134 @@
+"""Implementation of 'troven accept' subcommand."""
+
+from __future__ import annotations
+
+from datetime import datetime, timezone
+from pathlib import Path
+import sys
+
+from troven import git
+from troven.commands.open_cmd import detect_current_troven_id
+from troven.errors import (
+    InvalidStateError,
+    MergeConflictError,
+    RebaseConflictError,
+    TrovenError,
+    TrovenNotFoundError,
+)
+from troven.state import (
+    get_troven_file,
+    load_troven,
+    save_troven,
+    validate_summary_non_empty,
+)
+
+
+def execute_accept(
+    troven_id: str | None = None,
+    into_branch: str | None = None,
+    force: bool = False,
+) -> None:
+    """Incorporate active troven changes into the target branch."""
+    repo_root = git.get_main_repo_root()
+
+    if not troven_id:
+        detected = detect_current_troven_id(repo_root)
+        if not detected:
+            raise TrovenError(
+                "Troven ID required when not run from inside a troven worktree.",
+                remediation="Specify a troven ID: 'troven accept <id>' or run inside the worktree.",
+            )
+        troven_id = detected
+
+    clean_id = troven_id.removeprefix("troven/")
+    branch_name = f"troven/{clean_id}"
+
+    if not git.branch_exists(branch_name, cwd=repo_root):
+        raise TrovenNotFoundError(
+            f"Active branch '{branch_name}' not found.",
+            remediation=f"Check 'troven list' to view available trovens.",
+        )
+
+    # Locate worktree
+    worktree_dir = git.find_worktree_for_branch(branch_name, cwd=repo_root)
+
+    # Load and validate troven record from worktree if present, else base repo
+    if worktree_dir and worktree_dir.exists() and get_troven_file(worktree_dir, clean_id).exists():
+        md_source_dir = worktree_dir
+    else:
+        md_source_dir = repo_root
+    record = load_troven(md_source_dir, clean_id)
+    md_path = get_troven_file(md_source_dir, clean_id)
+
+    if record.status != "active":
+        raise InvalidStateError(
+            f"Troven '{clean_id}' is in state '{record.status}', not 'active'.",
+            remediation="Only active trovens can be accepted.",
+        )
+
+    # Gate-check summary
+    validate_summary_non_empty(record, md_path)
+
+    target_branch = into_branch or record.base_branch or "master"
+
+    # Foreign repo warning check
+    if not (repo_root / ".troven").exists() and not force and sys.stdin.isatty():
+        ans = input(
+            "This repository does not appear to use troven in its target branch.\n"
+            f"Accepting will add .troven/ to '{target_branch}'. Confirm? [y/N]: "
+        ).strip()
+        if ans.lower() not in ("y", "yes"):
+            print("Aborted.")
+            sys.exit(0)
+
+    # Ensure any pending .troven record changes inside worktree are committed to the branch
+    if worktree_dir and worktree_dir.exists():
+        wt_md = get_troven_file(worktree_dir, clean_id)
+        if wt_md.exists():
+            git.commit_files([wt_md], f"troven: record summary for {clean_id}", cwd=worktree_dir)
+
+    # Switch base repo to target branch
+    git.checkout_branch(target_branch, cwd=repo_root)
+
+    # Attempt fast-forward merge
+    print(f"Fast-forward merging '{branch_name}' into '{target_branch}'...")
+    if not git.merge_ff_only(branch_name, cwd=repo_root):
+        print(f"Branches have diverged. Attempting rebase inside worktree...")
+        if not worktree_dir or not worktree_dir.exists():
+            raise MergeConflictError(
+                f"Fast-forward merge failed and worktree for '{branch_name}' is not found locally.",
+                remediation=f"Open the troven with 'troven open {clean_id}', rebase onto '{target_branch}', and try again.",
+            )
+
+        if not git.rebase(target_branch, cwd=worktree_dir):
+            git.rebase_abort(cwd=worktree_dir)
+            raise RebaseConflictError(
+                f"Rebase of '{branch_name}' onto '{target_branch}' encountered conflicts.",
+                remediation=f"Resolve conflicts manually inside '{worktree_dir}' and run 'troven accept {clean_id}'.",
+            )
+
+        # After rebase, retry fast-forward merge
+        if not git.merge_ff_only(branch_name, cwd=repo_root):
+            raise MergeConflictError(
+                f"Fast-forward merge still failed after rebase.",
+                remediation=f"Inspect branch '{branch_name}' in '{worktree_dir}'.",
+            )
+
+    # Update troven record status to accepted
+    record.status = "accepted"
+    record.resolved_at = datetime.now(timezone.utc).astimezone().isoformat(timespec="seconds")
+    saved_md = save_troven(repo_root, record)
+
+    # Squash update of .troven record to target branch
+    git.commit_files([saved_md], f"troven: accept {clean_id}", cwd=repo_root)
+
+    # Cleanup worktree and branch
+    if worktree_dir and worktree_dir.exists():
+        print(f"Removing worktree at {worktree_dir}...")
+        git.remove_worktree(worktree_dir, force=True, cwd=repo_root)
+
+    print(f"Deleting branch '{branch_name}'...")
+    git.delete_branch(branch_name, force=True, cwd=repo_root)
+    git.prune_worktrees(cwd=repo_root)
+
+    print(f"\n\033[32m[Success]\033[0m Troven '{clean_id}' accepted into '{target_branch}'.")