solo-sdd 0.2.0__tar.gz

solo_sdd-0.2.0/.gitattributes

@@ -0,0 +1 @@
+docs/waiting.md merge=union

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

@@ -0,0 +1,162 @@
+name: release
+
+# A pushed tag v<version> on a main commit: the tests, the release check, then the same dist/ files to PyPI and npm
+# through trusted publishing, then a GitHub release whose text is the CHANGELOG.md section of the version.
+# The one-time registry setup: docs/release.md.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release-${{ github.ref }}
+  cancel-in-progress: false
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    steps:
+      # actions/checkout v4.4.0
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+        with:
+          fetch-depth: 0
+      - name: Public repository
+        # npm provenance and the README links on the registry pages need a public repository.
+        run: |
+          if [ "${{ github.event.repository.private }}" = "true" ]; then
+            echo "fail repository $GITHUB_REPOSITORY is private: make it public before a release (docs/release.md)"
+            exit 1
+          fi
+      - name: Tag on main
+        run: |
+          if ! git merge-base --is-ancestor "$GITHUB_SHA" origin/main; then
+            echo "fail tag $GITHUB_REF_NAME: commit $GITHUB_SHA is not on main"
+            exit 1
+          fi
+      # actions/setup-node v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "22"
+      - name: Install build tools
+        run: /usr/bin/python3 -m pip install --user --break-system-packages build twine hypothesis
+      - name: Run tests
+        run: |
+          /usr/bin/python3 tests/run.py --tier release < /dev/null
+      - name: Validate the process tree
+        run: |
+          if [ -d solo-sdd ]; then /usr/bin/python3 -m solo_sdd validate --all < /dev/null; else echo "no solo-sdd/: nothing to check"; fi
+      - name: Release check
+        run: /usr/bin/python3 scripts/release_check.py "$GITHUB_REF_NAME"
+      - name: Registry metadata
+        run: /usr/bin/python3 -m twine check --strict dist/*.tar.gz dist/*.whl
+      - name: Release text
+        run: |
+          mkdir -p "$RUNNER_TEMP/notes"
+          /usr/bin/python3 scripts/release_check.py --notes "$GITHUB_REF_NAME" > "$RUNNER_TEMP/notes/notes.md"
+      # actions/upload-artifact v4.6.2
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+          overwrite: true
+      # actions/upload-artifact v4.6.2
+      - uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02
+        with:
+          name: notes
+          path: ${{ runner.temp }}/notes/
+          if-no-files-found: error
+          overwrite: true
+
+  pypi:
+    needs: check
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/solo-sdd/
+    permissions:
+      id-token: write
+    steps:
+      # actions/download-artifact v4.3.0
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: dist
+          path: dist
+      - name: Already published
+        run: |
+          v="${GITHUB_REF_NAME#v}"
+          code=$(curl -s -o /dev/null -w '%{http_code}' "https://pypi.org/pypi/solo-sdd/$v/json")
+          if [ "$code" = 200 ]; then
+            echo "solo-sdd $v is already published on PyPI: only missing files are uploaded"
+          else
+            echo "solo-sdd $v is not on PyPI yet (HTTP $code)"
+          fi
+          rm -f dist/*.tgz
+      # Runs even when the version is there: skip-existing uploads only the files PyPI lacks (a run that stopped halfway).
+      # pypa/gh-action-pypi-publish v1.14.3, the head of release/v1 on 2026-11-10
+      - uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086
+        with:
+          packages-dir: dist/
+          skip-existing: true
+
+  npm:
+    needs: check
+    runs-on: ubuntu-latest
+    environment:
+      name: npm
+      url: https://www.npmjs.com/package/solo-sdd
+    permissions:
+      id-token: write
+    steps:
+      # actions/download-artifact v4.3.0
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: dist
+          path: dist
+      # actions/setup-node v4.4.0
+      - uses: actions/setup-node@49933ea5288caeca8642d1e84afbd3f7d6820020
+        with:
+          node-version: "24"
+      - name: npm with trusted publishing
+        run: npm install -g npm@^11.5.1 && npm --version
+      - name: Publish
+        env:
+          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          v="${GITHUB_REF_NAME#v}"
+          if npm view "solo-sdd@$v" version > /dev/null 2>&1; then
+            echo "solo-sdd $v is already published on npm"
+            exit 0
+          fi
+          # NPM_TOKEN only for the first publish, before the trusted publisher exists (docs/release.md).
+          if [ -n "$NPM_TOKEN" ]; then npm config set //registry.npmjs.org/:_authToken "$NPM_TOKEN"; fi
+          npm publish "./dist/solo-sdd-$v.tgz" --provenance --access public
+
+  github-release:
+    needs: [pypi, npm]
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      # actions/download-artifact v4.3.0
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: dist
+          path: dist
+      # actions/download-artifact v4.3.0
+      - uses: actions/download-artifact@d3f86a106a0bac45b974a628896c90dbdf5c8093
+        with:
+          name: notes
+          path: notes
+      - name: Release with the three files and the CHANGELOG section
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if gh release view "$GITHUB_REF_NAME" -R "$GITHUB_REPOSITORY" > /dev/null 2>&1; then
+            gh release upload "$GITHUB_REF_NAME" dist/* --clobber -R "$GITHUB_REPOSITORY"
+          else
+            gh release create "$GITHUB_REF_NAME" dist/* --notes-file notes/notes.md --verify-tag -R "$GITHUB_REPOSITORY"
+          fi

solo_sdd-0.2.0/.github/workflows/test.yml

@@ -0,0 +1,54 @@
+name: test
+
+# Ubuntu on a push to main and on a PR; macOS, whose minutes cost more, only on a v* tag; both on a manual run.
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: ${{ fromJSON(github.event_name == 'workflow_dispatch' && '["ubuntu-latest", "macos-latest"]' || startsWith(github.ref, 'refs/tags/') && '["macos-latest"]' || '["ubuntu-latest"]') }}
+    runs-on: ${{ matrix.os }}
+    steps:
+      # actions/checkout v4.4.0
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262
+      - name: Install Hypothesis, build and pyflakes
+        run: /usr/bin/python3 -m pip install --user --break-system-packages hypothesis build pyflakes==3.4.0 || /usr/bin/python3 -m pip install --user hypothesis build pyflakes==3.4.0
+      - name: Lint
+        run: /usr/bin/python3 -m pyflakes solo_sdd global scripts sync.py
+      - name: Run tests
+        if: ${{ !startsWith(github.ref, 'refs/tags/') && github.event_name != 'workflow_dispatch' }}
+        run: |
+          /usr/bin/python3 tests/run.py --tier slow < /dev/null
+      - name: Run tests, release tier
+        if: ${{ startsWith(github.ref, 'refs/tags/') || github.event_name == 'workflow_dispatch' }}
+        run: |
+          /usr/bin/python3 tests/run.py --tier release < /dev/null
+      - name: Validate the process tree
+        run: |
+          if [ -d solo-sdd ]; then /usr/bin/python3 -m solo_sdd validate --all < /dev/null; else echo "no solo-sdd/: nothing to check"; fi
+      - name: Wheel install smoke
+        run: |
+          /usr/bin/python3 -m pip wheel . --no-deps -w dist
+          /usr/bin/python3 -m venv "$RUNNER_TEMP/wheelenv"
+          "$RUNNER_TEMP/wheelenv/bin/pip" install dist/solo_sdd-*.whl
+          "$RUNNER_TEMP/wheelenv/bin/solo-sdd" --version
+      - name: npm tarball smoke
+        run: |
+          npm pack --pack-destination "$RUNNER_TEMP"
+          npm i -g --prefix "$RUNNER_TEMP/npm" "$RUNNER_TEMP"/solo-sdd-*.tgz
+          "$RUNNER_TEMP/npm/bin/solo-sdd" --version

solo_sdd-0.2.0/.gitignore

@@ -0,0 +1,43 @@
+__pycache__/
+*.pyc
+.DS_Store
+.hypothesis/
+
+# local agent settings
+.claude/
+.codex/
+
+# secrets
+.env
+.env.*
+!.env.example
+
+# environment (no /: in a worktree these are links)
+.venv
+node_modules
+
+# release files built by scripts/release_check.py
+dist/
+
+# the failed files of the last tests/run.py
+tests/.last-failed
+
+# logs
+*.log
+
+# the change archive: kept only in the working folder, not published
+solo-sdd/changes/archive/
+
+# single owner, not part of solo-sdd development
+docs/debug-profile.md
+docs/process-safety-verification.md
+docs/rules-audit.md
+docs/waiting.md
+global/claude-gui.py
+global/claude-process-safety-settings.json
+global/claude-safe.py
+tests/eval/sets/
+tests/probe_claude_development.py
+tests/probe_claude_process_safety.py
+tests/test_claude_gui.py
+tests/test_claude_safe.py

solo_sdd-0.2.0/AGENTS.md

@@ -0,0 +1,115 @@
+# solo-sdd
+
+## Purpose and mode
+
+Own spec-driven development process for one person or a team, with any coding agent, independent of other spec tools: the algorithm, skills, global agent rules, Claude Code hooks and project templates. The repository is the source of truth; `sync.py push` puts the files in place.
+Mode: prod. Prod here is the agent folders on this computer (`~/.claude`, `~/.codex`, `~/.agents`, `~/.local/bin`): after `sync.py push` an edit takes effect in all sessions at once.
+
+## Sources of truth
+
+- Behaviour contract: `solo-sdd/specs/`; active work: `solo-sdd/changes/`; the project intent: `solo-sdd/project.md`.
+- Algorithm: `ALGORITHM.md`; the lessons the rules grew from: `LESSONS.md`.
+- `README.md`: what lies where and how it is deployed. `targets.json`: the deployment map.
+- Files copied into agent folders are not a source: an edit in place is pulled with `sync.py pull`.
+- `solo-sdd/specs/` and the open changes of `solo-sdd/changes/` are kept in git. The change archive `solo-sdd/changes/archive/` and `docs/waiting.md` are not in git, they live only in the working folder: the archive is not published.
+
+## Working with specs
+
+- One change per session, up to the archive.
+- No clarifying questions: a reasoned decision, recorded in the report.
+- Work outside the current spec becomes a new change.
+- After `tasks.md` is closed, an independent live test before reporting readiness.
+
+## Commands
+
+| What | Command |
+|---|---|
+| Install | Python 3 from the system; for tests and lint, `python3 -m pip install --user hypothesis pyflakes==3.4.0` |
+| Tests | `python3 tests/run.py --jobs 5 --tier slow` before delivery; a round: `python3 tests/run.py --jobs 5 --tier fast`, then `python3 tests/run.py --jobs 5 --affected <path>...`; before a release tag: `python3 tests/run.py --jobs 5 --tier release` |
+| Tests (one) | `python3 tests/<file>.py`; one test: `python3 -m unittest <module>.<Class>.<test>` from `tests/` |
+| Lint | `python3 -m pyflakes solo_sdd global scripts sync.py` |
+| CLI | `python3 -m solo_sdd --version` |
+| What is deployed and where it differs | `python3 sync.py status` |
+| Deployment | `python3 sync.py push` |
+| Specs | `python3 -m solo_sdd validate --all` |
+
+## Project map
+
+| Path | Role |
+|---|---|
+| `skills/<name>/SKILL.md` | Algorithm skills and manual commands; deployed by `targets.json` |
+| `solo_sdd/` | Package and the `solo-sdd` command; deployment logic in `layout.py`, `sync.py` is a wrapper; the `solo-sdd/` tree rules and `validate` in `process_format.py`; `import openspec` in `import_openspec.py`; `init` in `init.py` |
+| `pyproject.toml` | Package description |
+| `package.json`, `bin/solo-sdd.js` | npm package: a wrapper that runs `python -m solo_sdd` |
+| `global/AGENTS.md` | Global rules of both agents |
+| `global/work_hooks.py`, `global/model-policy.json` | Claude Code workflow hooks and the model policy |
+| `global/work_hooks_settings.py` | One-off connection of the hooks in `~/.claude/settings.json` |
+| `global/process-guard.py` | Hook that forbids stopping processes directly |
+| `global/sdd_dispatch.py` | Status acceptance and `local` mode merge for `spec-dispatch` |
+| `global/sdd_eval.py` | Change replay and comparison of dispatcher configurations |
+| `tests/eval/` | Sets, configurations, prices, fixtures |
+| `templates/` | Templates for new projects |
+| `examples/demo/` | Demo project with its `solo-sdd/` tree and `WALKTHROUGH.md`; kept valid by `tests/test_demo.py` |
+| `integrations/antislop/` | Bundled integration `antislop`: pinned copy of the anti-slop rules for `ui-check` and `copy-check` with its `integration` description; deployed by `targets.json`, updated only by replacing the copy |
+| `integrations/security-audit/` | Bundled integration `security-audit`: pinned copy of `cloudflare/security-audit-skill` for the security pass of `spec-audit` with its `integration` description; deployed by `targets.json`, updated only by replacing the copy |
+| `solo-sdd/` | Specs, changes and the archive of this repository; the archive lives only in the working folder |
+| `scripts/publish-first.sh` | First publication: a new `main` without history and without `solo-sdd/`, one-off |
+| `scripts/pre-push-guard.sh` | `pre-push` hook the publication step of `docs/release.md` installs: refuses a pushed commit that shares history with `history-local` or `history-private`, and a ref not to a commit |
+| `scripts/release_check.py` | Release check: tag against versions, sdist, wheel from the sdist and npm tarball into `dist/`, packed files against `git ls-files`, `--version` smoke, the `CHANGELOG.md` section; `--notes <tag>` prints that section |
+| `CHANGELOG.md` | The changes each version archived; its section of the current version is the GitHub release text |
+| `.github/workflows/release.yml` | Release on a pushed tag `v<version>`: tests, release check, PyPI and npm through trusted publishing, GitHub release |
+| `docs/release.md` | One-time registry setup and the release steps |
+| `.github/workflows/test.yml` | CI: lint, `tests/run.py` and `solo-sdd validate --all`; the `slow` tier on Ubuntu for a push or PR, the `release` tier on macOS for a `v*` tag and on both for a manual run; a newer run of a ref cancels the older one |
+| `tests/` | Tests and probes; `tests/run.py` runs every `tests/test_*.py` in parallel, failed first (`--failed`, named files, `--affected <path>` by `tests/affected.json`); `tests/stands/` holds live scenario stands |
+
+## Working copy
+
+- Paths: `docs/waiting.md`, `docs/debug-profile.md`, `docs/rules-audit.md`, `docs/process-safety-verification.md`, `global/claude-gui.py`, `global/claude-process-safety-settings.json`, `global/claude-safe.py`, `tests/eval/sets/`, `tests/probe_claude_development.py`, `tests/probe_claude_process_safety.py`, `tests/test_claude_gui.py`, `tests/test_claude_safe.py`
+
+## Boundaries and invariants
+
+- Edits only here, then `sync.py push`. Files in agent folders are not edited by hand.
+- `sync.py push` does not overwrite a copy edited in place (`drift`); before overwriting it saves the previous text to `~/.local/share/solo-sdd/backup/`.
+- Hooks are fail-open: an internal error lets the action through and is written to `~/.claude/hook-state/errors.log`.
+- All repository text is in English, with no Cyrillic letter (`tests/test_repo_language.py`).
+
+## Checks
+
+Before "done": the `Tests` row, the lint from the table without output, `python3 -m solo_sdd validate --all`, `python3 sync.py status` without unexpected `drift`, the change's live scenario.
+
+## Delivery
+
+- Mode: pr
+- Merge: squash
+- PR title: the change name
+- Deploy: no; deployment to agent folders is done separately (`sync.py push`).
+- No CI: while GitHub Actions starts no jobs (the spending limit, since 2026-11-08), `sdd-pr.py wait <url>` prints `PR #<n> <url> CI: infra` with no log line and exits with code 4 (probed on PR #79 on 2026-11-12). Then the full local run before delivery, `python3 tests/run.py --tier slow`, is the only suite check, and the PR waits for the owner: an agent never merges around a red or missing check (`docs/release.md`).
+
+## Security
+
+- Paid model calls in tests: only the cheapest (`global/model-policy.json`).
+- `sync.py push` changes the agents' working folders on this computer: this is a prod action, check `sync.py status` after it.
+- There are no secrets in the repository and there must be none.
+
+## Lessons
+
+- A stand runs what it means to test: a container stand gets the repository files and its downloads through stdin from the host (a container here has no network of its own and a bind mount sees only folders under the home folder), and a stand that runs a Python package with `-m` against a copy of the repository runs from outside the copy, since the working folder comes first on the import path; a stand that compares with the tree before its change pins that commit by hash, since the fork point from main and a lookup by the change's own commits move once the branch merges; a test that runs a copy of a project file copies every project module that file imports, so a new import does not break the copy.
+- Detection of an installed agent or any other environment fact looks only inside the passed home and PATH, never at a machine-wide folder, and a test of such code pins what is detected, so it gives the same result on every machine; a setting proposed from detected facts requires every fact the command that uses it depends on, not only the one that makes it possible; a test fixture names every git default it relies on (the initial branch of each `init`, bare ones included), since the system git config differs between machines, and turns off git's detached auto maintenance in a repository it copies, which otherwise writes in it during the copy.
+- A claim about how a tool behaves or what it outputs, taken from its changelog, its binary or another agent's report, is written into a skill, document, change or a command's own output only after running that tool here on a probe (with no run possible it is worded as expected and unconfirmed, never as a state), and a record of which files a change edited, or of which tests a source path affects, only after checking it against its source before the commit: the diff for the first, and for the second every way a test reaches the path (an import, a script another script starts, a copy it compares, a build run in the tree); text with escapes of non-ASCII characters is read back in the written file before the commit, since the writing tool may decode the escapes; a timing or cost measured on another machine or load is measured again here, base and branch under the same load, before a pass bar or a plan rests on it; a path given to a command that also takes a name or a shorthand in that place (`npm publish`, `npm install`) starts with `./`, and a publishing step runs once as the registry's dry run before the first tag.
+- An unnamed "our product" in a request means solo-sdd itself: the owner's other products are neither the subject of the work nor a source of its facts unless the owner names them.
+- Markup that hides text (HTML comments) is removed once, in the reader, after code blocks and code spans are recognised, and no later consumer applies it again; a command that reads a format another program reads (a document `validate` checks, a shell command line) reads it with that program's own rules or a copy of its reader, never a regex of allowed prefixes, and accepts exactly what it accepts or refuses it, and a command that copies a tree and then advises deleting the source refuses on any entry it cannot list, follow or decode, and a gate or report over a document counts every line outside the part it exempts and keeps the readable entries of a file it cannot fully parse: a line or entry skipped silently is lost; a command that refuses a broken input checks it before its first side effect, also in the steps that run before its main one, and one that writes several files checks every target it can (readable, writable) before the first write, whichever order it writes in; in a fail-open handler an exception ends every later step, so a step that must always run comes before the steps that can raise, and each check loads a shared input (a policy file) through its own guarded read, so a broken input drops only the checks that need it.
+- A session capability the agents depend on (loopback sockets, network, subagent depth) is probed once before they are launched; its absence stops the launch with the fix named only when the project declares that it needs the capability, otherwise the launch goes on with the fix as a warning.
+- A check of a command's printed output finds a line by its prefix, not by its position, a check of a document reads a step or item whole up to the next one, not one physical line, and both collapse whitespace in both sides before comparing with a stated text: a new output line or a reflowed paragraph must not break old checks, and tools align output with runs of spaces.
+- A stand that grades a judgement call expects one answer only for an input where every correct reading gives it; otherwise it grades what all correct answers share.
+- A deployment gate is worded for the whole repository, not for one change: a push after any later merge deploys the whole tree, and a deployment the process starts for itself never takes a source that holds merged work not yet cleared for deployment; a publication step that hands a name others resolve to a new target (a repository renamed and its old name taken by a new one) first guards and repoints every clone that uses the name, and checks a push it forbids with a dry run, never with the push itself.
+- A cleanup of copies an earlier version or a gone source deployed skips every path the current deployment map still lays out, names its candidates instead of matching all unmapped state entries, and takes a source as gone only when it is missing, never when it cannot be read for lack of permission (a folder that can be listed but not entered included); a removal in a folder the owner also writes to deletes only the entries its own sources name (the map, the state, its caches), keeps and names every other entry, and silences only the one error it expects (a folder not empty).
+- A value that falls back to a built-in default is reported with its source, so a reader can tell "nothing set" from a choice, and a reader that switches on a listing tells a refusal (a FAIL line, a non-zero exit) from an empty answer, so a broken input never reads as the thing being off; every reader of a setting, the command a person runs included, takes its chain of sources from one shared definition, never from a fallback only one reader knows; and a choice inferred from older records is stored explicitly once made, so records a later step keeps never infer it back; a rule that says which of several values (two command rows, two settings) its readers take is written at every reader that a change finds by searching for the value's name, not only where the values are defined; a gate that asks for a command's run selects what it asks about with that command's own selection (the same function, both sides normalized the same way), so every request it makes is one a run can clear.
+- A bulk wording replacement in instructions keeps quoted program output verbatim and is reread line by line for a shift of meaning.
+- A script that moves or rewrites a branch decides from the commits themselves, never from a setting that other readers resolve from more sources than it does.
+- An input check covers the edge forms of its input: a whole-number or name check accepts only ASCII digits and the whole string (`str.isdigit` passes digits that `int()` rejects, a regex `\d` with `$` passes other scripts' digits and a trailing newline), a check whether input comes from a terminal treats a closed stdin (no stream at all) as no terminal, and a comparison that decides whether to rewrite a stored value normalizes both sides the same way, line endings included; a write made atomic through a new file and a rename keeps every refusal of the write it replaces, checking the target's own write permission, since a rename needs only the folder's; text a reader takes from foreign input (a folder name, a line of a file) reaches its output only escaped, and a reader of a foreign tree refuses a link leading out of it before it prints anything read through the link; a stored result read back is checked against what the step that wrote it can produce, and printed exactly as stored, never cleaned a second way; a foreign command's process group is killed only while a process the caller has not yet reaped holds the group id; every reader of a file in a folder foreign input can reach opens it without blocking and parses only a regular file, and a result stored beside others in one record carries its own time, since the record's write dates every result it keeps; a check that tells a missing path from an unreadable one stats the path and catches only the not-found errors, never a library predicate (`Path.is_file`, `exists`) whose error handling changes between Python versions.
+- Before a stand or test of a removed requirement is deleted, every check it holds for a requirement that stays moves into a kept test.
+- A new outcome or exemption of a step is written where the rule it changes is read: before that step in the order, and as its exit in every state list the process keeps where that list's exit rule is written; otherwise the run takes the old path or waits for an event that never comes; a new ban is checked against every rule that requires what it bans, and names that rule's case as its exception.
+- A scenario of a change that adds a behaviour names what only the new code produces, and an example project's own checks are ones its shipped open change already meets: otherwise a test written first passes on the old code, or the agent rewrites the example before code.
+- A gate that a person's marks open counts the expected items from its own source and takes the person's confirmation from a record the agent's account cannot produce (a review the platform refuses the author), never from the marks alone or from parsing the agent's commands; evidence the agent writes itself (a LIVE command, a review field) is matched whole against a source written before the work, and the bypass flag of such a gate is the owner's alone.
+- A guard that exempts part of a shell command (a message, a pattern, a path) reads it by the shell's grammar and each program's option grammar (clustered and abbreviated options, `$'…'`, a `#` comment, a `cd`, a wrapper that runs a word) and refuses every form it cannot read the same way: an exemption is kept as narrow as the forms it is proven on, and the fallback that drops it names the forms the reader can read (an allowlist), not every occurrence of a feared token; a check whether a pattern (a glob) reaches a protected name tests it against that name's own rule and the files that exist, never against a sample list of names; a reader of a nested part (a substitution, a `-c` string) takes it from the original text, never from a copy another reader rewrote (requoted, cut), and applies the same exemptions as at the top level; a guard that recognises a run behind wrappers and runners tries every later word instead of stopping at the first word it does not know, since that word may wrap the run: a false refusal is recorded as a known limit, a missed run is not; a form one rule learns to read stays unreadable for every other rule that refuses it for its own reason (a `${` computes a file name for the secret guard), so a scenario that expects a guard to pass is checked against every requirement of that guard on the same form; a fix that narrows or widens such a match is replayed against the forms the previous version decided, so no refused form starts passing and no command of another program starts being refused.
+- A path that becomes git-ignored is checked through every step that merges, resets, aborts or mirrors the tree for a deletion of its copy on disk: git treats an ignored file as expendable and overwrites or removes it, a transfer of ignored files carries their removal, and an undo that runs after a reset deletes files git tracks again; a temporary copy of a git index keeps the index's own time, since git rereads only a file no older than the index it loads and a fresh copy hides an edit made in that second.

solo_sdd-0.2.0/ALGORITHM.md

@@ -0,0 +1,211 @@
+# Solo SDD: the algorithm
+
+Spec-driven development for one person or a team, with any coding agent (Claude Code and Codex today). The user sets the goal and accepts the result. The agents run the work themselves: from the plan to code merged into main, without questions along the way. The base is solo-sdd's own process tree `solo-sdd/` and its commands (`solo-sdd new`, `validate`, `list`, `archive`); the skills from `skills/` work on top of them. A project still on `openspec/` moves with `solo-sdd import openspec`.
+
+How the repository is organised and how to deploy it is in [README.md](README.md). The third-party files the repository ships are listed in [SOURCES.md](SOURCES.md). Why the rules are worded the way they are is in [LESSONS.md](LESSONS.md).
+
+## Principles
+
+1. **The specification is the source of truth.** Behaviour changes together with the spec, in one change. Code that diverges from the spec counts as a defect, even if the tests are green.
+2. **A small change.** One result the user can check themselves, one area of code, at most 10 tasks. If it comes out bigger, it is several changes linked through `Depends On`.
+3. **A property, not a method.** The spec says what must be true ("git history does not change"), not how to check it ("look for the substring push"). The implementer chooses the method.
+4. **Proof, not a report.** Readiness is confirmed by observations: a test that fails on the previous code, and a live scenario in what a person sees. Green tests, a report by the author or a subagent, "the function was called" do not count as proof.
+5. **No questions along the way.** The agent resolves an ambiguity itself and records the decision. Asking is allowed only before three things: a paid call, deleting or overwriting data, an action on prod. The question names what will happen, how many calls and what amount.
+6. **A blocker does not stop the work.** First look for a workaround: mocks, old data, `.env`, a neighbouring service. No workaround: what is unchecked goes into `verification.md` and `docs/waiting.md`, the rest gets closed.
+7. **Code is written by whoever holds the plan.** Every handoff between agents loses precision, so the lead agent writes the code itself. Subagents are for independent acceptance and heavy reading. Review is done by an agent that did not write this code.
+8. **Nothing is invented.** Values the source knows (CLI, API, database) are asked from the source. An honest "could not determine" is better than a plausible value.
+9. **Cheap where a mistake is easy to notice.** Search, reading logs and test output run on cheap models; code, review and acceptance on the main one. First the effort changes (medium by default, low for mechanics, higher if stuck), the model only when effort did not help. Paid calls to the product model in tests and runs go to the cheapest models and with consent. Heavy reading goes to a search subagent (Explore), so the lead's context does not get compacted.
+10. **"Done" = archived, checked live, merged.** If any of the three is missing, the status is "not done" with what is missing.
+
+## Cycle
+
+```
+ 0 project-init ─► 1 context-resume ─► 2 evidence-research (when needed)
+                                                   │
+ 9 spec-audit ◄─ 8 ship ◄─ 7 closing ◄─ 6 proof ◄─ 5 spec-next ◄─ 4 spec-analyze ◄─ 3 spec-plan
+ (every 5 archives)                        ▲
+                                         debug-profile, ui-check, agent-quality
+```
+
+Cross-cutting skills at any stage: `work-status` (five lines about the state), `context-resume` (after a pause, a context compaction or an agent switch).
+
+### 0. The project is ready for agents: `project-init`
+
+Once per project. It creates `AGENTS.md` (project rules: commands, map, boundaries and invariants, checks), `CLAUDE.md` with the line `@AGENTS.md`, the process tree `solo-sdd/` by `solo-sdd init` with `solo-sdd/project.md` (language, mode and an "Intent"), `.env.example`, README.
+
+In a repository that already has code it also writes the codebase map `docs/codebase/` (`STACK.md`, `ARCHITECTURE.md`, `CONVENTIONS.md`, `CONCERNS.md`): four cheap subagents, every statement names a path, each file stamped with the commit; the `CONCERNS.md` items are candidates for `spec-plan`. `/project-init map` refreshes it.
+
+**Gate G0:** `solo-sdd validate --all` passes; every command from the `AGENTS.md` table actually runs; the project comes up by the README in a clean shell.
+
+### 1. Context: `context-resume`
+
+When returning to a project, after a context compaction or on an agent switch. It reads the project rules, `handoff.md`, `verification.md` of open changes, `git status` and the history by the words of the task. The output is a map: the goal, the source of truth, the last confirmed state, the user's decisions, blockers, the next step. A fact from history is checked against files and the service. If they diverge, the current state counts as right.
+
+### 2. Research and decision: `evidence-research`
+
+Only when the plan cannot be written without it: choosing a technology, a service or an approach. `evidence-research` gives a table of options by the user's constraints, every fact with a source and a date. A disputed decision goes the same way: the options side by side on checked facts, the choice and its reason. The result goes into `spec-plan` as input.
+
+### Light path: no change
+
+A code edit takes the light path when it changes no behaviour a main spec describes, adds no dependency, touches no data, migration or deploy, and changes at most `process.light-path.max-files` files (default 3); `process.light-path: off` forbids it. The edit, the project's tests, a live check of the edited place and one commit `light: <the request>` are the whole record; `spec-plan` coverage names such an item with its commit, `work-status` and `report` count these commits apart from changes. Anything outside the bounds, and a bug in behaviour a spec describes, goes through a change.
+
+### 3. Plan: `spec-plan`
+
+Input: a plan, a bug list, the result of a discussion. Output: a queue of small changes. No code is written, except the light path items, after the plan commit.
+
+- A unit fits if it has one checkable result, one area of code, at most 10 tasks and a live check scenario. Bugs are grouped by a common cause, not "one bug, one change".
+- A unit that leads away from the "Intent" of `solo-sdd/project.md` does not become a change and goes into the report.
+- `solo-sdd new <id>` lays out the change; the artifacts are written in the order proposal → specs → verification → tasks by the "Writing rules" of `spec-plan` (see "Change artifacts").
+- Whatever waits for a person, access or paid consent does not become a task. It is `Needs` in `verification.md`. A change made up entirely of such conditions gets a `WAITING` file.
+- Every input item is matched with a change or the light path. Any other item without a change counts as an error.
+- A bug with a found cause takes the short track (the "Bug fix" section in `spec-plan`): the reproduction and the place of the cause in the proposal, the bug scenario is added to the spec, the first task is a failing test for this scenario, at most 5 tasks, side edits in Out of Scope. Cause not found: `debug-profile` first.
+- A UI change starts What Changes with a Design Read line from `DESIGN.md` (no `Dial` line with three numbers means dials 1/1/1 and "draft without direction"); the Live Scenario is a list "element → action → result"; the user's business facts (numbers, reviews, customers) are placeholders `[data needed: …]`.
+
+**Gate G1:** `solo-sdd validate --all`; then `spec-analyze` on every created change (stage 4); full coverage of the input.
+
+After G1 the folders of created and changed changes go in one commit `change: <id>, …`, without other edits. If `solo-sdd/changes` is ignored, there is no commit, and the report says "plan outside git".
+
+### 4. Check before code: `spec-analyze`
+
+Before the first task of every change. The spec is checked against itself while there is no code: a hole in `tasks.md` costs one line, after implementation a rework.
+
+Passes:
+
+| # | Pass | What it looks for |
+|---|---|---|
+| 1 | Coverage | A requirement or scenario without a task and a test; a task without a requirement |
+| 2 | Solo frame | An empty Out of Scope; an unarchived Depends On; a retelling instead of a quote in Source; more than 10 tasks; waiting for a person in tasks; a Live Scenario that does not reach what the user sees |
+| 3 | Checkability | A task without an observable criterion |
+| 3a | Executable properties | An invariant, round trip or idempotence checked only by examples |
+| 4 | Consumer | A new field, module or value that nobody reads |
+| 5 | Ambiguities | Empty, erroneous and partial cases; "no data" versus "not read"; a repeat; what the user sees in each outcome; term drift; `TBD` |
+| 6 | Wording | A method instead of a property; line numbers instead of structure; hard-coded values; words without a measure |
+| 7 | Consistency | A contradiction with the main spec; a decision in design without a task; a task uses what appears later; drifting from the intent |
+| 7a | Requirement compatibility | Requirements that are true one by one and unsatisfiable together; incompatible constraints; an undescribed combination of conditions; a hidden assumption |
+
+Checks derived from the defects of a specific project live in its `solo-sdd/analyze.md` (laid out by `solo-sdd init`). The skill picks them up itself.
+
+The agent fixes CRITICAL and HIGH findings in the artifacts and writes the decisions into `Decisions Without Owner`. Code does not change in this pass.
+
+**Gate G2:** no open CRITICAL and HIGH; everything from `Depends On` is archived. Otherwise the change is not ready, and `spec-next` takes another.
+
+### 5. Implementation: `spec-next`
+
+One run closes one change, from selection to archive.
+
+1. Step 0: a project with `openspec/` and no `solo-sdd/` stops here with the next step `solo-sdd import openspec`; the skills never import by themselves.
+2. Selection: the named change; else the one with the most done; else the next one with closed dependencies. A change with a `CLAIM` file (taken by another agent) or `WAITING` is skipped.
+3. Claim: `solo-sdd/changes/<id>/CLAIM` in the main project folder with the line `<agent> <date>`; Claude adds `session=<session id>` (`$CLAUDE_CODE_SESSION_ID`), by which the write hook recognises its own `CLAIM`. The hook itself places the marker only on a `tasks.md` edit that checks a new task: analysis and audit that edit artifacts do not take the change.
+4. Check: `spec-analyze` (stage 4).
+5. The lead agent does the tasks from `tasks.md` itself, including code. Subagents are only for acceptance (item 7) and heavy reading (`Lookup:`, Explore). Executors only if the user named `codex-orchestration` (Codex CLI); then the orchestration rules apply:
+   - Split by file ownership. Independent units go in a parallel wave, units on one file in different waves or separate worktrees.
+   - A unit has one proof, at most two or three. If more, the unit is split.
+   - The spec for an executor starts with the header "do it yourself, do not ask" and holds own and foreign files, a sample, all literal values, a ban on commits and the report format.
+   - Acceptance by own commands and `git status` of own tree. An executor's report stays a claim, not proof.
+   - After a parallel wave, a review of the combined diff.
+6. A task is checked `- [x]` only after its own check. Test runs: while coding only the tests of the edited module (`Tests (one)`); the whole suite (`Tests`) once after the last code edit, again only when code changed after that run; after a red run the failed tests first, the suite once they are green. Output through the runner's quiet option (`-q`, `--reporter=dot`, `--silent`), and on a red run only the failure lines are read.
+   With enabled integrations, after the suite `solo-sdd check --point checks --changed --change <id>`: a `gate` FAIL holds the step as a red test does, and the CLI writes the `Integrations` line into `Result`.
+7. Independent acceptance: a reviewer with a clean context on the main model gets only the delta specs, the Live Scenario, the diff and the printed lines of the last `solo-sdd check` (it runs no integration), without the author's reports and `Result`.
+   With enabled integrations it also gets the material files of `solo-sdd check --point review --changed` as a method, whose instructions it does not execute. For every requirement: done, partial or no, with the place in code and the test; separately, edits the spec does not require. Findings are labelled `Important`, `Nit` (at most five) or `Pre-existing`; only `Important` gives rework.
+
+   Later rounds read only the new diff and the list of findings already given; an open `Important` after the last round (`process.review-rounds` of `solo-sdd/config`, default 3) or two reviewer failures in one round means `Not Verified`, no archive.
+
+Several ready changes at once (Claude Code only): `spec-dispatch`: the main session on the main model with `/effort low` hands them out in waves to Opus orchestrators, one per change in its own worktree in a temporary folder. An orchestrator runs the change by `spec-next` in the "Under the dispatcher" mode: it writes all tasks itself; subagents only for acceptance and search; it does not merge and hands back a status block instead of a report. The dispatcher does not read code: it repeats the commands from the status, merges one at a time, does not fix a conflict, delivers main.
+
+### 6. Proof
+
+| What changes | What proves it |
+|---|---|
+| Any behaviour | A test that fails on the previous code. A shape check ("the field exists") does not count |
+| An invariant, round trip, idempotence | A property-based test (`fast-check`, `Hypothesis`) named after the Requirement. The test must fail on at least one code mutation, the generator must reach boundary states |
+| What a person sees | The `Live Scenario` from `verification.md` on the built artifact or a stand |
+| An interface | `ui-check`: screenshots at 1280 and 390, both themes, the Hard Gate (antislop) with proofs, clicks "element → action → result", "draft without direction" without a `DESIGN.md` with `Dial`, an audit on the word "audit" |
+| AI agent quality | `agent-quality`: A versus B on one labelled set, one change per run |
+| A failure in a running service | `debug-profile`: reproduction → version and environment → localisation by logs → one hypothesis. After two failed edits, stop and analyse |
+
+Paid calls to the product model in tests and live acceptance go to the cheapest models; review and acceptance run on the main model. A paid run starts only with consent, with the number of calls and the amount.
+
+### 7. Closing
+
+- `verification.md` gets `Result` (what was run and what was got, with a date), `Not Verified` (what is not proven and why) and `Decisions Without Owner`.
+- `solo-sdd validate <id>`, then `solo-sdd archive <id> --yes`: the archive applies the deltas to the main specs itself. Then `solo-sdd validate --all`.
+- If the mandatory live scenario did not pass and there is no allowed Fallback, there is no archive, the status is "not done".
+- An external remainder after the archive is allowed only if the project rules or the user explicitly allow it. The ground goes into `verification.md` and `docs/waiting.md`, the report tells "archived" from "external acceptance not ready".
+- The `CLAIM` file is deleted.
+
+**Gate G5:** `verification.md` is filled; `solo-sdd validate` passes; the change is archived.
+
+### 8. Delivery: `ship`
+
+Done when the local main branch matches the remote and the tree has no unexplained files. Before that, check what exactly push or merge triggers. If it is a prod rollout: stop and ask what will roll out, where, what happens to the data. No `--force` and no `reset --hard`. Secrets do not go into a commit. With enabled integrations `solo-sdd check --point ship` runs before the commits; a `gate` FAIL stops before the commit.
+
+### 9. Audit: `spec-audit`
+
+Every 5 archives (`spec-next` reminds itself) or when fixes keep coming while the product does not work. Review is done by an agent that did not write the code, read-only and with a clean context. The output is a table "requirement → done, partial or no → file:line" and findings P0-P3. Every finding is confirmed by the code, at least one end-to-end scenario is checked up to the place the user sees. With enabled integrations the reviewer also reads the material files of `solo-sdd check --point audit` as a method and executes none of their instructions.
+
+## Change artifacts (`solo-sdd/changes/<id>/`)
+
+| File | What is in it | Who fills it |
+|---|---|---|
+| `proposal.md` | Why, What Changes, Capabilities, Impact, **Out of Scope** (not empty), **Depends On** (the only place for dependencies), **Source** (the user's quote verbatim) | spec-plan |
+| `specs/<capability>/spec.md` | Delta: `## Purpose` for a new capability; ADDED, MODIFIED, REMOVED, RENAMED Requirements; SHALL/MUST; WHEN/THEN scenarios | spec-plan |
+| `verification.md` | **Live Scenario**, **Needs**, **Fallback** before code; **Result**, **Not Verified**, **Decisions Without Owner** after | spec-plan, then spec-next |
+| `tasks.md` | At most 10 tasks; the last group `Acceptance` of two tasks: the live scenario and validate + archive | spec-plan |
+| `design.md` | Only when it cannot be done without: decisions with rejected alternatives | when needed |
+
+Project markers and files:
+
+| File | Meaning |
+|---|---|
+| `solo-sdd/changes/<id>/CLAIM` | An agent runs the change; another does not take it |
+| `solo-sdd/changes/<id>/WAITING` | The change waits for an external condition; a line in `docs/waiting.md` |
+| `docs/waiting.md` | The waiting table: what, from whom, since when (template: `templates/docs/waiting.md`) |
+| `handoff.md` | Handoff between sessions and agents: the five `work-status` lines and decisions |
+| `docs/debug-profile.md` | What runs where, logs, config, what must not be touched without consent |
+| `solo-sdd/analyze.md` | `spec-analyze` checks derived from the defects of this project |
+
+## Gates
+
+| Gate | When | Who checks | What | On failure |
+|---|---|---|---|---|
+| G0 | After `project-init` | The lead agent | validate, the commands from AGENTS.md run, the project comes up by the README | Fix the project or the README |
+| G1 | After `spec-plan` | The lead agent | validate, analyze, input coverage | Split or complete the changes |
+| G2 | Before code | `spec-analyze` | No CRITICAL and HIGH, dependencies archived | Fix the artifacts; the change is not taken |
+| G3 | After every task | The lead agent, by own commands | The diff, the task's checks, `git status` of own tree | Rework until the checks are green |
+| G4 | Before closing | The lead agent and an independent reviewer | The test failed on the previous code; the property test catches a mutation; the Live Scenario passed; the reviewer has no open `Important` | "Not done", Not Verified |
+| G5 | Closing | The lead agent | verification.md, `solo-sdd validate`, archive | Do not archive |
+| G6 | Delivery | `ship` | main = origin/main; deploy only with consent | Stop before the deploy |
+| G7 | Every 5 archives | An agent that did not write the code | Requirement ↔ code, an end-to-end scenario | P0 and P1 are fixed if the task allows the fix; otherwise a report to the user, who can pass it to `spec-plan` |
+
+## Roles
+
+| Role | Does | Does not |
+|---|---|---|
+| User | Gives the goal, Source and Intent; accepts the result; agrees to money, deletion and prod | Does not carry context between agents, does not answer technical questions along the way |
+| Lead agent | Plans, writes code, keeps the artifacts, closes the change | Does not accept own work; does not trust reports |
+| Executor (Codex, by the user's choice) | Does one unit in its own files and reports in the given form | Does not touch foreign files, does not commit, does not invent values |
+| Reviewer | Reads code and spec with a clean context, read-only | Does not edit what it found |
+| Search (Explore) | Reads many files and returns a digest | Does not edit and does not make decisions |
+
+Claude Code and Codex are equal: both work by the same rules (`~/AGENTS.md` = `~/.codex/AGENTS.md` = `~/.claude/CLAUDE.md`) and the same skills. They differ only in the tool for subagents and orchestration.
+
+## When to run what
+
+| Situation | Skill |
+|---|---|
+| A new folder or a repository without rules | `project-init` |
+| "Let's continue", after a pause or an agent switch | `context-resume` |
+| "What to choose", comparing technologies or services | `evidence-research` |
+| A disputed decision between options | `evidence-research` |
+| A plan, a bug list, the result of a discussion → into work | `spec-plan` |
+| A bug with a found cause | `spec-plan`, the "Bug fix" section; cause not found: `debug-profile` first |
+| Before the code of a change | `spec-analyze` |
+| "Implement the next spec", "finish the change" | `spec-next` |
+| Several ready changes, "hand them to orchestrators", the main session only accepts statuses (Claude Code) | `spec-dispatch` |
+| The interface changed | `ui-check` |
+| Text for people in the product | `copy-check` |
+| A prompt, model or retrieval of an AI agent changes | `agent-quality` |
+| A service does not work, the cause is not obvious | `debug-profile` |
+| Commit, push, PR, merge | `ship` |
+| "Status?" | `work-status` |
+| Review, audit, "why does nothing work" | `spec-audit` |