Source of Truth (Lite)

1. The plan (it waits for your confirmation)

sot-build-lite   [x] Start > [>] Plan > [ ] Write > [ ] Check > [ ] Q&A > [ ] Approve
Step 2 of 6, Plan: the project is mapped and a document plan is ready. Needs from you: confirm the plan.

What I found: this is

itsdangerous, the Pallets library for cryptographically signing data so it can be sent to untrusted places and verified when it comes back. It's a small Python library: about 1,200 lines in src/itsdangerous/, 5 test modules and Sphinx docs. It's built with flit and uv and tested with tox in GitHub Actions.

I already found two inconsistencies in pyproject.toml, and they'll go into the open-questions document:

• The coverage settings measure jinja2 instead of itsdangerous.
• The source package includes an examples/ folder that doesn't exist.

Proposed documents:

1. overview.md: what it is, who uses it, its status and what's out of scope
2. architecture.md: the layers (encoding → Signer → TimestampSigner → Serializer → URL-safe), with diagrams of how signing and verification flow, and the rules a change must not break
3. project-structure.md: what each folder holds and where to make each kind of change
4. technology-stack.md: versions and the exact commands for setup, tests, linting, type checks and docs
5. decisions.md: the main design choices and why they were made
6. open-questions.md: contradictions, unknowns and risks

Optional extras (I recommend the first three): 7 public-api.md · 8 security.md · 9 testing.md · 10 features · 11 module-map · 12 data-model · 13 interfaces · 14 coding-standards · 15 build-and-delivery · 16 tech-debt · 17 glossary

Should I write these documents? You can add extras by number (for example "7 8 9"), or remove or rename any document.

2. After the writing, the check, your answers and your yes

sot-build-lite   [x] Start > [x] Plan > [x] Write 6/6 > [x] Check > [x] Q&A > [x] Approve
Done: the knowledge base is approved and recorded. Needs from you: nothing.

The knowledge base is approved. Everyone starts at knowledge-base/INDEX.md, which tells people and agents which document to open for what they're doing.

Documents:

• overview.md: what the library does, how your applications use it, its status and what's out of scope
• architecture.md: the layers, token format, key handling and rotation, errors, step-by-step flows with diagrams, the rules a change must not break, and the gotchas
• project-structure.md: what each folder holds and where to make each kind of change
• technology-stack.md: every tool with its version and the exact commands
• decisions.md: 24 decisions, with the reason given only where a source records it
• open-questions.md: contradictions, unknowns, risks and known debt

Questions:

• Answered: how your team uses the library (as a dependency).

Still open (kept in open-questions.md): the release steps before a tag is pushed · whether loads_unsafe should really never fail · whether key_derivation="none" is supported · whether coverage should be measured

Limitations:

• Only architecture.md and decisions.md had the independent check; I checked the rest myself.
• I didn't run any tests or builds; every command and version comes from the project files.