svarupa 0.1.0__tar.gz

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

@@ -0,0 +1,128 @@
+name: ci
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+
+env:
+  FORCE_COLOR: "1"
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --all-extras --dev
+      - name: ruff
+        run: uv run ruff check svarupa tests
+      - name: ruff format check
+        run: uv run ruff format --check svarupa tests
+      - name: pyright
+        run: uv run pyright svarupa
+
+  test:
+    name: test ${{ matrix.os }} py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --dev --python ${{ matrix.python }}
+      - name: pytest
+        run: uv run pytest -q
+
+  # The determinism suite is the highest-value test in the project. If it
+  # regresses, every PR shows architecture changes that did not happen, teams
+  # learn to ignore the check, and the governance pillar is worthless.
+  determinism:
+    name: determinism ${{ matrix.os }} py${{ matrix.python }} seed=${{ matrix.hashseed }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+        python: ["3.10", "3.13"]
+        hashseed: ["0", "12345", "random"]
+    env:
+      PYTHONHASHSEED: ${{ matrix.hashseed }}
+      LC_ALL: C
+      LANG: C
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --dev --python ${{ matrix.python }}
+      - name: determinism suite
+        run: uv run pytest -q -m determinism
+
+  # Gate 2 from Spike 0, deferred at the time because a Docker daemon was not
+  # available locally. Renders the same corpus on Linux and macOS and asserts
+  # the bytes match. A hash mismatch here means the lockfile is not portable,
+  # which breaks per-PR diffing at the root.
+  cross-platform-bytes:
+    name: byte identity (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest]
+    env:
+      LC_ALL: C
+      LANG: C
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+      - run: uv sync --dev
+      # Builds from a real fixture tree on disk, not an in-memory string.
+      # An in-memory corpus is pure str manipulation and can essentially never
+      # differ across platforms, so it verified the serializer's determinism
+      # rather than the product's. NFD paths, dirent ordering and
+      # case-insensitive volumes only enter through an actual filesystem walk.
+      - name: build from a real fixture tree
+        run: uv run python scripts/render_fixture_lock.py lockfile.out
+      - name: hash
+        run: |
+          python3 -c "
+          import hashlib, pathlib
+          b = pathlib.Path('lockfile.out').read_bytes()
+          print(f'sha256={hashlib.sha256(b).hexdigest()}  bytes={len(b)}')
+          "
+      - uses: actions/upload-artifact@v4
+        with:
+          name: lockfile-${{ matrix.os }}
+          path: lockfile.out
+
+  compare-bytes:
+    needs: cross-platform-bytes
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          path: artifacts
+      - name: assert Linux and macOS bytes are identical
+        run: |
+          a=artifacts/lockfile-ubuntu-latest/lockfile.out
+          b=artifacts/lockfile-macos-latest/lockfile.out
+          if ! cmp -s "$a" "$b"; then
+            echo "::error::lockfile bytes differ between Linux and macOS"
+            diff <(cat -A "$a") <(cat -A "$b") | head -40
+            exit 1
+          fi
+          echo "byte identity confirmed: $(sha256sum "$a" | cut -d' ' -f1)"

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

@@ -0,0 +1,38 @@
+name: release
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  # id-token is what PyPI trusted publishing (OIDC) exchanges for a short-lived
+  # upload credential; no API token is stored anywhere.
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: check the tag matches the package version
+        shell: bash
+        run: |
+          TAG="${GITHUB_REF_NAME#v}"
+          PKG=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          test "$TAG" = "$PKG" || { echo "tag v$TAG != pyproject version $PKG"; exit 1; }
+
+      - name: run the test suite
+        run: |
+          uv sync --frozen
+          uv run pytest
+
+      - name: build
+        run: uv build
+
+      - name: publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

svarupa-0.1.0/.github/workflows/svarupa.yml

@@ -0,0 +1,61 @@
+name: architecture
+
+on:
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  diff:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # The base branch's tree and its committed lockfile are both needed,
+          # so the fetch cannot be depth 1.
+          fetch-depth: 0
+
+      - uses: astral-sh/setup-uv@v5
+
+      - name: install svarupa
+        run: uv tool install 'svarupa==0.1.0'
+
+      - name: regenerate the base lockfile from base-branch code
+        shell: bash
+        run: |
+          git worktree add /tmp/base-src "${{ github.event.pull_request.base.sha }}"
+          svarupa /tmp/base-src --lock --out /tmp/base-artifact
+
+      # `shell: bash` turns pipefail on, so nothing here hides a failure.
+      # The delta is written to the job summary before the exit code is
+      # re-raised: a failing run is the one whose delta must be readable.
+      - name: architecture delta
+        shell: bash
+        run: |
+          BASE_SHA="${{ github.event.pull_request.base.sha }}"
+          # A base commit git cannot read is a job failure, never a silent
+          # fallback: falling back would drop the drift guard exactly when
+          # the checkout is wrong.
+          git cat-file -e "$BASE_SHA^{commit}"
+          if git cat-file -e "$BASE_SHA:.svarupa/architecture.lock" 2>/dev/null; then
+            git show "$BASE_SHA:.svarupa/architecture.lock" > /tmp/committed-base.lock
+            svarupa . --lock \
+              --diff /tmp/committed-base.lock \
+              --drift-base /tmp/base-artifact/architecture.lock \
+              > /tmp/delta.txt 2>&1 && code=0 || code=$?
+          else
+            # First adoption: the base branch has no committed lockfile yet, so
+            # the delta is taken against the regenerated base directly.
+            svarupa . --lock \
+              --diff /tmp/base-artifact/architecture.lock \
+              > /tmp/delta.txt 2>&1 && code=0 || code=$?
+          fi
+          cat /tmp/delta.txt
+          {
+            echo '## Architecture delta'
+            echo '````'
+            cat /tmp/delta.txt
+            echo '````'
+          } >> "$GITHUB_STEP_SUMMARY"
+          exit "$code"

svarupa-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+# The artifact directory is regenerated on every run, with one exception:
+# `architecture.lock` is committed on purpose. It is the diffable fingerprint
+# of the architecture, and a reviewer is meant to see `dep api -> auth` appear
+# as a green line in the pull request before CI even runs. Ignoring the whole
+# directory would ignore the one file the design says to commit.
+.svarupa/*
+!.svarupa/architecture.lock
+
+*.egg-info/
+*.pyc
+.pytest_cache/
+.ruff_cache/
+.venv/
+.venv2/
+__pycache__/
+build/
+dist/
+tests/js/node_modules/

svarupa-0.1.0/.svarupa/architecture.lock

@@ -0,0 +1,38 @@
+# svarupa 0.1.0
+# schema 1.7
+# grammars python@0.25.0
+dep	scripts	svarupa
+dep	scripts	svarupa/extract
+dep	scripts	svarupa/lock
+dep	svarupa	svarupa/derive
+dep	svarupa	svarupa/emit
+dep	svarupa	svarupa/extract
+dep	svarupa	svarupa/lock
+dep	svarupa	svarupa/query
+dep	svarupa	svarupa/setup
+dep	svarupa/derive	svarupa
+dep	svarupa/derive	svarupa/extract
+dep	svarupa/emit	svarupa
+dep	svarupa/emit	svarupa/derive
+dep	svarupa/emit	svarupa/extract
+dep	svarupa/emit	svarupa/layout
+dep	svarupa/emit	svarupa/lock
+dep	svarupa/extract	svarupa
+dep	svarupa/layout	svarupa
+dep	svarupa/layout	svarupa/derive
+dep	svarupa/lock	svarupa
+dep	svarupa/lock	svarupa/extract
+dep	svarupa/query	svarupa
+dep	svarupa/setup	svarupa
+entrypoint	svarupa	svarupa
+environment	pypi
+module	scripts
+module	svarupa
+module	svarupa/derive
+module	svarupa/emit
+module	svarupa/extract
+module	svarupa/layout
+module	svarupa/lock
+module	svarupa/query
+module	svarupa/setup
+role	svarupa	cli

svarupa-0.1.0/LICENSE

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

svarupa-0.1.0/PKG-INFO

@@ -0,0 +1,185 @@
+Metadata-Version: 2.5
+Name: svarupa
+Version: 0.1.0
+Summary: Verified architecture diagrams and a queryable knowledge graph, derived from your codebase. Every box points at a line of code.
+Project-URL: Homepage, https://github.com/aiwithvd/svarupa
+Project-URL: Repository, https://github.com/aiwithvd/svarupa
+Project-URL: Issues, https://github.com/aiwithvd/svarupa/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: architecture,diagrams,knowledge-graph,static-analysis,tree-sitter
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Documentation
+Requires-Python: >=3.10
+Requires-Dist: networkx<4,>=3.2
+Requires-Dist: pathspec<2,>=0.12
+Requires-Dist: pyyaml<7,>=6
+Requires-Dist: tomli>=2; python_version < '3.11'
+Requires-Dist: tree-sitter-python==0.25.0
+Requires-Dist: tree-sitter-typescript==0.23.2
+Requires-Dist: tree-sitter<0.27,>=0.26
+Provides-Extra: leiden
+Requires-Dist: leidenalg>=0.10; extra == 'leiden'
+Requires-Dist: python-igraph>=0.11; extra == 'leiden'
+Provides-Extra: mcp
+Requires-Dist: mcp>=2; extra == 'mcp'
+Description-Content-Type: text/markdown
+
+# Svarupa
+
+**स्वरूप** — *"its own true form."*
+
+Svarupa reads a codebase and produces a **verified** map of it: a queryable
+knowledge graph plus six types of architecture diagram (architecture, module
+dependencies, data flow, request flow, deploy topology, ERD), delivered as one
+interactive HTML artifact. A type the evidence cannot produce is named as
+absent, never fabricated.
+
+The defining constraint: **every node and every edge in every diagram carries
+`file:line` evidence, or it does not render.** Not a heuristic guess, not a
+model's plausible story. A claim you can click through to the source line that
+proves it.
+
+The name states the thesis. Svarupa is a thing's actual form, not its intended
+one. Architecture documents describe what someone meant to build. Svarupa
+renders what exists.
+
+> **Status: alpha (v0.1.0).** The evidence contract is stable; flags and output
+> formats may still change between minor versions.
+
+---
+
+## Quickstart
+
+```bash
+uv tool install svarupa     # or: pipx install svarupa / pip install svarupa
+svarupa .                   # scans the repo, writes .svarupa/
+open .svarupa/index.html
+```
+
+That is the whole setup — no configuration file, no daemon, no account. The
+first run of a typical repository takes seconds.
+
+`python -m svarupa` is the same command; `--out ./map` writes the artifact
+somewhere other than `<repo>/.svarupa/`. The artifact holds:
+
+- `index.html`: every diagram type as a tab. Click a box for its passport
+  (kind, connections, reach, cited source lines); double-click a drillable box,
+  or click its chevron, to open it in place down to component and code level.
+- `graph.json`: the knowledge graph. `svarupa query <dir> get_node <label>`,
+  `get_neighbors`, `shortest_path`, `affected`, `god_nodes`, `graph_stats`,
+  `query_graph`; `svarupa mcp <dir>` serves the same over MCP.
+- `REPORT.md`: the resolution scorecard and every finding, with its code.
+- Declared environments (production, staging, qa, development) are extracted
+  with `file:line` evidence and surface in the CLI summary, a REPORT.md
+  section, `graph.json` nodes, and a cited strip on the deploy topology.
+- `--lock` writes the committed architecture lockfile; `--diff` prints the
+  architecture delta against a base lockfile. `svarupa setup ci_github`
+  (or `ci_gitlab`) installs the per-pull-request workflow.
+
+![The architecture tab of the demo repository](docs/images/demo-architecture.png)
+
+![The deploy topology tab, with the declared-environments strip on top](docs/images/demo-deploy-topology.png)
+
+Declared environments — production, staging, qa, development — are extracted
+with `file:line` evidence and shown as a cited strip above the topology.
+
+---
+
+## Why
+
+Every tool in this space sits on one side of a divide and cannot cross it.
+
+| Tool | Analyzes code | Draws formal diagrams |
+|---|---|---|
+| Graphify | Deeply, 25+ languages | No — force-directed node-link graphs only |
+| Understand-Anything | Yes, AST + LLM | No — force layouts only |
+| Archify | No — reads nothing | Yes, five types, excellent quality |
+| Cocoon-AI | No — prompt-to-diagram | Yes, architecture only |
+
+Nobody closes the loop `code → AST → derived formal diagram`. The analyzers
+produce blobs; the drawers produce unverifiable pictures.
+
+### The larger thesis: continuous architecture governance
+
+Graphify and Understand-Anything are *onboarding* tools. You run one when you
+join a project, look at the graph, and never open it again.
+
+Because Svarupa's output is deterministic and evidence-backed, it runs in CI on
+every pull request: diff the architecture, comment the impact, fail the build
+on policy violations. **Cross-language architecture linting is a category
+nobody occupies.**
+
+```
+Architecture impact of #482
+
+  + 2 components    billing.refunds, billing.webhooks
+  + 1 datastore     redis (compose.yml:31)
+  ! NEW DEPENDENCY  billing -> auth.internal
+                    via billing/refunds.py:44
+  + 4 endpoints     POST /refunds, GET /refunds/{id}, ...
+```
+
+---
+
+## Design principles
+
+**Fail-closed on evidence.** An element without a source location is not
+emitted. When Python's dynamic dispatch means a call target cannot be pinned,
+no edge is written and the gap is counted in the report, rather than papered
+over with a plausible one.
+
+**Three-bin honesty.** The resolution scorecard reports *resolved*,
+*known-external*, and **unresolved-unknown**. Counting every failure as
+"external" would launder resolver bugs into a number that looks like honesty.
+
+**Deterministic by contract.** Same commit, same bytes, on any machine.
+Canonical ordering, `==`-pinned grammars, NFC-normalized paths, no timestamps,
+no locale-dependent formatting. Verified in CI across Linux and macOS on Python
+3.10 through 3.13 with `PYTHONHASHSEED` varied.
+
+**Identity comes from structure, not from clustering.** Lockfile modules are
+directories, packages, and workspace members. Community detection is
+chaotically sensitive to input perturbation — measured: one added import flips
+25-38% of community assignments — so it is used for visual grouping only and
+never reaches anything committed.
+
+**Measured, not assumed.** Function-level sequence diagrams were cut after
+measurement showed call resolution at ~20% on service code with median chain
+depth 0-1. Replaying this repository's own real history (15 commits of actual
+development: license swaps, viewer work, layout fixes) produced a median of
+**0 lockfile lines per commit** — the diff moves only when the architecture
+moves, not when code churns. See `docs/reviews/` for the numbers and the
+reasoning.
+
+---
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check svarupa
+uv run pyright svarupa
+```
+
+Design and review history:
+
+- `docs/superpowers/specs/` — the design, with a decision log carrying the
+  reasoning behind each choice
+- `docs/reviews/` — adversarial reviews, raw and triaged. Every finding is
+  marked Accepted, Rejected, or Deferred **with a recorded why**, because a
+  rejected finding needs its reasoning kept just as much as an accepted one
+
+---
+
+## License
+
+MIT. See `LICENSE`.
+

svarupa-0.1.0/README.md

@@ -0,0 +1,152 @@
+# Svarupa
+
+**स्वरूप** — *"its own true form."*
+
+Svarupa reads a codebase and produces a **verified** map of it: a queryable
+knowledge graph plus six types of architecture diagram (architecture, module
+dependencies, data flow, request flow, deploy topology, ERD), delivered as one
+interactive HTML artifact. A type the evidence cannot produce is named as
+absent, never fabricated.
+
+The defining constraint: **every node and every edge in every diagram carries
+`file:line` evidence, or it does not render.** Not a heuristic guess, not a
+model's plausible story. A claim you can click through to the source line that
+proves it.
+
+The name states the thesis. Svarupa is a thing's actual form, not its intended
+one. Architecture documents describe what someone meant to build. Svarupa
+renders what exists.
+
+> **Status: alpha (v0.1.0).** The evidence contract is stable; flags and output
+> formats may still change between minor versions.
+
+---
+
+## Quickstart
+
+```bash
+uv tool install svarupa     # or: pipx install svarupa / pip install svarupa
+svarupa .                   # scans the repo, writes .svarupa/
+open .svarupa/index.html
+```
+
+That is the whole setup — no configuration file, no daemon, no account. The
+first run of a typical repository takes seconds.
+
+`python -m svarupa` is the same command; `--out ./map` writes the artifact
+somewhere other than `<repo>/.svarupa/`. The artifact holds:
+
+- `index.html`: every diagram type as a tab. Click a box for its passport
+  (kind, connections, reach, cited source lines); double-click a drillable box,
+  or click its chevron, to open it in place down to component and code level.
+- `graph.json`: the knowledge graph. `svarupa query <dir> get_node <label>`,
+  `get_neighbors`, `shortest_path`, `affected`, `god_nodes`, `graph_stats`,
+  `query_graph`; `svarupa mcp <dir>` serves the same over MCP.
+- `REPORT.md`: the resolution scorecard and every finding, with its code.
+- Declared environments (production, staging, qa, development) are extracted
+  with `file:line` evidence and surface in the CLI summary, a REPORT.md
+  section, `graph.json` nodes, and a cited strip on the deploy topology.
+- `--lock` writes the committed architecture lockfile; `--diff` prints the
+  architecture delta against a base lockfile. `svarupa setup ci_github`
+  (or `ci_gitlab`) installs the per-pull-request workflow.
+
+![The architecture tab of the demo repository](docs/images/demo-architecture.png)
+
+![The deploy topology tab, with the declared-environments strip on top](docs/images/demo-deploy-topology.png)
+
+Declared environments — production, staging, qa, development — are extracted
+with `file:line` evidence and shown as a cited strip above the topology.
+
+---
+
+## Why
+
+Every tool in this space sits on one side of a divide and cannot cross it.
+
+| Tool | Analyzes code | Draws formal diagrams |
+|---|---|---|
+| Graphify | Deeply, 25+ languages | No — force-directed node-link graphs only |
+| Understand-Anything | Yes, AST + LLM | No — force layouts only |
+| Archify | No — reads nothing | Yes, five types, excellent quality |
+| Cocoon-AI | No — prompt-to-diagram | Yes, architecture only |
+
+Nobody closes the loop `code → AST → derived formal diagram`. The analyzers
+produce blobs; the drawers produce unverifiable pictures.
+
+### The larger thesis: continuous architecture governance
+
+Graphify and Understand-Anything are *onboarding* tools. You run one when you
+join a project, look at the graph, and never open it again.
+
+Because Svarupa's output is deterministic and evidence-backed, it runs in CI on
+every pull request: diff the architecture, comment the impact, fail the build
+on policy violations. **Cross-language architecture linting is a category
+nobody occupies.**
+
+```
+Architecture impact of #482
+
+  + 2 components    billing.refunds, billing.webhooks
+  + 1 datastore     redis (compose.yml:31)
+  ! NEW DEPENDENCY  billing -> auth.internal
+                    via billing/refunds.py:44
+  + 4 endpoints     POST /refunds, GET /refunds/{id}, ...
+```
+
+---
+
+## Design principles
+
+**Fail-closed on evidence.** An element without a source location is not
+emitted. When Python's dynamic dispatch means a call target cannot be pinned,
+no edge is written and the gap is counted in the report, rather than papered
+over with a plausible one.
+
+**Three-bin honesty.** The resolution scorecard reports *resolved*,
+*known-external*, and **unresolved-unknown**. Counting every failure as
+"external" would launder resolver bugs into a number that looks like honesty.
+
+**Deterministic by contract.** Same commit, same bytes, on any machine.
+Canonical ordering, `==`-pinned grammars, NFC-normalized paths, no timestamps,
+no locale-dependent formatting. Verified in CI across Linux and macOS on Python
+3.10 through 3.13 with `PYTHONHASHSEED` varied.
+
+**Identity comes from structure, not from clustering.** Lockfile modules are
+directories, packages, and workspace members. Community detection is
+chaotically sensitive to input perturbation — measured: one added import flips
+25-38% of community assignments — so it is used for visual grouping only and
+never reaches anything committed.
+
+**Measured, not assumed.** Function-level sequence diagrams were cut after
+measurement showed call resolution at ~20% on service code with median chain
+depth 0-1. Replaying this repository's own real history (15 commits of actual
+development: license swaps, viewer work, layout fixes) produced a median of
+**0 lockfile lines per commit** — the diff moves only when the architecture
+moves, not when code churns. See `docs/reviews/` for the numbers and the
+reasoning.
+
+---
+
+## Development
+
+```bash
+uv sync
+uv run pytest
+uv run ruff check svarupa
+uv run pyright svarupa
+```
+
+Design and review history:
+
+- `docs/superpowers/specs/` — the design, with a decision log carrying the
+  reasoning behind each choice
+- `docs/reviews/` — adversarial reviews, raw and triaged. Every finding is
+  marked Accepted, Rejected, or Deferred **with a recorded why**, because a
+  rejected finding needs its reasoning kept just as much as an accepted one
+
+---
+
+## License
+
+MIT. See `LICENSE`.
+