shikiru-cli 0.2.0__py3-none-any.whl

shikiru/prompts/templates/conflicts.md.j2

@@ -0,0 +1,22 @@
+{% extends "_base.md.j2" %}
+{% import "_macros.md.j2" as macros %}
+{% block body %}
+You are the Implementer resolving a rebase conflict during integration of this task.
+
+{% if conflict %}
+The latest conflict or verification guidance is:
+
+{{ conflict | fenced("text") }}
+{% endif %}
+
+{{ macros.facts_section(facts) }}
+
+Resolve the conflict, keeping the intent of both sides, then commit. Report `completed` only
+when the rebase can proceed cleanly; report `needs_decision` or `blocked` with a concrete
+`question` otherwise.
+
+Before committing, check the target project's instructions and documentation for its commit-message
+convention. Follow that convention when one is documented; use Conventional Commits if none is
+documented. Keep the subject concise and summarizing the conflict resolution, and end the commit
+message with the trailer `Task: {{ task_id }}` on its own line.
+{% endblock %}

shikiru/prompts/templates/consult.md.j2

@@ -0,0 +1,5 @@
+{% extends "_base.md.j2" %}
+{% import "_macros.md.j2" as macros %}
+{% block body %}
+{{ macros.consult_body(question, operator_decision) }}
+{% endblock %}

shikiru/prompts/templates/continue.md.j2

@@ -0,0 +1,4 @@
+{% extends "_base.md.j2" %}
+{% block body %}
+Continue this task's current turn; nothing about it has changed.
+{% endblock %}

shikiru/prompts/templates/feedback_analysis.md.j2

@@ -0,0 +1,29 @@
+{% extends "_base.md.j2" %}
+{% import "_macros.md.j2" as macros %}
+{% block body %}
+You are the Leader analysing the pull request review feedback below for this task. Task mode: `{{ mode }}`.
+
+{{ macros.facts_section(facts) }}
+
+## Feedback
+
+{{ feedback_snapshot | fenced("json") }}
+
+Decide every source item exactly once, by its `id`. A discussion is given whole, with the earlier
+answers that were already posted in it. Its messages marked `"new": true` are the ones to answer;
+the unmarked ones are context, and `reply` answers only the marked ones. Each item may raise several points: list all of
+them in `points` and cover each in `detail` and `reply`. Choose `address` for a request to accept,
+`already_addressed` when the Git facts or files show it is done (a moved or outdated location is
+not proof), `disagree` for a request to decline with a specific reason, and `needs_operator`
+when evidence is missing or requirements conflict; never invent a fix for those.
+
+Put each piece of implementation work in `work` with a concrete instruction, and point every
+`address` decision at it by `work_id`. Duplicate requests share one `work` entry but keep their own
+decision and `reply`. Do not change code or files. Replies are proposals; the engine publishes
+them after verification.
+
+{% if mode == "plan" %}
+This is a planning task: accepted work stays within its planning and documentation scope. A request
+to implement the planned product is a `needs_operator` decision about scope.
+{% endif %}
+{% endblock %}

shikiru/prompts/templates/feedback_rework.md.j2

@@ -0,0 +1,33 @@
+{% extends "_base.md.j2" %}
+{% import "_macros.md.j2" as macros %}
+{% block body %}
+You are the Implementer applying the accepted work from pull request review feedback. Task mode: `{{ mode }}`.
+
+{{ macros.facts_section(facts) }}
+
+## Work to do
+{% for work in feedback_work %}
+
+{{ work | fenced("json") }}
+{% endfor %}
+
+## Feedback it answers
+
+{{ feedback_snapshot | fenced("json") }}
+
+In a discussion, the messages marked `"new": true` are the ones the work answers; the unmarked ones
+are context.
+
+Do exactly this work, commit it, run the project's tests and keep the trackers current. Do not
+reply to the reviewers or touch other feedback.
+
+Before committing, check the target project's instructions and documentation for its commit-message
+convention. Follow that convention when one is documented; use Conventional Commits if none is
+documented. Keep each subject concise and summarizing its commit. End every commit message with the
+trailer `Task: {{ task_id }}` on its own line.
+{% if mode == "plan" %}
+This is a planning task: stay within planning and documentation changes.
+{% endif %}
+Report `completed` only when nothing remains; report `needs_decision` or `blocked` with a concrete
+`question` otherwise.
+{% endblock %}

shikiru/prompts/templates/feedback_verify.md.j2

@@ -0,0 +1,33 @@
+{% extends "_base.md.j2" %}
+{% import "_macros.md.j2" as macros %}
+{% block body %}
+You are the Leader verifying the result of a pull request review feedback round. Task mode: `{{ mode }}`.
+
+{{ macros.facts_section(facts) }}
+
+## Feedback snapshot
+
+{{ feedback_snapshot | fenced("json") }}
+
+## Your analysis
+
+{{ feedback_analysis | fenced("json") }}
+
+Review the changes with `git diff {{ base }}...HEAD` in the workspace. The facts above outrank the
+Implementer's claims. Check that each accepted request is really satisfied, that each
+`already_addressed` claim is true, and that each reply is accurate against the snapshot and the
+Git and check evidence. Do not change code or tests.
+
+In a discussion, the messages marked `"new": true` are the ones each reply must answer; the
+unmarked ones are context, including earlier answers.
+
+Choose `accept` only when every change and reply is right; give the final reply for each source
+item that has one in `replies`. Check the target project's instructions and documentation for its
+commit-message convention. On `accept`, also give `commit_subject`: a concise subject for the whole
+change following that convention, or Conventional Commits if none is documented (no task reference).
+Choose `changes_requested` with `issues` for further rework, or `escalate` with options for the
+Operator. `supersede` is not available.
+{% if final_round %}
+This is the final round: `changes_requested` is not available.
+{% endif %}
+{% endblock %}

shikiru/prompts/templates/handoff.md.j2

@@ -0,0 +1,23 @@
+{% extends "_base.md.j2" %}
+{% import "_macros.md.j2" as macros %}
+{% block body %}
+You are picking up this task in a fresh session. Read the earlier reports and facts below to
+catch up before doing anything else.
+
+{{ macros.facts_section(facts) }}
+
+{% if operator_decision is defined %}
+{{ macros.consult_body(question, operator_decision) }}
+{% else %}
+Continue the task from here.
+{% endif %}
+
+For commits you make, check the target project's instructions and documentation for its
+commit-message convention. Follow that convention when one is documented; use Conventional Commits
+if none is documented. Keep each subject concise and summarizing its commit. End every commit message
+with the trailer `Task: {{ task_id }}` on its own line.
+
+For a plan or an accepted review, give `commit_subject` and `summary` for the whole planned or
+accepted change. Keep the summary short. For an accepted review, draw on every implementation and
+rework report above, not only the latest review.
+{% endblock %}

shikiru/prompts/templates/implement.md.j2

@@ -0,0 +1,13 @@
+{% extends "_base.md.j2" %}
+{% block body %}
+You are the Implementer, starting this task's first implementation turn.
+
+Implement the request, commit your work, run the project's tests and keep the trackers
+current. Report `completed` only when nothing remains; report `needs_decision` or `blocked`
+with a concrete `question` otherwise.
+
+Before committing, check the target project's instructions and documentation for its commit-message
+convention. Follow that convention when one is documented; use Conventional Commits if none is
+documented. Keep each subject concise and summarizing its commit. End every commit message with the
+trailer `Task: {{ task_id }}` on its own line.
+{% endblock %}

shikiru/prompts/templates/plan.md.j2

@@ -0,0 +1,30 @@
+{% extends "_base.md.j2" %}
+{% block body %}
+You are the Leader planning a task.
+
+Shape the plan in the trackers listed above and commit it. Fill `new_tasks` only when the
+request itself asks you to execute the plan, not merely to produce one; otherwise leave it
+empty. A plan turn implements nothing, so when the request asks for work to be done (for
+example "implement ..."), `new_tasks` is the only way that work happens, even when the
+trackers already describe it: leaving it empty ends this task with nothing implemented.
+When you fill `new_tasks`, restructure the tracker entries so each new task has its own
+entry and together they replace this task's entry; each new task ticks its own entry when done.
+Record any tracker changes outside the plan itself in `scope_changes`.
+
+Check the target project's instructions and documentation for its commit-message convention. Give
+`commit_subject` a concise subject for the whole plan change using that convention, or Conventional
+Commits if none is documented (no task reference). Keep `summary` short and describe the whole
+committed plan change.
+Use that subject for the plan commit, and end the commit message with the trailer
+`Task: {{ task_id }}` on its own line.
+
+Give each tracker entry for a task, and each `new_tasks` request, an acceptance-criteria section
+in exactly this form: the heading verbatim, then one independently verifiable criterion per bullet.
+
+## {{ acceptance_criteria_heading }}
+- <criterion>
+- <criterion>
+
+Put nothing else under that heading: a prose line or another heading ends the section, and
+criteria written after it are not read.
+{% endblock %}

shikiru/prompts/templates/rework.md.j2

@@ -0,0 +1,13 @@
+{% extends "_base.md.j2" %}
+{% block body %}
+You are the Implementer, reworking this task after a verdict requested changes.
+
+Address every issue raised in the verdict above, commit your work, run the project's tests
+and keep the trackers current. Report `completed` only when nothing remains; report
+`needs_decision` or `blocked` with a concrete `question` otherwise.
+
+Before committing, check the target project's instructions and documentation for its commit-message
+convention. Follow that convention when one is documented; use Conventional Commits if none is
+documented. Keep each subject concise and summarizing its commit. End every commit message with the
+trailer `Task: {{ task_id }}` on its own line.
+{% endblock %}

shikiru/prompts/templates/triage.md.j2

@@ -0,0 +1,20 @@
+{% extends "_base.md.j2" %}
+{% block body %}
+You are the Leader triaging a task, before any work starts.
+
+This turn is read-only: make no edits to the repository or the trackers.
+
+Decide:
+- `mode`: `implement` for a self-contained change, `plan` when a plan turn should shape the
+  work first, including when the request needs decomposing into several tasks, as it does
+  when it spans several tracker entries: each entry becomes its own task. An open
+  decision is not a reason to plan: a plan turn cannot raise it, while an implement task
+  raises it through consult to you and, if you cannot decide it, to the Operator.
+- `complexity`, `acceptance_criteria` and `references`.
+
+When the request has an acceptance-criteria section, carry its bullets into
+`acceptance_criteria` unchanged. The section starts at a line holding only one of
+`## {{ acceptance_criteria_heading }}`, `{{ acceptance_criteria_heading }}:`,
+`**{{ acceptance_criteria_heading }}**` or `**{{ acceptance_criteria_heading }}:**`, in any
+letter case.
+{% endblock %}

shikiru/prompts/templates/verify.md.j2

@@ -0,0 +1,29 @@
+{% extends "_base.md.j2" %}
+{% import "_macros.md.j2" as macros %}
+{% block body %}
+You are the Leader verifying the Implementer's work on this task.
+
+{{ macros.facts_section(facts) }}
+
+Review the change with `git diff {{ base }}...HEAD` in the workspace. The facts above outrank
+the Implementer's claims. Do not change code or tests: when something is missing or wrong,
+choose `changes_requested` with the issues. The only files you may edit are the trackers, for
+scope changes, and you commit those edits. Accept only when no issues remain;
+non-blocking residual risks go into `residual_risks` or `new_tasks`, not `issues`.
+
+If you commit tracker scope changes, follow the target project's documented commit-message
+convention, using Conventional Commits if none is documented. Summarize the changes and end the
+message with the trailer `Task: {{ task_id }}` on its own line.
+
+Check the target project's instructions and documentation for its commit-message convention. When
+you `accept`, `commit_subject` is a concise subject for the whole change following that convention,
+or Conventional Commits if none is documented (no task reference). Keep `summary` short and describe
+the entire change as it will land, drawing on every implementation and rework turn in the reports
+above, not only this review.
+{% if final_round %}
+This is the final round: choose `accept`, `supersede` (decompose into `new_tasks`) or
+`escalate`. `changes_requested` is not available this round.
+{% endif %}
+When you `escalate`, give the Operator options, exactly one `recommended`, and set `needs_input` on
+an option that asks the Operator to provide something (a file, a result, access, a value).
+{% endblock %}

shikiru/store/__init__.py

@@ -0,0 +1 @@
+"""SQLite state store: schema, migrations, per-aggregate stores and the read-only reader."""

shikiru/store/commands.py

@@ -0,0 +1,242 @@
+"""Operator command queue: append, dispatch and acknowledge."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+from pydantic import TypeAdapter
+
+from shikiru.domain.commands import (
+    COMMAND_ID_KEY,
+    Command,
+    CommandStatus,
+    IdentifiedCommand,
+    Submit,
+)
+from shikiru.store.database import (
+    dump_json,
+    format_timestamp,
+    load_json,
+    next_sequence,
+    require_after_insert,
+    transaction,
+)
+from shikiru.store.tasks import TASK_ID_PREFIX, TASK_SEQUENCE
+
+if TYPE_CHECKING:
+    import sqlite3  # noqa: TID251
+
+    from shikiru.clock import Clock
+
+_COMMAND_ADAPTER: TypeAdapter[Command] = TypeAdapter(Command)
+_RESULT_ADAPTER: TypeAdapter[dict[str, Any] | None] = TypeAdapter(dict[str, Any] | None)
+_SUBMIT_TASK_ID_JSON_PATH = "$.task_id"
+
+
+def _identified(command: Command, command_id: int) -> Command:
+    if isinstance(command, IdentifiedCommand):
+        return command.model_copy(update={COMMAND_ID_KEY: command_id})
+    return command
+
+
+@dataclass(frozen=True, slots=True)
+class QueuedCommand:
+    """One pending command, as `CommandQueue.pending()` hands it to the engine."""
+
+    id: int
+    command: Command
+
+
+@dataclass(frozen=True, slots=True)
+class CommandOutcome:
+    """A command's lifecycle status, for `OperatorCommands` to wait on its ack."""
+
+    id: int
+    status: CommandStatus
+    result: dict[str, Any] | None
+
+
+@dataclass(frozen=True, slots=True)
+class StoredCommand:
+    """One durable command row read for bounded operator history."""
+
+    id: int
+    ts: str
+    command: Command
+    status: CommandStatus
+    result: dict[str, Any] | None
+
+
+@dataclass(frozen=True, slots=True)
+class CommandHistoryPage:
+    """One bounded page of durable command rows."""
+
+    entries: list[StoredCommand]
+    offset: int
+    limit: int
+    total_count: int
+    has_more: bool
+
+
+def fetch_command_history(
+    connection: sqlite3.Connection,
+    *,
+    limit: int,
+    offset: int = 0,
+    status: CommandStatus | None = None,
+) -> CommandHistoryPage:
+    """Read one bounded newest-first page with its stored status and result."""
+    if status is None:
+        total_count = connection.execute("SELECT COUNT(*) FROM commands").fetchone()[0]
+        rows = connection.execute(
+            "SELECT id, ts, payload, status, result FROM commands "
+            "ORDER BY id DESC LIMIT ? OFFSET ?",
+            (limit, offset),
+        ).fetchall()
+    else:
+        total_count = connection.execute(
+            "SELECT COUNT(*) FROM commands WHERE status = ?", (status.value,)
+        ).fetchone()[0]
+        rows = connection.execute(
+            "SELECT id, ts, payload, status, result FROM commands WHERE status = ? "
+            "ORDER BY id DESC LIMIT ? OFFSET ?",
+            (status.value, limit, offset),
+        ).fetchall()
+    entries = [_stored_command(row) for row in rows]
+    return CommandHistoryPage(
+        entries=entries,
+        offset=offset,
+        limit=limit,
+        total_count=total_count,
+        has_more=offset + len(entries) < total_count,
+    )
+
+
+def fetch_command(
+    connection: sqlite3.Connection,
+    command_id: int,
+) -> StoredCommand | None:
+    """Read one durable command status by id without changing its lifecycle."""
+    row = connection.execute(
+        "SELECT id, ts, payload, status, result FROM commands WHERE id = ?",
+        (command_id,),
+    ).fetchone()
+    return _stored_command(row) if row is not None else None
+
+
+def fetch_pending_command(
+    connection: sqlite3.Connection,
+    command: Command,
+) -> StoredCommand | None:
+    """Find an identical still-pending command without scanning history into memory."""
+    payload = dump_json(_COMMAND_ADAPTER, command)
+    if isinstance(command, Submit):
+        row = connection.execute(
+            "SELECT id, ts, payload, status, result FROM commands "
+            "WHERE status = ? AND kind = ? AND "
+            "json_remove(payload, ?) = json_remove(?, ?) ORDER BY id DESC LIMIT 1",
+            (
+                CommandStatus.PENDING.value,
+                command.kind.value,
+                _SUBMIT_TASK_ID_JSON_PATH,
+                payload,
+                _SUBMIT_TASK_ID_JSON_PATH,
+            ),
+        ).fetchone()
+    else:
+        row = connection.execute(
+            "SELECT id, ts, payload, status, result FROM commands "
+            "WHERE status = ? AND kind = ? AND payload = ? ORDER BY id DESC LIMIT 1",
+            (CommandStatus.PENDING.value, command.kind.value, payload),
+        ).fetchone()
+    return _stored_command(row) if row is not None else None
+
+
+def _stored_command(row: sqlite3.Row) -> StoredCommand:
+    result = row["result"]
+    return StoredCommand(
+        id=row["id"],
+        ts=row["ts"],
+        command=load_json(_COMMAND_ADAPTER, row["payload"]),
+        status=CommandStatus(row["status"]),
+        result=load_json(_RESULT_ADAPTER, result) if result is not None else None,
+    )
+
+
+class CommandQueue:
+    """Appends operator commands and lets the engine dispatch and acknowledge them."""
+
+    def __init__(self, connection: sqlite3.Connection, clock: Clock) -> None:
+        """Use `connection` and `clock` for every write below.
+
+        Unlike the other stores, this connection isn't only the engine's: clients (CLI, MCP)
+        append commands and, for `Submit`, allocate the task id here too.
+        """
+        self._connection = connection
+        self._clock = clock
+
+    def append(self, command: Command) -> QueuedCommand:
+        """Append `command`; a `Submit` is given its `T-n` id here, atomically."""
+        ts = format_timestamp(self._clock.now())
+        with transaction(self._connection):
+            if isinstance(command, Submit):
+                seq = next_sequence(self._connection, TASK_SEQUENCE)
+                command = command.model_copy(update={"task_id": f"{TASK_ID_PREFIX}{seq}"})
+            cursor = self._connection.execute(
+                "INSERT INTO commands (ts, kind, payload) VALUES (?, ?, ?)",
+                (ts, command.kind.value, dump_json(_COMMAND_ADAPTER, command)),
+            )
+            command_id = cursor.lastrowid
+        command_id = require_after_insert(
+            command_id, "sqlite did not allocate a rowid for the new command"
+        )
+        return QueuedCommand(id=command_id, command=command)
+
+    def pending(self) -> list[QueuedCommand]:
+        """Read every pending command, oldest first, as typed `domain.commands.Command` models."""
+        rows = self._connection.execute(
+            "SELECT id, payload FROM commands WHERE status = ? ORDER BY id",
+            (CommandStatus.PENDING.value,),
+        ).fetchall()
+        return [
+            QueuedCommand(
+                id=row["id"],
+                command=_identified(load_json(_COMMAND_ADAPTER, row["payload"]), row["id"]),
+            )
+            for row in rows
+        ]
+
+    def mark_done(self, command_id: int, result: dict[str, Any] | None = None) -> None:
+        """Mark `command_id` done, recording `result` if the client needs it."""
+        self._set_status(command_id, CommandStatus.DONE, result)
+
+    def mark_rejected(self, command_id: int, result: dict[str, Any] | None = None) -> None:
+        """Mark `command_id` rejected, recording `result` (e.g. an error message)."""
+        self._set_status(command_id, CommandStatus.REJECTED, result)
+
+    def _set_status(
+        self, command_id: int, status: CommandStatus, result: dict[str, Any] | None
+    ) -> None:
+        self._connection.execute(
+            "UPDATE commands SET status = ?, result = ? WHERE id = ?",
+            (
+                status.value,
+                dump_json(_RESULT_ADAPTER, result),
+                command_id,
+            ),
+        )
+
+    def status(self, command_id: int) -> CommandOutcome | None:
+        """Read `command_id`'s current lifecycle status, or `None` if it doesn't exist."""
+        row = self._connection.execute(
+            "SELECT id, status, result FROM commands WHERE id = ?", (command_id,)
+        ).fetchone()
+        if row is None:
+            return None
+        result = row["result"]
+        return CommandOutcome(
+            id=row["id"],
+            status=CommandStatus(row["status"]),
+            result=load_json(_RESULT_ADAPTER, result) if result is not None else None,
+        )