sako 0.5.0__tar.gz

sako-0.5.0/.gitignore

@@ -0,0 +1,16 @@
+__pycache__/
+*.py[cod]
+.venv/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+node_modules/
+.env
+.env.*
+*.pem
+*.key
+*.sqlite*
+*.db
+.claude/settings.local.json
+dist/

sako-0.5.0/AGENTS.md

@@ -0,0 +1,84 @@
+# Working on SAKO
+
+Rules and checks for agents that change this repository. They extend
+[CONTRIBUTING.md](CONTRIBUTING.md), which people read first.
+
+SAKO is a small execution kit: [SAKO.md](SAKO.md) is the method with its default
+planner, `sako.py` is the runtime, `skills/` is the optional agent entry,
+`templates/` holds the empty task table, and `docs/` holds the demo, the glossary,
+the recipes, compatibility, limits, the lifecycle, and the guarantees with their
+evidence (validation).
+
+## Read path
+
+1. This file, then [CONTRIBUTING.md](CONTRIBUTING.md) for the design budgets and the
+   [principles](README.md#why-it-stays-small) it points to.
+2. [SAKO.md](SAKO.md) before changing behavior or planning, and the
+   [guarantees](docs/validation.md#guarantees) a change must keep.
+3. `tests/selftest.py` to see what is proven.
+
+## Laws
+
+- One runtime file. `sako.py` stays standard-library Python 3.10 or newer, in one
+  file within the runtime budget in CONTRIBUTING.md. Count before adding (`wc -l
+  sako.py`). Over the budget, remove something or reopen the question of a heavier
+  tool; never add a second script.
+- The principles, the guarantees and the maintainer's direction govern changes to
+  project conventions.
+- Machinery only after an observed need. A new check, command or hook shows first
+  that the ledger row, the method or an existing command cannot hold it.
+- Documents claim only what exists. A command that is not implemented is not
+  documented.
+- Examples are synthetic: no real product, person, account, path or session identifier
+  in examples, fixtures or tests. Comparisons, recipes, install steps and client wiring
+  may name real tools; check what they say against each tool's current documentation.
+- Plain language, no em dashes, in files, replies and commit messages.
+- Git is the archive: delete retired material and commit the deletion.
+
+## Traps
+
+- `init` needs this checkout or the package built from it (`pyproject.toml` installs
+  `sako.py` as `sako/__init__.py`). The runtime copied into a project cannot seed
+  another project.
+- The scenario suite starts `sleep` processes as stand-ins for agent sessions. An
+  interrupted run leaves them until they exit on their own, within an hour.
+
+## Checks
+
+From the checkout root:
+
+```sh
+PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
+PYTHONDONTWRITEBYTECODE=1 python3 tests/selftest.py
+git diff --check
+```
+
+Run both suites on the oldest supported Python when it is available. A change to
+`sako.py` without a green suite does not land.
+
+## Commits
+
+Commit under the author and committer identity already configured for this
+repository; never replace it with a tool identity or change global settings.
+
+Every agent-created commit ends, after a blank line, with one trailer per tool that
+did the work, each exactly once:
+
+```text
+Co-authored-by: Codex <noreply@openai.com>
+Co-authored-by: Claude <noreply@anthropic.com>
+```
+
+Use the Codex trailer for Codex work and the Claude trailer for Claude work. Credit both
+only when both materially contributed. Review-only involvement belongs in review
+evidence, not co-authorship. Commits made by a person alone carry no tool trailer.
+Keep each trailer exactly once when amending or squashing. These trailers are the
+whole attribution: no `Claude-Session` trailer, no session links.
+
+Write the message in a file and commit with `git commit -F <file>`. Check the
+resulting author, committer and message with `git show -s --format=full HEAD`, and the
+parsed trailers with `git show -s --format='%(trailers:key=Co-authored-by,valueonly)' HEAD`.
+
+`.claude/settings.json` supplies Claude Code's trailer text for this repository. A
+Claude session that commits here from outside this project must receive that setting
+explicitly. Codex follows this section; no automatic attribution setting is assumed.

sako-0.5.0/CHANGELOG.md

@@ -0,0 +1,44 @@
+# Changelog
+
+Notable changes to SAKO, one entry per release. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow
+[Semantic Versioning](https://semver.org/). SAKO is alpha software: commands and file
+formats can change in any 0.x release.
+
+## [0.5.0] - 2026-09-25
+
+The first public release.
+
+Install from your project's Git repository with `uvx sako init`. To update later, run
+`uvx sako@latest init --update`.
+
+### Added
+
+- A task ledger in Markdown, `.sako/work/TASKS.md`, with a done record that keeps a
+  receipt for every closed task.
+- A finish gate that checks, when a session stops, that its changes belong to a
+  claimed task, that closed work has a passing check for its content, and that
+  finished work is committed.
+- Hooks for Claude Code and Codex, chosen by `init`; any other agent runs `start`,
+  `check --gate` and `end` itself.
+- Claims and scope checks for parallel sessions in one repository and its linked
+  worktrees.
+- Three footprints for the records: local (the default), their own repository, or
+  committed with the code.
+- The method, `SAKO.md`, with a small default planner, and a `sako` skill for agents.
+
+### Known issues
+
+- Codex gets no hooks on Windows; there the agent runs the commands itself.
+- No live client session has run on a Mac yet; macOS is tested in CI.
+- See [limits](docs/limits.md) for the rest.
+
+### Tested with
+
+- Python 3.10 and 3.14 on Linux, macOS and Windows in CI; Python 3.10 and 3.12 on
+  WSL2 (Ubuntu 24.04).
+- Git 2.31 or newer.
+- Claude Code 2.1.280 on Linux and Codex 0.154.0 on Linux; Claude Code 2.1.220 hooks
+  on Windows.
+
+[0.5.0]: https://github.com/Thakay/sako/releases/tag/v0.5.0

sako-0.5.0/CONTRIBUTING.md

@@ -0,0 +1,132 @@
+# Contributing to SAKO
+
+SAKO is a task ledger and finish gate for coding agents. A useful change makes task
+ownership, evidence, recovery, or adoption more dependable while preserving the
+project's chosen workflow. A bug report, a result from your client, a documentation
+fix and code are all welcome.
+
+## Report a bug
+
+Open an issue with the bug form. Give the smallest reproduction, the expected and
+actual behavior, the versions the form asks for, and the command output that
+explains the failure. Use synthetic examples and remove private project details. To
+report a vulnerability, follow [SECURITY.md](SECURITY.md) instead.
+
+## Propose a change
+
+For new machinery, show the observed problem and why the existing task record,
+instructions, or commands cannot handle it. Keep planning practices replaceable.
+An external integration must define source identity, status ownership, and recovery.
+A change serves the finish gate, the ledger, installing, or leaving cleanly, and
+keeps to the [principles](README.md#why-it-stays-small); a change that serves none of
+these waits.
+
+A pull request explains the problem, the resulting behavior, how it was checked, and
+any compatibility limits. Follow the writing and commit rules in
+[AGENTS.md](AGENTS.md).
+
+## Design budgets
+
+Tests hold these limits. Over one, remove something before adding.
+
+| Budget | Limit |
+|---|---|
+| Install | One command, no required flags |
+| Reading for a normal task | About 1,500 words: the skill, the task template's preamble, a start context and the method's required part |
+| Required ledger columns | 8 at most |
+| Runtime | One standard-library file of at most 1,800 lines, counted with `wc -l sako.py` |
+
+## Work from a checkout
+
+Use Linux, WSL, macOS or Windows, Python 3.10 or newer, and Git 2.31 or newer; on
+Windows, run the checks from Git Bash, with `python` where they say `python3`. The
+runtime and the tests use Python's standard library; no package installation is
+needed. Read [SAKO.md](SAKO.md) before changing behavior.
+
+| Path | Purpose |
+|---|---|
+| [README.md](README.md) | The entry for people: what SAKO is, the quickstart, the footprints |
+| [SAKO.md](SAKO.md) | The method installed in each project, with its default planner |
+| [AGENTS.md](AGENTS.md) | Rules for agents changing this repository; `CLAUDE.md` imports it |
+| [SECURITY.md](SECURITY.md) | How to report a vulnerability, and what SAKO reads and sends |
+| `sako.py` | One Python file for records, presence, evidence, and installation |
+| `pyproject.toml` | Builds the `sako` package from this checkout |
+| `skills/sako/` | Optional agent entry to the installed method |
+| `templates/` | The empty task table |
+| `docs/` | Compatibility, the demo, the glossary, intake recipes, limits, moving to a tracker, update and removal, validation |
+| `tests/` | Unit, concurrent-process, adoption, recovery and documentation checks |
+| `.github/` | CI, the bug form and Dependabot |
+
+## Check the change
+
+From the checkout root:
+
+```sh
+PYTHONDONTWRITEBYTECODE=1 python3 -m unittest discover -s tests -v
+PYTHONDONTWRITEBYTECODE=1 python3 tests/selftest.py
+git diff --check
+```
+
+Run both suites on Python 3.10 when available; CI runs them on Linux, Windows and
+macOS. The scenario suite is also part of discovery, so the counts overlap. Tests use
+temporary repositories and process stand-ins: they do not establish live-client
+behavior or newcomer usability. Add a focused regression for a behavior bug.
+
+## Documentation
+
+- Each fact has one home; elsewhere, a sentence or two and a link. SAKO.md, the only
+  document installed in a project, is the home of behavior.
+- Document only behavior that exists, in the words the
+  [glossary](docs/glossary.md) defines: plain language, second person, present
+  tense. History belongs in Git, not in the docs; owner deliberations and internal
+  planning notes stay out.
+- The `Links` test in `tests/test_release.py` checks that every relative link and
+  heading anchor resolves, that the README's links to this repository point at real
+  files, and that no page has an em dash.
+- The [demo](docs/demo.md) is generated: after a change to what it shows, run
+  `PYTHONDONTWRITEBYTECODE=1 python3 tests/demo.py > docs/demo.md` and never edit
+  the page by hand.
+- Update [validation](docs/validation.md) when measured results or their scope
+  change; `PYTHONDONTWRITEBYTECODE=1 python3 tests/measure.py` reproduces the
+  measurements.
+
+## Build and try the package
+
+`pyproject.toml` installs the one runtime file as `sako/__init__.py` beside the
+method, the task template and the skill; nothing moves in the checkout. The wheel
+carries no tests or contributor documents. Building publishes nothing. To build it
+and try it in a fresh Git repository:
+
+```sh
+uv build
+wheel=$(ls -t "$PWD"/dist/sako-*.whl | head -1)
+sako_example=$(mktemp -d)
+git init "$sako_example" && cd "$sako_example"
+uvx --from "$wheel" sako init
+python3 .sako/sako.py next
+```
+
+A new repository has no sign of a client, so `init` installs the shared skill and no
+hooks, and says how to add them:
+
+```text
+Hooks: none, no client found here. Agents read .agents/skills/sako/SKILL.md; run start, check --gate and end yourself (python3 .sako/sako.py start --session <id>). Change the client with: uvx sako init --client claude|codex|none.
+```
+
+`next` then says nothing is ready and points to **No planner? Start here** in
+`.sako/SAKO.md`. [Update and removal](docs/update-and-remove.md) covers the rest of
+the kit's lifecycle.
+
+## AI-assisted contributions
+
+They are welcome under four rules: you reviewed the change and can explain it; both
+suites pass; you wrote the pull request description yourself; and each commit names
+the tools that helped, with a `Co-authored-by:` trailer as
+[AGENTS.md](AGENTS.md#commits) describes. No session links.
+
+## How the project runs
+
+One maintainer reviews and decides; decisions live in issues and pull requests.
+Expect a first reply within 7 days, and within 14 days for a security report. There
+is no contributor license agreement: under GitHub's terms of service, a contribution
+is licensed under the repository's MIT license.

sako-0.5.0/LICENSE

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

sako-0.5.0/PKG-INFO

@@ -0,0 +1,200 @@
+Metadata-Version: 2.5
+Name: sako
+Version: 0.5.0
+Summary: A task ledger and finish gate for coding agents
+Project-URL: Homepage, https://github.com/Thakay/sako
+Project-URL: Documentation, https://github.com/Thakay/sako/tree/main/docs
+Project-URL: Issues, https://github.com/Thakay/sako/issues
+Project-URL: Source, https://github.com/Thakay/sako
+Project-URL: Changelog, https://github.com/Thakay/sako/blob/main/CHANGELOG.md
+Author: Kasra Aminiyeganeh
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agentic development,claude code,codex,coding agents,finish gate,task ledger
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# SAKO
+
+SAKO helps you track coding-agent tasks and review the evidence behind finished
+work. It keeps tasks in a Markdown **ledger** and uses a **finish gate** to flag
+unrecorded changes, missing or stale check results, and finished work that needs a
+commit.
+
+If you use coding agents such as Claude Code or Codex in a Git repository, SAKO
+helps you keep track of who is working on what, what has been checked, and what a
+later session needs to pick up. You can use it with one agent or several sessions
+working in the same repository.
+
+SAKO fits alongside your planner, coding agent, and tests. Its focus is the link
+between a task and the evidence that it is finished: the gate reads Git and the
+latest check result, then points out gaps when a session stops. You choose the
+work and decide whether the result meets your needs. The records are plain
+Markdown, and the runtime is one Python file with no service or account to set up.
+
+SAKO stands for Simple Agentic Kit for Operations, pronounced "sah-ko".
+
+**Alpha:** commands and file formats can change in any 0.x release.
+
+## Quickstart
+
+You need Python 3.10 or newer, Git 2.31 or newer,
+[uv](https://docs.astral.sh/uv/getting-started/installation/), and a coding agent
+that can run commands. SAKO runs on Linux, WSL, macOS, and Windows.
+
+On Windows, use `python` wherever these instructions say `python3`. Check that
+`python --version` reports 3.10 or newer in Git Bash, where Claude Code runs
+SAKO's hooks
+([platform notes](https://github.com/Thakay/sako/blob/main/docs/limits.md#environment)).
+
+From your project's Git repository, install SAKO:
+
+```sh
+uvx sako init
+```
+
+In a project containing `CLAUDE.md`, the installer sets up Claude Code's hooks and
+prints:
+
+```text
+SAKO installed in .sako/ (local). Nothing tracked changed; the folder is listed in .git/info/exclude.
+Records: .sako/work/TASKS.md and DONE.md. They are not in Git yet; git clean -x deletes them.
+  Keep their history, or share them privately:  uvx sako init --repo [url]
+  Commit them with the code:                    uvx sako init --shared
+Hooks written: Claude Code (.claude/settings.local.json), chosen from CLAUDE.md. Start a session to begin. Change the client with: uvx sako init --client claude|codex|none.
+```
+
+Next, set your project's check command in `.sako/config.json`. For example, a
+Python project using unittest would set
+`"verify_command": ["python3", "-B", "-m", "unittest"]`. Use the command that checks
+your own project; `-B` in this example prevents Python from creating cache files
+during the check.
+
+Start a session in your coding client and ask for a change as usual. The start
+context gives your agent the instructions for recording and checking the work.
+SAKO sets up hooks for Claude Code and Codex when it detects them. Without hooks,
+the agent runs `start`, `check --gate`, and `end` itself. See
+[client compatibility](https://github.com/Thakay/sako/blob/main/docs/compatibility.md)
+for setup details.
+
+[What `init` changes](https://github.com/Thakay/sako/blob/main/docs/update-and-remove.md#what-init-changes)
+lists every file the installer writes. To uninstall while keeping your task
+records, run `python3 .sako/sako.py remove`.
+
+## Done means
+
+When a session stops, its hook checks that session's changes against three rules.
+The agent can also run the gate with `check --gate`:
+
+- **Recorded:** every changed file belongs to a task the session claimed or closed.
+- **Proven:** a task closed after checked content changed has a passing check for
+  that content. A missing or failed check never counts as a pass.
+- **Committed:** finished work is committed. If you keep the task records in Git,
+  they are committed too.
+
+Each finding explains how to fix the problem. You can pause unfinished work while
+keeping its task claimed.
+
+Every closed task gets a **receipt** in `.sako/work/DONE.md`, recording its
+completion condition, evidence, closing session, date, and check result. If no
+automated check is configured, the receipt says so.
+
+You still review and accept the result. A passing gate confirms that SAKO's rules
+were met; the [method](https://github.com/Thakay/sako/blob/main/SAKO.md#done-means)
+explains what they cover.
+
+## See a complete task
+
+[The demo](https://github.com/Thakay/sako/blob/main/docs/demo.md) follows a task
+from an unclaimed change through a failed check, a fix, a receipt, and a commit.
+A fresh session then picks up the next task from the records. It is a scripted
+run with real command output, kept in sync by a test.
+
+## SAKO is and is not
+
+SAKO handles task ownership and checks the evidence behind finished work. Here
+is how it fits with the rest of your tools:
+
+| SAKO provides | Where other tools fit |
+|---|---|
+| Task records in Markdown, linked to the source of the work | Your planner or spec process; SAKO includes a small default planner |
+| A finish gate connecting changed files, check results, and commits | Your tests and CI to check whether the code works |
+| Claims and scope checks for sessions in one repository and its worktrees | A scheduler if you want agents launched or assigned automatically |
+| Local records you can keep private or commit | A tracker for team sync or work across clones and machines |
+
+SAKO uses only Python's standard library and sends no telemetry. The gate prompts
+agents to fix gaps; it is not a security boundary. It blocks a stop once, and a
+repeated stop or a hook's own error lets the session end.
+
+## Where your records live
+
+Your task records live in `.sako/`. The **footprint** determines how you keep and
+share them:
+
+| Footprint | Command | What you get |
+|---|---|---|
+| Local, the default | `init` | Records stay outside Git. Useful for trying SAKO or working on one machine |
+| Repo | `init --repo [url]` | Records have their own Git history inside `.sako/`, with an optional remote for private sharing |
+| Shared | `init --shared` | Records live with your code, with a separate copy on each branch. The installer prints the commit command |
+
+Switching footprints preserves the records byte for byte.
+
+## As your project grows
+
+Start with one agent, one task, and the default planner. You can add more when
+your work calls for it:
+
+- **Bring an existing plan.** Use
+  [task intake](https://github.com/Thakay/sako/blob/main/docs/intake-recipes.md)
+  to turn your plan into tasks with priorities and references to their source.
+- **Work in parallel.** Claims and scope checks help coordinate sessions in the
+  same repository, including linked worktrees.
+- **Work across clones or machines.**
+  [Move task authority to a tracker](https://github.com/Thakay/sako/blob/main/docs/move-to-a-tracker.md).
+  Add a scheduler if you also need agents started and assigned for you.
+
+## Why it stays small
+
+1. **Keep evidence visible.** The gate reads Git and check results. A passing
+   check, a commit, and your acceptance each mean something different. You decide
+   whether the checks cover what the task needs to prove.
+2. **Give each fact one home.** Your planner holds intent, the ledger holds
+   ownership and evidence, and Git holds the changes. Source references connect
+   them without copying the plan. Plain Markdown keeps the records readable by
+   people, agents, and other tools.
+3. **Keep everyday use simple.** Install with one command and a short read. Bring
+   your own planner, agent, and checks; the agent runs the commands while you
+   guide the work and review the result.
+4. **Make adoption reversible.** The default install leaves tracked files alone.
+   Add history and sharing when you need them. Removal and migration instructions
+   help you keep your records when you move on.
+
+## Learn more
+
+- [SAKO.md](https://github.com/Thakay/sako/blob/main/SAKO.md): the method your agent follows
+- [Compatibility](https://github.com/Thakay/sako/blob/main/docs/compatibility.md): client setup and tested behavior
+- [Limits](https://github.com/Thakay/sako/blob/main/docs/limits.md): supported environments and boundaries
+- [Update and removal](https://github.com/Thakay/sako/blob/main/docs/update-and-remove.md): installation details, updates, and removal
+- [Validation](https://github.com/Thakay/sako/blob/main/docs/validation.md): guarantees and their evidence
+- [Glossary](https://github.com/Thakay/sako/blob/main/docs/glossary.md): terms used in the docs
+
+## Contributing, security and license
+
+Bug reports, client test results, and improvements are welcome. See
+[CONTRIBUTING.md](https://github.com/Thakay/sako/blob/main/CONTRIBUTING.md) to get
+started, and [SECURITY.md](https://github.com/Thakay/sako/blob/main/SECURITY.md) to
+report a vulnerability. SAKO is released under the
+[MIT license](https://github.com/Thakay/sako/blob/main/LICENSE).

sako-0.5.0/README.md

@@ -0,0 +1,171 @@
+# SAKO
+
+SAKO helps you track coding-agent tasks and review the evidence behind finished
+work. It keeps tasks in a Markdown **ledger** and uses a **finish gate** to flag
+unrecorded changes, missing or stale check results, and finished work that needs a
+commit.
+
+If you use coding agents such as Claude Code or Codex in a Git repository, SAKO
+helps you keep track of who is working on what, what has been checked, and what a
+later session needs to pick up. You can use it with one agent or several sessions
+working in the same repository.
+
+SAKO fits alongside your planner, coding agent, and tests. Its focus is the link
+between a task and the evidence that it is finished: the gate reads Git and the
+latest check result, then points out gaps when a session stops. You choose the
+work and decide whether the result meets your needs. The records are plain
+Markdown, and the runtime is one Python file with no service or account to set up.
+
+SAKO stands for Simple Agentic Kit for Operations, pronounced "sah-ko".
+
+**Alpha:** commands and file formats can change in any 0.x release.
+
+## Quickstart
+
+You need Python 3.10 or newer, Git 2.31 or newer,
+[uv](https://docs.astral.sh/uv/getting-started/installation/), and a coding agent
+that can run commands. SAKO runs on Linux, WSL, macOS, and Windows.
+
+On Windows, use `python` wherever these instructions say `python3`. Check that
+`python --version` reports 3.10 or newer in Git Bash, where Claude Code runs
+SAKO's hooks
+([platform notes](https://github.com/Thakay/sako/blob/main/docs/limits.md#environment)).
+
+From your project's Git repository, install SAKO:
+
+```sh
+uvx sako init
+```
+
+In a project containing `CLAUDE.md`, the installer sets up Claude Code's hooks and
+prints:
+
+```text
+SAKO installed in .sako/ (local). Nothing tracked changed; the folder is listed in .git/info/exclude.
+Records: .sako/work/TASKS.md and DONE.md. They are not in Git yet; git clean -x deletes them.
+  Keep their history, or share them privately:  uvx sako init --repo [url]
+  Commit them with the code:                    uvx sako init --shared
+Hooks written: Claude Code (.claude/settings.local.json), chosen from CLAUDE.md. Start a session to begin. Change the client with: uvx sako init --client claude|codex|none.
+```
+
+Next, set your project's check command in `.sako/config.json`. For example, a
+Python project using unittest would set
+`"verify_command": ["python3", "-B", "-m", "unittest"]`. Use the command that checks
+your own project; `-B` in this example prevents Python from creating cache files
+during the check.
+
+Start a session in your coding client and ask for a change as usual. The start
+context gives your agent the instructions for recording and checking the work.
+SAKO sets up hooks for Claude Code and Codex when it detects them. Without hooks,
+the agent runs `start`, `check --gate`, and `end` itself. See
+[client compatibility](https://github.com/Thakay/sako/blob/main/docs/compatibility.md)
+for setup details.
+
+[What `init` changes](https://github.com/Thakay/sako/blob/main/docs/update-and-remove.md#what-init-changes)
+lists every file the installer writes. To uninstall while keeping your task
+records, run `python3 .sako/sako.py remove`.
+
+## Done means
+
+When a session stops, its hook checks that session's changes against three rules.
+The agent can also run the gate with `check --gate`:
+
+- **Recorded:** every changed file belongs to a task the session claimed or closed.
+- **Proven:** a task closed after checked content changed has a passing check for
+  that content. A missing or failed check never counts as a pass.
+- **Committed:** finished work is committed. If you keep the task records in Git,
+  they are committed too.
+
+Each finding explains how to fix the problem. You can pause unfinished work while
+keeping its task claimed.
+
+Every closed task gets a **receipt** in `.sako/work/DONE.md`, recording its
+completion condition, evidence, closing session, date, and check result. If no
+automated check is configured, the receipt says so.
+
+You still review and accept the result. A passing gate confirms that SAKO's rules
+were met; the [method](https://github.com/Thakay/sako/blob/main/SAKO.md#done-means)
+explains what they cover.
+
+## See a complete task
+
+[The demo](https://github.com/Thakay/sako/blob/main/docs/demo.md) follows a task
+from an unclaimed change through a failed check, a fix, a receipt, and a commit.
+A fresh session then picks up the next task from the records. It is a scripted
+run with real command output, kept in sync by a test.
+
+## SAKO is and is not
+
+SAKO handles task ownership and checks the evidence behind finished work. Here
+is how it fits with the rest of your tools:
+
+| SAKO provides | Where other tools fit |
+|---|---|
+| Task records in Markdown, linked to the source of the work | Your planner or spec process; SAKO includes a small default planner |
+| A finish gate connecting changed files, check results, and commits | Your tests and CI to check whether the code works |
+| Claims and scope checks for sessions in one repository and its worktrees | A scheduler if you want agents launched or assigned automatically |
+| Local records you can keep private or commit | A tracker for team sync or work across clones and machines |
+
+SAKO uses only Python's standard library and sends no telemetry. The gate prompts
+agents to fix gaps; it is not a security boundary. It blocks a stop once, and a
+repeated stop or a hook's own error lets the session end.
+
+## Where your records live
+
+Your task records live in `.sako/`. The **footprint** determines how you keep and
+share them:
+
+| Footprint | Command | What you get |
+|---|---|---|
+| Local, the default | `init` | Records stay outside Git. Useful for trying SAKO or working on one machine |
+| Repo | `init --repo [url]` | Records have their own Git history inside `.sako/`, with an optional remote for private sharing |
+| Shared | `init --shared` | Records live with your code, with a separate copy on each branch. The installer prints the commit command |
+
+Switching footprints preserves the records byte for byte.
+
+## As your project grows
+
+Start with one agent, one task, and the default planner. You can add more when
+your work calls for it:
+
+- **Bring an existing plan.** Use
+  [task intake](https://github.com/Thakay/sako/blob/main/docs/intake-recipes.md)
+  to turn your plan into tasks with priorities and references to their source.
+- **Work in parallel.** Claims and scope checks help coordinate sessions in the
+  same repository, including linked worktrees.
+- **Work across clones or machines.**
+  [Move task authority to a tracker](https://github.com/Thakay/sako/blob/main/docs/move-to-a-tracker.md).
+  Add a scheduler if you also need agents started and assigned for you.
+
+## Why it stays small
+
+1. **Keep evidence visible.** The gate reads Git and check results. A passing
+   check, a commit, and your acceptance each mean something different. You decide
+   whether the checks cover what the task needs to prove.
+2. **Give each fact one home.** Your planner holds intent, the ledger holds
+   ownership and evidence, and Git holds the changes. Source references connect
+   them without copying the plan. Plain Markdown keeps the records readable by
+   people, agents, and other tools.
+3. **Keep everyday use simple.** Install with one command and a short read. Bring
+   your own planner, agent, and checks; the agent runs the commands while you
+   guide the work and review the result.
+4. **Make adoption reversible.** The default install leaves tracked files alone.
+   Add history and sharing when you need them. Removal and migration instructions
+   help you keep your records when you move on.
+
+## Learn more
+
+- [SAKO.md](https://github.com/Thakay/sako/blob/main/SAKO.md): the method your agent follows
+- [Compatibility](https://github.com/Thakay/sako/blob/main/docs/compatibility.md): client setup and tested behavior
+- [Limits](https://github.com/Thakay/sako/blob/main/docs/limits.md): supported environments and boundaries
+- [Update and removal](https://github.com/Thakay/sako/blob/main/docs/update-and-remove.md): installation details, updates, and removal
+- [Validation](https://github.com/Thakay/sako/blob/main/docs/validation.md): guarantees and their evidence
+- [Glossary](https://github.com/Thakay/sako/blob/main/docs/glossary.md): terms used in the docs
+
+## Contributing, security and license
+
+Bug reports, client test results, and improvements are welcome. See
+[CONTRIBUTING.md](https://github.com/Thakay/sako/blob/main/CONTRIBUTING.md) to get
+started, and [SECURITY.md](https://github.com/Thakay/sako/blob/main/SECURITY.md) to
+report a vulnerability. SAKO is released under the
+[MIT license](https://github.com/Thakay/sako/blob/main/LICENSE).