subroutine 0.1.0__tar.gz

subroutine-0.1.0/.claude-plugin/marketplace.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "https://anthropic.com/claude-code/marketplace.schema.json",
+  "name": "subroutine",
+  "description": "Project management for people and agents, in equal measure.",
+  "owner": {
+    "name": "Simon Holliday",
+    "email": "simon.holliday@protonmail.com"
+  },
+  "plugins": [
+    {
+      "name": "subroutine",
+      "source": "./plugins/subroutine",
+      "description": "Give Claude a shared, durable task list: file work, find what is ready, record what happened, and leave the next session something to read. Needs Subroutine itself installed separately — 'pip install subroutine', then 'subroutine init'.",
+      "author": {
+        "name": "Simon Holliday",
+        "email": "simon.holliday@protonmail.com"
+      },
+      "category": "productivity",
+      "keywords": [
+        "tasks",
+        "project-management",
+        "todo",
+        "self-hosted",
+        "planning"
+      ],
+      "homepage": "https://github.com/simonholliday/subroutine"
+    }
+  ]
+}

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

@@ -0,0 +1,221 @@
+name: CI
+
+# Two jobs rather than one matrix doing everything. Lint and type results are identical on
+# every Python version, so running them three times would add nothing but three places to
+# read the same failure.
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ci-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  PIP_DISABLE_PIP_VERSION_CHECK: "1"
+
+jobs:
+  checks:
+    name: Lint and types
+    runs-on: ubuntu-latest
+
+    steps:
+      # Full history and tags, because the release check compares this commit's migration
+      # head against the one at the most recent tag. A shallow clone has neither, and the
+      # check would find no previous tag and cheerfully pass every time.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: python -m pip install -e '.[dev,postgres]'
+
+      # `ruff check` only. `ruff format` would strip the space in `def foo (x)` and
+      # re-indent the whole codebase with spaces — it is not a formatter on this project.
+      - name: Ruff
+        run: ruff check .
+
+      - name: Mypy
+        run: mypy src tests scripts
+
+      # A release that moves the schema has to say so in CHANGELOG.md, so that somebody can
+      # *plan* the database upgrade rather than meet one halfway through installing
+      # something (SPEC.md §12.4a). Derived from the migration directory rather than from
+      # anybody remembering at release time, which is when nobody does.
+      - name: Release notes
+        run: python scripts/check_release_notes.py
+
+  # Subroutine is AGPL and is also offered commercially, and both rest on being able to
+  # grant rights in the whole of what ships. A copyleft dependency takes that away, and it
+  # will arrive inside somebody else's requirements rather than as a decision anybody
+  # makes. Separate job with a clean install: development tools are not distributed, so a
+  # GPL linter constrains nothing and should not fail this.
+  licences:
+    name: Dependency licences
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      # `packaging` is the script's own tool for walking the closure, not a dependency of
+      # Subroutine — it is installed here rather than declared, so it never ships.
+      - name: Install runtime dependencies only
+        run: python -m pip install '.[postgres]' packaging
+
+      - name: Check
+        run: python scripts/check_licences.py
+
+  # Checked by the tool that will read them (SPEC.md §21). `tests/test_plugin.py` covers what
+  # the manifests must *say* — that the version matches the package, that every declared option
+  # is substituted somewhere, that the token is held as a secret. Only Claude Code itself can
+  # say whether they conform to its schema, and a manifest that does not is one nobody can
+  # install at all.
+  #
+  # Its own job rather than a step in `checks`, because it needs a Node package the rest of the
+  # build has no use for. Jobs run in parallel, so this costs nothing on the clock and does not
+  # slow the lint feedback everybody actually waits for.
+  plugin:
+    name: Plugin manifests
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22"
+
+      - name: Install Claude Code
+        run: npm install -g @anthropic-ai/claude-code
+
+      - name: Validate
+        run: |
+          claude plugin validate .
+          claude plugin validate ./plugins/subroutine
+
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        # Without this the suite can start before the server accepts connections, and the
+        # PostgreSQL half would skip rather than fail — see SUBROUTINE_TEST_REQUIRE_POSTGRES.
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: python -m pip install -e '.[dev,postgres]'
+
+      # The whole suite runs twice, once per backend. The drift check that compares the
+      # models against the migration head is one of those tests, and it is the reason this
+      # job matters more than it looks: portability breaks are caught on the day they are
+      # introduced rather than at the first PostgreSQL deployment.
+      - name: Tests on SQLite and PostgreSQL
+        env:
+          SUBROUTINE_TEST_POSTGRES_ADMIN_URL: postgresql+psycopg://postgres:postgres@localhost:5432/postgres
+          SUBROUTINE_TEST_REQUIRE_POSTGRES: "1"
+        run: pytest -q
+
+  # Proves the thing a new user actually does, on a clean machine with nothing configured:
+  # install the package, run one command, get a working database. It is separate from the
+  # test job because it must not see the repository's test fixtures or a pre-made database.
+  first-run:
+    name: First run
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install as a user would
+        run: python -m pip install .
+
+      - name: subroutine init
+        run: |
+          set -euo pipefail
+          output="$(subroutine init 2>&1)"
+          echo "$output"
+          expected='Ready. Try: subroutine add "something to do"'
+          if [ "$output" != "$expected" ]; then
+            echo "init printed something other than its one line" >&2
+            exit 1
+          fi
+
+      - name: The database is queryable afterwards
+        run: |
+          set -euo pipefail
+          subroutine db current | grep -q '^Schema is at '
+          subroutine init | grep -q 'Already set up'
+
+      # SPEC.md §13.5b, the gating criterion for M2: a fresh installation to a working
+      # to-do list in three commands and a completed task in a fourth, with none of the
+      # output mentioning a workspace, a status, a project, a criterion, a verification, a
+      # session or a claim. The suite runs this too; it runs here as well because this job
+      # is the only one with nothing configured and no fixtures — which is the state the
+      # person it is written about is actually in.
+      - name: The personal test
+        run: |
+          set -euo pipefail
+          # `2>&1` on every one of them, because a warning is as visible to the person as
+          # an answer is. Capturing stdout alone is what let a checkout marker greet a
+          # stranger with the words *workspace* and *project* while this job reported
+          # success (`SR#219`, `SR#222`).
+          subroutine add "Call the dentist before Sunday" 2>&1 | tee /tmp/add.txt
+          subroutine today 2>&1 | tee /tmp/today.txt
+          subroutine done 1 2>&1 | tee /tmp/done.txt
+          grep -q 'Added: Call the dentist' /tmp/add.txt
+          grep -q 'Call the dentist' /tmp/today.txt
+          grep -q 'Done: Call the dentist' /tmp/done.txt
+          if grep -Eiq 'workspace|status|project|criterion|verification|session|claim' \
+              /tmp/add.txt /tmp/today.txt /tmp/done.txt; then
+            echo "The personal path mentioned something §1.4 says it must not." >&2
+            exit 1
+          fi

subroutine-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,178 @@
+name: Release
+
+# Publishing is the one act here that cannot be undone: PyPI refuses a version it has already
+# seen, even after a deletion, so a broken 0.1.0 is not fixed but abandoned. Everything in this
+# file exists to spend that single attempt well — the suite runs, the metadata is checked, and
+# the tag is made to agree with the version.
+#
+# **A failed upload spends nothing; only a successful upload of a bad artefact does.** That is
+# why TestPyPI is a rehearsal somebody asks for rather than a gate on the way through. What it
+# proves is the OIDC handshake, and if that is misconfigured the real upload simply fails and is
+# retried; what it does not prove is the artefact, which `twine check` and a clean install from
+# the built wheel already cover. Registering a publisher there is a separate account and a
+# separate act, so a release must not wait on one.
+#
+# Hence: a **tag** publishes to PyPI, a **manual** run rehearses on TestPyPI, and neither can do
+# the other's job by accident.
+#
+# No stored credential anywhere. Both uploads authenticate by OIDC against a trusted publisher
+# (SPEC.md §2.2), which is why each publishing job asks for `id-token: write` and nothing else
+# does.
+
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  # CI runs on pushes to main, and a tag is not one — so without this a release could publish
+  # code no suite ever saw. One version rather than the full matrix: this is a gate on the
+  # artefact, not the compatibility run that already happened on the commit.
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+
+    services:
+      postgres:
+        image: postgres:16
+        env:
+          POSTGRES_USER: postgres
+          POSTGRES_PASSWORD: postgres
+          POSTGRES_DB: postgres
+        ports:
+          - 5432:5432
+        options: >-
+          --health-cmd "pg_isready -U postgres"
+          --health-interval 5s
+          --health-timeout 5s
+          --health-retries 10
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+          cache: pip
+          cache-dependency-path: pyproject.toml
+
+      - name: Install
+        run: python -m pip install -e '.[dev,postgres]'
+
+      # Both backends, and an unreachable PostgreSQL is a failure rather than a skip — a
+      # release verified on half a test run is not verified.
+      - name: Tests on SQLite and PostgreSQL
+        env:
+          SUBROUTINE_TEST_POSTGRES_ADMIN_URL: postgresql+psycopg://postgres:postgres@localhost:5432/postgres
+          SUBROUTINE_TEST_REQUIRE_POSTGRES: "1"
+        run: pytest
+
+  build:
+    name: Build
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+      # Full history and tags: `check_release_notes.py` compares this commit's migration head
+      # against the head at the previous tag, and a shallow clone has neither.
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      # Subroutine itself as well as the build tools, because `check_release_notes.py` reads
+      # the migration head through `subroutine.db.migrate` rather than by parsing files — the
+      # asymmetry that script's own docstring argues for. Installing only `build` and `twine`
+      # left it with `ModuleNotFoundError: No module named 'subroutine'`, which passed every
+      # local check because a shell that can run the script already has the package (`SR#230`).
+      - name: Install the build tools, and Subroutine itself
+        run: python -m pip install -e . build twine
+
+      - name: Build the wheel and the sdist
+        run: python -m build
+
+      - name: Check the metadata
+        run: twine check dist/*
+
+      # The tag says which release this is and `pyproject.toml` says what will be uploaded
+      # under that name. If they disagree, the thing published is not the thing the tag names
+      # — and this is the last moment that mistake costs nothing.
+      - name: The tag names the version being built
+        if: startsWith(github.ref, 'refs/tags/')
+        run: |
+          set -euo pipefail
+          tagged="${GITHUB_REF_NAME#v}"
+          built="$(python -c 'import pathlib, tomllib; print(tomllib.loads(pathlib.Path("pyproject.toml").read_text())["project"]["version"])')"
+          if [ "$tagged" != "$built" ]; then
+            echo "the tag $GITHUB_REF_NAME does not name version $built" >&2
+            exit 1
+          fi
+          echo "tag and version agree on $built"
+
+      # A release that moves the schema has to say so in the changelog (SPEC.md §12.4a). CI
+      # checks this on every commit; it is checked again here because this is the run where
+      # being wrong reaches somebody else's database.
+      - name: Release notes
+        run: python scripts/check_release_notes.py
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  # The rehearsal: same artefacts, same mechanism, a registry where a mistake costs nothing —
+  # run when somebody asks for it. Skipped entirely on a tag, so a release is never held up for
+  # the want of a publisher registered on a different site.
+  testpypi:
+    name: TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+
+    environment:
+      name: testpypi
+      url: https://test.pypi.org/p/subroutine
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  # `push` can only mean a tag here, since that is this workflow's only push trigger — so the
+  # condition says "a release, not a rehearsal" rather than restating the trigger. Guarded by
+  # the `pypi` environment as well, so a required reviewer on it makes the upload a decision
+  # somebody takes rather than a consequence of pushing a tag.
+  pypi:
+    name: PyPI
+    needs: build
+    if: github.event_name == 'push'
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/subroutine
+
+    permissions:
+      id-token: write
+
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - uses: pypa/gh-action-pypi-publish@release/v1

subroutine-0.1.0/.gitignore

@@ -0,0 +1,53 @@
+# Python
+__pycache__/
+*.py[cod]
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+
+# Virtualenvs — the house convention keeps these outside the tree, but guard anyway
+.venv/
+venv/
+env/
+
+# Tooling caches
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+
+# Local data — a stray `subroutine init` in the working tree must never be committed
+*.db
+*.db-wal
+*.db-shm
+*.sqlite3
+/data/
+/instance/
+
+# Secrets and local configuration
+.env
+.env.*
+config.local.toml
+
+# Editors
+.idea/
+*.swp
+.DS_Store
+
+# Local documentation
+CLAUDE.md
+COMPETITIVE-ANALYSIS.md
+SPEC.md
+MVP-PLAN.md
+reviews
+
+# Committing this is right for a team sharing one instance, and wrong here: a clone of
+# *Subroutine itself* goes to strangers who share nothing, and the marker would name a
+# workspace and a project that exist on no machine but ours (`SR#219`).
+.subroutine

subroutine-0.1.0/CHANGELOG.md

@@ -0,0 +1,76 @@
+# Changelog
+
+Notable changes, newest first. Dates are the date of the release.
+
+**A release that changes the database schema says so at the top of its own section**, and CI
+fails if it does not. `scripts/check_release_notes.py` compares the migration head against the
+most recent tag rather than trusting anybody to remember, so the notice appears in the
+unreleased section on the day the migration lands — written by whoever wrote the migration, not
+by whoever cuts the release in a hurry three weeks later. `--emit` prints the wording.
+
+The point of it is that you can *plan* a database upgrade instead of meeting one halfway
+through installing something. See [docs/hosting.md](docs/hosting.md#upgrading) for what the
+upgrade involves.
+
+## 0.1.0 — 2026-08-01
+
+The first public release. Everything here is new, so this section says what exists rather than
+what changed.
+
+No migration notice: there is no previous release to upgrade from, and a fresh install builds
+its schema outright with `subroutine init`.
+
+### A personal to-do list
+
+- `subroutine init`, `add`, `today`, `done`, `plan`, `defer`, `list`, `search`, `show`,
+  `comment`, `project create`, `project list` and `doc create`. Three commands from install to
+  a working list, and a fourth to tick something off.
+- Quick capture: `subroutine add "Fix the deploy script by friday !4/2 ~2h #ops"` sets the
+  deadline, both priority axes, the estimate and a tag from the line you already type.
+- Items are addressed by a number allocated once and never reused, so it goes on meaning that
+  item after you have finished a dozen others.
+- `subroutine start` and `subroutine stop`, so the list can say what you are in the middle of.
+- `subroutine link 42 blocks 43` and `subroutine unlink`. `--ready` reads those links, so
+  this is how that filter learns anything.
+- `subroutine delete` and `subroutine restore`, with `list --trash` to see what is in there.
+  Deleting is soft, so the wrong number costs nothing.
+- `subroutine list --ready` shows only work that can actually be started — nothing unfinished
+  blocks it and it is not deferred. It is the question a backlog cannot answer.
+- `subroutine help` and `subroutine --help` do the same thing: they list the commands.
+  `subroutine explain` covers the ideas behind them — dates, refs, the capture shorthand.
+
+### An HTTP API, and agents as first-class users
+
+- The HTTP API under `/v1`, with the same data model and the same permission checks the
+  CLI uses. `GET /v1/docs/agent` is the guide an agent should read first.
+- Scoped bearer tokens: an agent's credential can be narrower than the person who issued it,
+  and may never be wider. Per-workspace pins and per-permission scopes.
+- `subroutine token create --username ana` issues for a person, `--service-account claude` for
+  a machine identity, creating it as it goes. Two flags because they are two decisions, and
+  neither will issue a credential for an account that could not use it.
+- `subroutine mcp` serves the same instance over the Model Context Protocol, in nine tools —
+  including `link` and `project`, so an agent can say what blocks what and file its own work.
+- **A Claude Code plugin**, which wires those tools up and carries a skill describing the
+  practice — including how to adopt Subroutine in a project that does not use it yet.
+- Attribution on everything, a comment thread per item, and a history of every change.
+
+### Running it
+
+- `subroutine serve` listens on loopback and refuses a wider bind without TLS in front of it.
+- SQLite by default with no configuration; PostgreSQL with the `postgres` extra.
+- `subroutine upgrade` — reports both schema versions, takes a verified backup, migrates, then
+  reads the result back. It does not install software, deliberately.
+- Backups to a directory of your choosing, verified where they land, and a restore that makes
+  you say whether it is a recovery or a clone.
+- Separate instances on one machine with `--profile`, isolated across all three XDG roots.
+
+### Known limits
+
+Session handoffs, verification evidence and claims are specified and not built — as are
+attachments, calendar feeds, recurring tasks, a `GET /v1/changes` feed, and manual reordering.
+There is no web UI.
+
+Two of those are *refused out loud* rather than merely absent, which is worth telling apart:
+the capture grammar recognises `every monday` well enough to leave it in your title and say it
+did nothing with it, and a calendar credential presented to the API is turned down by name.
+The rest are simply not there yet.

subroutine-0.1.0/CLA.md

@@ -0,0 +1,78 @@
+# Subroutine Contributor Licence Agreement
+
+Adapted from the Apache Software Foundation Individual Contributor Licence Agreement
+v2.0. Version 1.0, dated 2026-07-29.
+
+You agree to this by saying so in your pull request:
+
+> I have read the CLA document and I hereby agree to its terms.
+
+## Why this exists
+
+Subroutine is published under AGPL-3.0-or-later and is also offered under a commercial
+licence by separate agreement. Offering both requires the ability to grant rights in the
+whole of the code, including your contribution. This document is how you grant those
+rights.
+
+**You keep your copyright.** This is a licence, not an assignment. Your contribution
+remains yours and you may use it however you wish, elsewhere and for any purpose.
+
+## Agreement
+
+By contributing to Subroutine you accept the following terms for your present and future
+contributions. If you do not agree, please do not contribute.
+
+**1. Definitions.** "You" means the copyright owner, or the person legally authorised by
+the copyright owner, entering into this agreement. "The Project Owner" means Simon
+Holliday. "Contribution" means any original work of authorship, including any changes or
+additions to existing work, that You intentionally submit to the Project Owner for
+inclusion in Subroutine. "Submit" means any form of communication sent to the Project
+Owner or its representatives, including but not limited to source control systems, issue
+trackers and mailing lists, but excluding communication conspicuously marked "Not a
+Contribution".
+
+**2. Grant of copyright licence.** You grant to the Project Owner, and to recipients of
+software distributed by the Project Owner, a perpetual, worldwide, non-exclusive,
+royalty-free, irrevocable copyright licence to reproduce, prepare derivative works of,
+publicly display, publicly perform, sublicense and distribute Your Contributions and
+such derivative works.
+
+This licence expressly includes the right to sublicense and distribute Your Contributions
+**under any licence terms, including proprietary terms**, whether or not those terms are
+the ones under which Subroutine is currently published. This is the clause that makes
+commercial licensing of Subroutine possible, and it is the reason this document exists.
+
+**3. Grant of patent licence.** You grant to the Project Owner, and to recipients of
+software distributed by the Project Owner, a perpetual, worldwide, non-exclusive,
+royalty-free, irrevocable patent licence to make, have made, use, offer to sell, sell,
+import and otherwise transfer Subroutine. This applies only to those patent claims
+licensable by You that are necessarily infringed by Your Contribution alone or by its
+combination with Subroutine.
+
+If any entity brings patent litigation alleging that Subroutine, or a Contribution
+incorporated within it, constitutes direct or contributory patent infringement, any
+patent licences granted to that entity under this agreement terminate as of the date the
+litigation is filed.
+
+**4. You have the right to grant this.** You represent that You are legally entitled to
+grant the above licences, and that each of Your Contributions is Your original creation.
+If Your employer has rights to intellectual property You create, You represent that You
+have received permission to make the Contributions on behalf of that employer, that Your
+employer has waived such rights, or that Your employer has executed a separate agreement
+with the Project Owner.
+
+**5. Work that is not Yours.** You may submit work that is not Your original creation
+only if it is clearly identified as such, complete with its source and any licence or
+other restriction attached to it. Mark it conspicuously as "Submitted on behalf of a
+third party: [named here]".
+
+**6. No warranty and no obligation.** You are not expected to provide support for Your
+Contributions. Except for the representations in section 4, and unless required by
+applicable law or agreed in writing, You provide Your Contributions on an "AS IS" basis,
+without warranties or conditions of any kind, either express or implied, including
+without limitation any warranty of title, non-infringement, merchantability or fitness
+for a particular purpose.
+
+**7. Tell us if something changes.** You agree to notify the Project Owner if You become
+aware of any fact or circumstance that would make any of these representations inaccurate
+in any respect.