vyuha 0.1.0__tar.gz

vyuha-0.1.0/.claude/commands/implement.md

@@ -0,0 +1,81 @@
+# /implement — Start a Ticket
+
+Claims a ticket and creates its git worktree.
+
+**Usage:** `/implement TICK-NNN`
+
+```bash
+vyuha start $ARGUMENTS
+```
+
+After the worktree is created (`worktrees/<ticket-id>/`), edit files **there** — never edit the main checkout's copies. Reset CWD between tickets.
+
+Run tests from within the worktree (use relative paths to your test runner). When tests are green:
+
+```bash
+vyuha complete $ARGUMENTS
+```
+
+Then merge:
+
+```bash
+vyuha merge $ARGUMENTS
+```
+
+---
+
+## Writing agent notes
+
+After completing a ticket (tests green, `vyuha complete` called), write a short notes block for each file in `ticket.touches` so future agents inherit constraints discovered during this implementation.
+
+### Note file location
+
+For each file path in `ticket.touches`, the note file is:
+
+```
+.vyuha/notes/<flat_path>.md
+```
+
+where `<flat_path>` is the file path with every `/` replaced by `_`.
+
+Examples:
+- `src/vyuha/core.py` → `.vyuha/notes/src_vyuha_core.py.md`
+- `.claude/commands/implement.md` → `.vyuha/notes/.claude_commands_implement.md.md`
+
+### How to write notes
+
+**Append** a tagged block to the note file (create the file if it doesn't exist):
+
+```markdown
+## [TICK-NNN]
+- <factual constraint 1>
+- <factual constraint 2>
+```
+
+Rules:
+- Write **factual constraints only**: "X fails if Y", "always do Z before W", "field X must be non-null or parser crashes"
+- **Max 5 bullets per ticket per file** — be terse
+- If nothing non-obvious was learned about a file, **write nothing** (omit the block entirely for that file)
+- Do not repeat what the ticket spec already says; write only what surprised you or would trip up the next agent
+
+### Escalation rule
+
+| Type of learning | Where it goes |
+|---|---|
+| File-specific or ephemeral (implementation detail, edge case in one file) | `.vyuha/notes/<flat_path>.md` only |
+| Project-wide convention discovered during implementation | Append a proposal to `.vyuha/pending-globals.md` (also gitignored) with the ticket ID and rationale |
+
+**Never write to `CLAUDE.md` autonomously.** Only a human may promote a proposal from `pending-globals.md` into `CLAUDE.md`.
+
+### Example
+
+After implementing TICK-042 that touched `src/vyuha/concurrency.py` and `.vyuha.yml`:
+
+`.vyuha/notes/src_vyuha_concurrency.py.md`:
+```markdown
+## [TICK-042]
+- flock path must be on the same filesystem as the repo root or acquire silently fails
+- always release lock in a trap, not in normal control flow
+```
+
+`.vyuha/notes/.vyuha.yml.md` — omitted (nothing non-obvious learned about the YAML schema)

vyuha-0.1.0/.claude/commands/integrate.md

@@ -0,0 +1,23 @@
+# /integrate — Merge and Promote
+
+Integration ritual for code-complete tickets.
+
+```bash
+# 1. Review what's code_complete
+vyuha board
+
+# 2. For each code_complete ticket:
+vyuha review TICK-NNN
+vyuha merge TICK-NNN
+
+# 3. Check pipeline status
+vyuha pipeline-status
+
+# 4. Promote to an environment (manual envs only):
+vyuha promote <env-name>
+
+# 5. If feature-flagged, enable in the target environment:
+vyuha flag enable <flag-name> --env <env-name>
+```
+
+For auto-trigger environments (hook-driven), the pipeline handles promotion automatically.

vyuha-0.1.0/.claude/commands/next-ticket.md

@@ -0,0 +1,7 @@
+# /next-ticket — Recommend Next Ticket
+
+Runs `vyuha next` to recommend the highest-priority unblocked ticket(s), respecting `depends_on` and the `touches` lock so parallel agents don't collide.
+
+```bash
+vyuha next
+```

vyuha-0.1.0/.claude/commands/orchestrate.md

@@ -0,0 +1,392 @@
+# /orchestrate — Clear the Board
+
+Runs the ticket-processing loop. Pulls touch-disjoint batches from `vyuha next`,
+takes each ticket as far as policy allows **in parallel up to a resource cap**,
+and repeats until no eligible tickets remain.
+
+**Usage:** `/orchestrate [--max N] [--dry-run] [--human-review final|per_ticket|none]`
+
+This skill coordinates the run. It never edits code itself — it dispatches per-ticket
+subagents and runs the CLI verbs between them.
+
+---
+
+## 0. Preflight — single-orchestrator guard
+
+Only one orchestrator may run per repo. A second one would double the live agent count
+and blow past the rate-limit / GPU cap (each orchestrator enforces `max_parallel`
+independently, with no cross-process coordination).
+
+The check-and-set, stale-lock reclaim, and atomicity (`flock`) live in `concurrency.py`;
+the skill calls the verb with its own shell PID (`$$`):
+
+```bash
+vyuha orchestrator-lock acquire --pid $$ || exit 1   # refuses if a live orchestrator holds it
+trap 'vyuha orchestrator-lock release --pid $$' EXIT  # release on exit/error/interrupt
+```
+
+> A stale lock (holder process dead) is reclaimed automatically. To inspect without
+> claiming, run `vyuha orchestrator-lock status`; to override a wedged lock, add `--force`.
+
+---
+
+## 1. Resolve the concurrency cap
+
+The cap is the **resource gate**; `vyuha next` is the **correctness gate**. The
+effective batch size each round is `min(eligible_disjoint_tickets, max_parallel)`.
+
+Resolve `max_parallel` in this order (first hit wins):
+
+1. `--max N` flag on this invocation.
+2. `executors.<executor>.max_parallel` in `.vyuha.yml` for the active `executor`.
+3. Top-level `max_parallel` in `.vyuha.yml`.
+4. Built-in default: **2**.
+
+```yaml
+# .vyuha.yml
+executor: claude
+max_parallel: 2            # global default
+executors:
+  claude: { max_parallel: 3 }   # cloud → bounded by API rate limits
+  local:  { max_parallel: 1 }   # single-GPU → effectively sequential
+```
+
+Reminder on semantics: the executor value is an **override**, not additive.
+`local: 1` runs one ticket at a time on purpose; raise it only when your local server
+batches (e.g. vLLM continuous batching).
+
+---
+
+## 2. The loop
+
+```
+repeat:
+  batch_json = `vyuha --json next`
+  candidates = [batch_json.next] + batch_json.peers   # already touch-disjoint
+  if candidates is empty: break                        # no eligible tickets remain
+  batch = candidates[:max_parallel]                    # apply resource cap
+  run every ticket in `batch` IN PARALLEL (one subagent each)
+  collect finished tickets; as a slot frees, the loop's next round refills it
+```
+
+Use a **worker-pool / semaphore**, not blind fan-out: keep at most `max_parallel`
+subagents live at once and pull the next candidate as each finishes. Do **not** spawn the
+whole board and wait. `vyuha next` only ever returns a disjoint set, so re-querying
+each round naturally respects the `touches` lock as tickets enter/leave flight.
+
+### Prior agent notes injection
+
+Before dispatching the subagent for a ticket, collect any notes left by previous agents
+for files this ticket will touch.
+
+**Step 1 — collect notes**
+
+For each path in `ticket.touches`, derive the flat filename:
+- Replace every `/` in the path with `_`
+- Read `.vyuha/notes/<flat_path>.md` if it exists; silently skip if missing
+
+**Step 2 — build the injection**
+
+Concatenate all non-empty note file contents. If the result is non-empty, prepend it to
+the agent prompt as a dedicated section:
+
+```
+## Prior agent notes
+
+<concatenated note file contents>
+```
+
+If no note files exist (or all are empty), **omit the section entirely** — do not add a
+heading with no content.
+
+**Step 3 — dispatch**
+
+Pass the (possibly augmented) prompt to the subagent. The injection is executor-agnostic:
+it works the same for `claude-subagent`, `claude-process`, `aider`, and any other
+executor in the dispatch table below.
+
+---
+
+### Per-ticket executor dispatch
+
+The executor for each ticket is resolved per-ticket:
+
+```python
+executor = ticket.get('executor') or cfg['executor']
+```
+
+| `executor` value | Dispatch method |
+|---|---|
+| `claude-subagent` (or `claude`) | Task tool (in-process subagent) |
+| `claude-process` | `claude -p <prompt>` subprocess in the ticket's worktree |
+| `aider`, `codex`, `<cmd>` | configured agent as a process in the ticket's worktree |
+
+```
+vyuha start  TICK-NNN     # claim + worktree (TOCTOU-safe; see below)
+  → dispatch per executor (see table above) with prior notes prepended
+vyuha complete TICK-NNN   # drift check vs touches + status → code_complete
+  → review gate: see §3 below
+vyuha merge  TICK-NNN     # ff merge → main, worktree removed
+  → analytics log: see §2a below (MANDATORY — do not skip)
+```
+
+### §2a. Analytics logging (mandatory after every merge)
+
+Immediately after `vyuha merge TICK-NNN` succeeds, call `vyuha log` with the token
+counts from the task-notification `<usage>` blocks. Do not skip this step — missing
+entries cannot be backfilled accurately later.
+
+```bash
+vyuha log TICK-NNN \
+  --tokens <total_subagent_tokens>    # sum of implementer + all reviewer usage blocks
+  --summary-tokens <summary_tok>      # rough: len(agent_result_text) // 4
+  --executor claude-subagent \
+  --model claude-sonnet-4-6 \
+  --tests-passed                      # include if tests passed in the subagent
+```
+
+**Where to get the numbers:**
+- `total_subagent_tokens`: sum the `subagent_tokens` field from every task-notification
+  `<usage>` block for this ticket (implementer + reviewer(s))
+- `summary_tokens`: rough estimate — `len(result_text) // 4` where `result_text` is the
+  agent's returned summary string
+
+Log immediately; if the merge was done manually (without `vyuha merge`), still call
+`vyuha log` right after the git commit.
+
+If `vyuha start` fails with *"grabbed by another session"* or *"conflicts with …"*,
+**skip that ticket this round** and move on — it is not an error, just a lost race or a
+lock. The next `vyuha next` will reflect reality.
+
+For `claude-subagent`/`claude`: Give the subagent only the ticket spec and its `touches` —
+not the board state.
+
+For `claude-process`: Run `claude -p "<prompt>"` as a subprocess in the ticket's worktree
+(`worktrees/tick-NNN`). The prompt is the same context as what would be given to a Task
+subagent. Capture stdout/stderr; non-zero exit means implementation failed.
+
+---
+
+## 3. Review gate (always runs — agent review at full quality)
+
+After `vyuha complete TICK-NNN`, dispatch a **review subagent** using the resolved
+reviewer executor — which may differ from the implementer's executor. Resolve it as:
+
+```python
+reviewer = ticket.get('reviewer') or cfg.get('reviewer') or cfg['executor']
+```
+
+Resolution order (first non-empty value wins):
+1. Ticket-level `reviewer` field in frontmatter (per-ticket override)
+2. Project-level `reviewer` in `.vyuha.yml` (project-wide reviewer default)
+3. Project-level `executor` in `.vyuha.yml` (fallback to implementer's executor)
+
+Dispatch the review subagent using the resolved `reviewer` value, **not** the
+implementer's executor. This allows, for example, a `claude-process` project to use
+`claude-subagent` for reviews, or a specific ticket to route its review to `human`.
+
+### What to give the reviewer
+
+```
+Ticket spec:
+  id: TICK-NNN
+  title: <title>
+  close_criteria: <close_criteria>
+  touches: [<files>]
+
+Diff (branch vs main):
+<output of: git diff main...tick-nnn>
+```
+
+### What the reviewer returns
+
+A JSON object on stdout:
+```json
+{
+  "verdict": "approved" | "changes_requested",
+  "summary": "<one-line verdict summary>",
+  "findings": ["<finding 1>", "<finding 2>"]
+}
+```
+
+### How the orchestrator calls the CLI
+
+```bash
+# Parse the JSON verdict and call:
+vyuha review TICK-NNN \
+  --verdict <verdict> \
+  --summary "<summary>" \
+  --findings "<newline-joined findings>"
+```
+
+`vyuha review --verdict approved` → flips ticket to `in_review`, stores
+`review_verdict` and `review_summary` in frontmatter, appends findings under
+`## Review Findings` in the ticket body.
+
+`vyuha review --verdict changes_requested` → stores fields, exits non-zero,
+**leaves ticket at `code_complete`**. The orchestrator treats this ticket as
+blocked for that batch round.
+
+### Policy on changes_requested
+
+- Leave the ticket at `code_complete` with the findings stored.
+- Continue the rest of the batch — do not halt the whole run.
+- Report blocked tickets in the end-of-run summary (§6).
+- Do **not** auto-retry the implementation; a human should inspect first.
+
+---
+
+## 4. Rate-limit / load handling (set the cap optimistically)
+<!-- was §3 before the review gate was added as §3 -->
+
+So you can set `max_parallel` to the cap rather than guessing low:
+
+- On HTTP **429 / rate-limit** from a subagent: respect `Retry-After`, exponential
+  backoff with jitter, then retry that ticket. Do **not** fail the batch.
+- If 429s persist across a round, **shrink the live worker count by 1** (adaptive
+  throttle) and log it; recover upward after a clean round.
+- On a **local** executor, OOM/timeout is the signal instead — lower the cap, never retry
+  blindly into the same wall.
+
+---
+
+## 5. Review policy (human gates only — agent review ALWAYS runs)
+
+Set per-batch via `--human-review`, default `final`. Agent review at full quality runs on
+**every** ticket regardless.
+
+| Mode | Agent review | Human gate |
+|---|---|---|
+| `per_ticket` | full quality | stop each ticket at `in_review` for a human |
+| `final` (default) | full quality | one human pass over the whole batch at the end |
+| `none` | full quality | none — pre-vetted/trusted runs only |
+
+`none` does not mean unreviewed; it means no *human* gate.
+
+---
+
+## 5a. Watch daemon spawn on exit (TICK-019 / TICK-023)
+
+After the run loop exits — whether the board is empty or only blocked/in-review
+tickets remain — check for tickets still at `in_review` status.
+
+**If any `in_review` tickets exist:**
+
+1. Check whether a watcher is already running:
+   ```bash
+   vyuha watch --status
+   ```
+2. If not running, spawn a detached background watcher using the `spawn_detached`
+   helper from `vyuha.lifecycle`. This is platform-agnostic Python — no `nohup`,
+   no `&`, no shell syntax:
+   ```python
+   from vyuha.lifecycle import spawn_detached
+   from pathlib import Path
+   import sys
+
+   log_path = repo_root / ".vyuha" / "watch.log"
+   pid = spawn_detached([sys.executable, "-m", "vyuha", "watch"], log_path)
+   print(f"[orchestrate] watch daemon started (pid {pid}) — will merge approved PRs in background")
+   ```
+   The orchestrator's `spawn_watch_daemon(repo_root)` function wraps this exactly.
+3. If already running, skip spawn and note it in the summary.
+
+**End-of-run summary line (when daemon spawned or already running):**
+```
+[waiting] N ticket(s) in review — watch daemon running (pid NNN)
+```
+
+**If no `in_review` tickets:** do not spawn the watcher.
+
+The watcher polls every 60 seconds, calls `vyuha merge` on APPROVED PRs, and exits
+when no `in_review` tickets with a `pr_number` remain.
+
+---
+
+## 7. Context hygiene — keep the main session slim
+
+The orchestrator runs in the main Claude session. Every tool result that lands here
+consumes context that is never reclaimed. Subagents exist precisely to keep heavy
+content out of this session. Violating these rules causes the main context to fill
+faster than the board clears, eventually forcing a summarisation mid-run.
+
+### Rules
+
+**`vyuha start` — suppress the ticket echo**
+
+`vyuha start` prints the full ticket spec to stdout. Capture only the first 3 lines
+(worktree path / branch / "Started"):
+
+```bash
+vyuha start TICK-NNN 2>&1 | head -3
+```
+
+**Reviewer subagents — never relay diffs through main context**
+
+Do NOT fetch `git diff main...tick-NNN` in the main session and paste it into the
+reviewer prompt. Instead, tell the reviewer where to look:
+
+```
+Read the diff yourself:
+  git -C /home/.../worktrees/tick-NNN diff main...tick-NNN
+Do not ask me to provide it — run the command directly.
+```
+
+This keeps the diff bytes in the subagent's context, not here.
+
+**Reviewer subagents — read worktree files, not main-repo files**
+
+Reviewer agents that need to read source files MUST be told the worktree path
+explicitly. Agents that default to the main repo see pre-merge state and produce
+false `changes_requested` verdicts. Always include in every reviewer prompt:
+
+```
+Work from the worktree at: /home/.../worktrees/tick-NNN
+Do NOT read files from the main repo path.
+```
+
+**Notes files — bounded by design**
+
+Notes files are written only on ticket hibernation (interrupted executor sessions).
+Each hibernation overwrites the file (not appends), and diffs are truncated at 30 KB
+at write time. Notes files are therefore always small and safe to inject as-is.
+
+**`vyuha next` / `vyuha board` — use sparingly**
+
+Call `vyuha --json next` once per loop iteration. Do not call `vyuha board` mid-loop
+unless diagnosing a problem — the JSON output from `next` has everything needed.
+
+### Symptoms of drift
+
+If the main context is above ~40 % mid-run, check:
+1. Were recent `vyuha start` outputs unsuppressed?
+2. Did a reviewer prompt contain an inline diff?
+3. Was a large notes file read into context?
+
+Correct forward; do not restart the run.
+
+---
+
+## 6. Stop conditions
+
+- `vyuha next` returns no candidates → **no eligible tickets remain**, exit cleanly.
+- Any ticket fails review (`changes_requested`) → leave at `code_complete` (§3), continue
+  rest, report blocked tickets at the end.
+- Any ticket with `--human-review per_ticket` approved → stops at `in_review` for a human.
+- Interrupt / error → release the orchestrator lock (§0 trap) and report what merged,
+  what is in flight, and what remains.
+
+End every run with a summary: merged, blocked/in-review, skipped (lost races), remaining.
+
+---
+
+## Notes / open design points
+
+- **`vyuha next` returns one disjoint batch, not a `--limit`.** The skill applies the
+  `max_parallel` slice itself. A future `vyuha next --limit N` would let the CLI enforce
+  the cap (testable without an LLM in the loop).
+- **The single-orchestrator lock is advisory** (PID file, §0) but now hardened in
+  `concurrency.py` (TICK-009 / DECISIONS F14): atomic check-and-set under an `flock`, with
+  stale-lock reclaim, exposed via `vyuha orchestrator-lock`. The per-ticket claim also
+  takes an `flock` around its read→write→commit window (`claim_lock`), closing the residual
+  TOCTOU gap — git's `index.lock` only serialized the status commit, not the whole claim.

vyuha-0.1.0/.claude/commands/tickets.md

@@ -0,0 +1,7 @@
+# /tickets — Ticket Board
+
+Runs `vyuha board` and displays all tickets grouped by status, plus the environment pipeline.
+
+```bash
+vyuha board
+```

vyuha-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,63 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+    branches: ["**"]
+
+jobs:
+  test:
+    name: Test (${{ matrix.os }}, Python ${{ matrix.python-version }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.11"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e .[dev]
+
+      - name: Run tests
+        if: runner.os != 'Windows'
+        run: python ci/run_pytest.py
+
+      - name: Run tests
+        if: runner.os == 'Windows'
+        shell: cmd
+        run: python ci/run_pytest.py
+
+  smoke-windows:
+    name: Windows runtime smoke (Python ${{ matrix.python-version }})
+    runs-on: windows-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11"]
+
+    steps:
+      - uses: actions/checkout@v5
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v6
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e .[dev]
+
+      # Unmocked end-to-end exercise of the OS boundaries the unit suite mocks/skips:
+      # detached spawn (CREATE_NEW_PROCESS_GROUP), os.kill SIGTERM (TerminateProcess),
+      # the os.kill liveness probe, portalocker flock, and a real `vyuha init` run.
+      - name: Run runtime smoke test
+        shell: cmd
+        run: python ci/smoke_windows.py

vyuha-0.1.0/.gitignore

@@ -0,0 +1,30 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+venv/
+.venv/
+
+# Vyuha local state
+.vyuha.yml
+.vyuha/*
+!.vyuha/notes/
+.vyuha/notes/*
+!.vyuha/notes/.gitkeep
+worktrees/
+*-context-log.jsonl
+
+# Claude Code harness files
+HANDOFF.md
+next-session-prompt.md
+AUTONOMOUS_SDLC_PLATFORM_REVIEW.md
+TICK-017-complete.txt
+.claude/auto-continue.md
+.claude/settings.local.json
+.claude/settings.example.json
+.claude/standing-instructions.md
+.claude/stop-failure-events.jsonl
+.claude/statusline-quota-cache.sh

vyuha-0.1.0/.vyuha.yml.example

@@ -0,0 +1,65 @@
+# .vyuha.yml — project configuration for vyuha
+# Copy this file to .vyuha.yml in your repo root and edit to taste.
+# Or run `vyuha init` to generate a config interactively.
+
+ticket_prefix: TICK          # TICK-NNN, FEAT-NNN, BUG-NNN, TASK-NNN, etc.
+tickets_dir: .vyuha/tickets
+worktrees_dir: .vyuha/worktrees
+
+# Who writes the code
+executor: claude             # claude | claude-subagent | claude-process | aider | openhands | codex | ollama
+
+# Who reviews the code (optional — defaults to executor if omitted).
+# Set to a different executor for model review, or `human` to pause after
+# completion until a person records an explicit verdict.
+# reviewer: claude
+
+# Max tickets the orchestrator runs in parallel.
+# Effective batch = min(touch-disjoint candidates, max_parallel)
+max_parallel: 2
+
+# Per-executor overrides (replace the global, not additive).
+# `flags` are prepended to the executor command when dispatching a ticket.
+# The flags below enable headless/autonomous operation — remove them if you
+# want the executor to prompt for approval on each action (supervised mode).
+executors:
+  claude:  { max_parallel: 3, flags: ["--dangerously-skip-permissions"] }
+  aider:   { max_parallel: 1, flags: ["--yes-always"] }
+  codex:   { max_parallel: 3, flags: ["--approval-policy=never"] }
+  ollama:  { max_parallel: 1, models: { implement: llama3.1, review: qwen2.5-coder } }
+
+# Files/patterns where overlapping tickets cannot run in parallel.
+# Leave empty if your project has no shared core files.
+core_files: []
+core_patterns: []
+
+# Statuses during which a ticket's `touches` stay locked (held until merge).
+lock_statuses: [in_progress, code_complete, in_review]
+
+# ── Feature flags (optional) ─────────────────────────────────────────────────
+# Remove this section if you do not use feature flags.
+flag_file: ~/.vyuha/feature_flags.json
+
+# ── Deployment pipeline (optional) ───────────────────────────────────────────
+# Remove this section for projects with no deployment pipeline (libraries,
+# research, open-source). Add one entry per environment in promotion order.
+environments:
+  - name: staging
+    branch: staging
+    from: main                          # base branch for pending-diff + promotion
+    trigger: manual                     # manual | auto (auto = hook-driven, vyuha reports only)
+    sync: ff-only                       # ff-only | merge-no-ff
+    guard_script: null                  # path to script; exit 1 blocks promote
+    pre_promote: []                     # scripts to run before promote
+    post_promote: []                    # scripts to run after promote
+    flag_file: ~/.vyuha/staging.feature_flags.json
+
+  - name: production
+    branch: production
+    from: main
+    trigger: manual
+    sync: ff-only
+    guard_script: null
+    pre_promote: []
+    post_promote: []
+    flag_file: ~/.vyuha/feature_flags.json