shikiru-cli 0.2.0__tar.gz

shikiru_cli-0.2.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,33 @@
+name: Bug report
+description: Report a problem with Shikiru
+labels: ["bug"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Do not paste secrets or private project content. State files, prompts and reports can contain
+        it; redact before posting.
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: Steps to reproduce
+      description: The commands you ran, in order.
+  - type: textarea
+    id: environment
+    attributes:
+      label: Environment
+      description: Output of `shikiru --version` and `shikiru doctor`, and your operating system.
+    validations:
+      required: true

shikiru_cli-0.2.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,24 @@
+name: Feature request
+description: Suggest a change to Shikiru
+labels: ["enhancement"]
+body:
+  - type: markdown
+    attributes:
+      value: >-
+        Open this before starting anything larger than a small fix, so the approach can be agreed first.
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behaviour
+    validations:
+      required: true
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered

shikiru_cli-0.2.0/.github/pull_request_template.md

@@ -0,0 +1,12 @@
+## Summary
+
+<!-- What changes and why. Link the issue if there is one. -->
+
+## Quality gate
+
+Result of `PYTEST_ADDOPTS='--dist=loadfile' uv run poe check` on this branch (green, or the failing check):
+
+## Checklist
+
+- [ ] Commits follow Conventional Commits.
+- [ ] `AGENTS.md` conventions are followed.

shikiru_cli-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,104 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  check:
+    name: ${{ matrix.os }}
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      max-parallel: 2
+      matrix:
+        os: [ubuntu-24.04, macos-15]
+    env:
+      PYTEST_ADDOPTS: --dist=loadfile --durations=15
+      SHIKIRU_TEST_CPUS_PER_WORKER: "1"
+      UV_NO_PROGRESS: "true"
+      NODE_OPTIONS: --max-old-space-size=1536
+      TERM: xterm-256color
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: "0.12.5"
+          python-version: "3.14"
+          activate-environment: true
+          enable-cache: false
+
+      - name: Install required host tools
+        run: |
+          if [[ "$RUNNER_OS" == Linux ]]; then
+            sudo apt-get update
+            sudo apt-get install --yes \
+              bison build-essential ca-certificates curl git libevent-dev libncurses-dev pkg-config
+            TMUX_VERSION=3.5a
+            TMUX_SHA256=16216bd0877170dfcc64157085ba9013610b12b082548c7c9542cc0103198951
+            TMUX_ARCHIVE="$RUNNER_TEMP/tmux-$TMUX_VERSION.tar.gz"
+            TMUX_SOURCE="$RUNNER_TEMP/tmux-$TMUX_VERSION"
+            curl --fail --location --silent --show-error \
+              "https://github.com/tmux/tmux/releases/download/$TMUX_VERSION/tmux-$TMUX_VERSION.tar.gz" \
+              --output "$TMUX_ARCHIVE"
+            printf '%s  %s\n' "$TMUX_SHA256" "$TMUX_ARCHIVE" | sha256sum --check
+            tar --extract --gzip --file "$TMUX_ARCHIVE" --directory "$RUNNER_TEMP"
+            cd "$TMUX_SOURCE"
+            ./configure --prefix=/usr/local
+            make -j2
+            sudo make install
+          else
+            brew install git tmux
+          fi
+
+      - name: Sync locked environment
+        run: uv sync --locked
+
+      - name: Check required host tool versions
+        run: |
+          uv run --locked python - <<'PY'
+          import asyncio
+
+          from shikiru.domain.versions import parse_version
+          from shikiru.operator.doctor import GIT_MINIMUM_VERSION, TMUX_MINIMUM_VERSION
+          from shikiru.process import SubprocessRunner
+
+          COMMAND_TIMEOUT = 5
+          REQUIREMENTS = (
+              ("git", "--version", GIT_MINIMUM_VERSION),
+              ("tmux", "-V", TMUX_MINIMUM_VERSION),
+          )
+
+          async def check_versions():
+              runner = SubprocessRunner()
+              for executable, flag, minimum in REQUIREMENTS:
+                  result = await runner.run(
+                      (executable, flag), timeout=COMMAND_TIMEOUT, check=True
+                  )
+                  version = parse_version(result.stdout)
+                  if version is None or version < minimum:
+                      raise SystemExit(f"{executable} must be at least {minimum}")
+                  print(f"{executable}: {result.stdout.strip()}")
+
+          asyncio.run(check_versions())
+          PY
+
+      - name: Run quality gate
+        run: uv run --locked poe check
+
+      - name: Build and exercise package distributions
+        run: bash scripts/release-readiness-smoke.sh

shikiru_cli-0.2.0/.github/workflows/release.yml

@@ -0,0 +1,136 @@
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions: {}
+
+jobs:
+  check:
+    name: Check CI passed on the tagged commit
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    permissions:
+      contents: read
+      actions: read
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Check the tagged commit is on main and CI passed on it
+        env:
+          GH_TOKEN: ${{ github.token }}
+          GH_REPO: ${{ github.repository }}
+        run: |
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "::error::the tag must point at a commit on main" >&2
+            exit 1
+          fi
+          passed="$(gh run list --workflow ci.yml --commit "$GITHUB_SHA" --json conclusion \
+            --jq 'any(.[]; .conclusion == "success")')"
+          if [[ "$passed" != true ]]; then
+            echo "::error::CI has not passed on this commit; wait for it and push the tag again" >&2
+            exit 1
+          fi
+
+  build:
+    name: Build the distributions
+    needs: check
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    env:
+      TAG: ${{ github.ref_name }}
+      UV_NO_PROGRESS: "true"
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          version: "0.12.5"
+          python-version: "3.14"
+          enable-cache: false
+
+      - name: Build the distributions
+        run: uv build
+
+      - name: Check the build carries the tag's version
+        run: |
+          VERSION="${TAG#v}"
+          if [[ ! -f "dist/shikiru_cli-$VERSION-py3-none-any.whl" ]]; then
+            echo "::error::tag $TAG does not build as shikiru-cli $VERSION" >&2
+            exit 1
+          fi
+
+      - name: Upload the distributions
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-24.04
+    timeout-minutes: 10
+    environment:
+      name: pypi
+    permissions:
+      id-token: write
+
+    steps:
+      - name: Download the distributions
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish with trusted publishing
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3
+
+  github:
+    name: Create the GitHub release
+    needs: pypi
+    runs-on: ubuntu-24.04
+    timeout-minutes: 15
+    permissions:
+      contents: write
+    env:
+      TAG: ${{ github.ref_name }}
+
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - name: Download the distributions
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: dist
+          path: dist/
+
+      - name: Write the release notes
+        run: |
+          python3 scripts/release_notes.py "$TAG" --repo "$GITHUB_REPOSITORY" \
+            > "$RUNNER_TEMP/release-notes.md"
+
+      - name: Create the GitHub release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          version="${TAG#v}"
+          prerelease=()
+          if [[ "${version%%.*}" == "0" ]]; then
+            prerelease+=(--prerelease)
+          fi
+          gh release create "$TAG" dist/* --verify-tag --title "$TAG" \
+            --notes-file "$RUNNER_TEMP/release-notes.md" "${prerelease[@]}"

shikiru_cli-0.2.0/.gitignore

@@ -0,0 +1,14 @@
+.venv/
+__pycache__/
+*.pyc
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+.pytest-timeout/
+.import_linter_cache/
+.coverage
+.coverage.*
+htmlcov/
+dist/
+build/
+*.egg-info/

shikiru_cli-0.2.0/.python-version

@@ -0,0 +1 @@
+3.14

shikiru_cli-0.2.0/AGENTS.md

@@ -0,0 +1,11 @@
+# Shikiru — Agent Conventions
+
+- **Read first**: `docs/design.md`.
+- **Conventions**: SOLID, KISS, YAGNI. One responsibility per class; pure functions in `domain`; constructor injection; no comments, clear names; docstrings only on public contracts and their implementations. No literals: tunables go in `defaults.toml`, protocol values in named constants. No silent fallbacks, no bare `except`. Build nothing beyond the task.
+- **Tests**: behaviour over implementation. Unit tests only for `domain` rules, models and parsers; integration tests for the rest (real SQLite, git, tmux via `tmux_server`, fake agent). Wait with `wait_until`, time with `FakeClock`, never sleep. No mocks of our own classes, no snapshot spam. Coverage ≥ 80%.
+- **Test value**: test domain rules and invariants, not the framework or data shape — no tests for pydantic features (frozen, extra, defaults), enum or constant listings, trivial wiring, or message/description wording. One table per rule. Integration tests assert observable behaviour at boundaries; coverage beyond the gate is not a goal.
+- **Environment**: In each fresh worktree run `uv sync --locked`. Verify that Python imports and tool entrypoints resolve to this worktree. If a copied `.venv` points elsewhere, recreate it before verification.
+- **Verification**: Match checks to the change. For documentation-only changes, including agent instructions, review the diff and run `git diff --check`; do not run application tests. For code or executable configuration changes, run relevant checks while developing, then `PYTEST_ADDOPTS='--dist=loadfile' uv run poe check` (the local worker count is half the CPU cores unless `SHIKIRU_TEST_CPUS_PER_WORKER` overrides the divisor; CI uses one worker per CPU, so do not pass `-n` locally) on the final changes before the final commit and completion report; it must be green. Repeat the full gate only when subsequent changes invalidate that result.
+- **Execution**: Prefer foreground checks. For background commands, retain their process handle and log path, inspect their exit status, and check existing results when resuming. Do not rely solely on completion notifications or start duplicate checks.
+- **Commits**: Conventional commits, one coherent change each. Separate independent refactorings; keep small supporting refactorings with the behavior they enable. The subject is what the release notes show, so write it for a user: `type(scope): what changed`. A change that breaks behavior, configuration or the schema marks the type with `!` or adds a `BREAKING CHANGE:` line to the body.
+

shikiru_cli-0.2.0/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

shikiru_cli-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,113 @@
+# Contributing to Shikiru
+
+Thank you for helping. Before you start:
+
+- Open an issue before anything larger than a small fix, so the approach can be agreed first.
+- Read [AGENTS.md](AGENTS.md) and [the design](docs/design.md). Its conventions apply to people as
+  well as agents.
+- Commit with [Conventional Commits](https://www.conventionalcommits.org/), one coherent change per
+  commit.
+- Before you open a pull request, make sure the quality gate is green. Its result goes in the pull
+  request template.
+- CI runs the same gate on Ubuntu and macOS.
+
+## Validate a checkout and a real project
+
+```sh
+uv sync --locked
+PYTEST_ADDOPTS='--dist=loadfile' uv run poe check
+bash scripts/release-readiness-smoke.sh
+```
+
+The quality gate covers formatting, lint, boundaries, types, unused-code checks and behavior tests.
+Real Claude/Codex adapter code is tested offline using recorded protocol output and controlled
+subprocesses: invocation, parsing, resumption, compaction, usage and failures. Engine integration
+uses the fake-agent plugin with real Git, SQLite and private tmux. Live provider contracts and
+real-agent end-to-end scenarios are opt-in and excluded from normal CI.
+The package smoke builds wheel/sdist and exercises an isolated installed package with a fake agent,
+a disposable HOME/repository and private tmux server; it makes no paid provider calls. GitHub CI
+syncs the locked development environment and runs both checks with one test worker per available CPU
+and job timeouts. The isolated installation resolves the built package's declared runtime
+dependencies.
+Automated checks do not establish reliability for every provider or real project.
+
+### Verify real agents
+
+These checks use your authenticated agent CLIs and consume real provider usage. Run them locally
+from the Shikiru checkout after `uv sync --locked`, with Git/tmux available and the agents you are
+testing installed, authenticated and permitted to execute the scratch project's commands. Run
+sequentially (`-n 0`); timeouts are not spending or RAM limits.
+
+For a configured project's actual role ladders, start with `shikiru doctor --probe` in that project.
+For automated adapter verification, choose model IDs supported by your account first:
+
+- Claude contract tests accept `SHIKIRU_CLAUDE_LIVE_MODEL` and
+  `SHIKIRU_CLAUDE_LIVE_CHANGE_MODEL` for the initial and model-change checks. Set both to supported
+  models; the model-change check skips if no second model is configured.
+- Codex contract tests currently use `_LIVE_MODEL`, `_LIVE_OTHER_MODEL` and `_EFFORT` in
+  [their test module](tests/integration/test_codex_headless_contract.py). Review/update those test
+  constants for your account; they are separate from project configuration and have no equivalent
+  model environment overrides.
+
+Enable live checks only for the invocation below. Include just the test file for each agent you
+have configured (both are shown):
+
+```sh
+SHIKIRU_E2E=1 uv run pytest -n 0 --no-cov -k live \
+  tests/integration/test_claude_headless_contract.py \
+  tests/integration/test_codex_headless_contract.py
+```
+
+These exercise report submission, measured usage, session/model resumption, stop/resume, structured
+Helper answers and context compaction. The compaction check deliberately grows context and can
+consume substantially more usage than a basic report check. Review skips as well as failures.
+
+For complete workflow verification, review `REAL_AGENT`, `REAL_MODEL`, `REAL_EFFORT` and
+`REAL_ROLE_LADDERS` in [real_agent_config.py](tests/e2e/real_agent_config.py); these configure all
+roles in disposable fixture repositories, independently of your `.shikiru/config.toml`. Start
+with one completion/integration scenario:
+
+```sh
+SHIKIRU_E2E=1 uv run pytest -n 0 --no-cov \
+  tests/e2e/test_real_agents.py::test_real_agents_e1_completes_and_integrates
+```
+
+Then run all six real-agent scenarios:
+
+```sh
+SHIKIRU_E2E=1 uv run pytest -n 0 --no-cov tests/e2e/test_real_agents.py
+```
+
+They cover completion/integration, next-turn Operator messages, planning with dependent parallel
+tasks, MCP decision resolution, restart recovery and takeover/handback. Tests use private tmux
+servers and disposable projects under `~/.cache/shikiru-e2e/`, with cleanup afterwards. Results go
+to `build/e2e/`; failure diagnostics go to `build/e2e/diagnostics/`. The harness has per-attempt and
+one-hour invocation time budgets and can retry an eligible failed scenario once, consuming
+additional usage. Its parallel-work scenarios disable CPU/free-RAM dispatch gates; monitor your
+host and account usage. See [budgets.py](tests/e2e/budgets.py) for the current limits. These paid
+checks are excluded from normal CI and have not been run as part of this cleanup.
+
+### Check your own project
+
+For a provider-backed check, clone a committed project into a fresh disposable directory, initialize
+Shikiru, review its ladders and submit one small, reviewable change. While active, detach/reattach,
+exercise a task pause and, where useful, Take over/Hand back; stop/start the engine to inspect
+recovery. Confirm the resulting diff, tests and Git history. Use a model and account you are willing
+to spend usage on; `doctor --probe` is also a live check.
+
+## Releasing
+
+A release is the commit tagged `v<version>`; see [the design](docs/design.md#releases-and-deployment).
+Push the tag on a commit of `main` whose CI has passed:
+
+```sh
+git tag v<version> && git push origin v<version>
+```
+
+The Release workflow does the rest. If a run fails, fix the cause on `main` and cut a new tag; a tag
+is not moved.
+
+The owner sets up publishing once. On pypi.org, add a pending publisher for the project `shikiru-cli`
+with owner `ferrum-code-dev`, repository `shikiru`, workflow `release.yml` and environment `pypi`. On
+GitHub, create the environment `pypi` in the repository settings. No PyPI token is stored in the
+repository.

shikiru_cli-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ferrum Code
+
+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.