torbenandClaude Opus 5.5
f6aaadc413
Every settings field declares its tier; a value in the wrong file is an error naming
file, key and tier. A field naming a program or affecting a gate cannot be declared
instance. Secrets are references only: {"ref": "<name>"} via WIKITOOL_SECRET_<NAME> or
a user-only secrets file, {"ref": "op://..."} via op read (locked 1Password: exit 42).
The preflight records op as an optional tool. doctor gains one line per tier, docs
verify checks a committed wikitool.json for plaintext secrets, CI resolves a real
op:// value through 1password/load-secrets-action. No feature reads its settings
this way yet; without the two files every other command is unchanged.
Files changed:
- .gitea/workflows/ci.yml
- .gitignore
- AGENTS.md
- CHANGES.md
- INSTALL.md
- VERSION
- docs/explanation/README.md
- docs/explanation/configuration-tiers.md
- docs/how-to/README.md
- docs/how-to/use-1password-for-settings.md
- docs/reference/commands/README.md
- docs/reference/commands/configuration.md
- docs/reference/commands/instance-health.md
- docs/reference/commands/types-instructions-and-docs.md
- docs/reference/configuration.md
- docs/reference/exit-codes.md
- instructions/dev/doc-pull-through.md
- instructions/dev/testing-conventions.md
- instructions/preflight.md
- tools/CONTRACT.md
- tools/README.md
- tools/chemenu/cli.py
- tools/chemenu/cli_contract.py
- tools/chemenu/commands/_util.py
- tools/chemenu/commands/config_cmd.py
- tools/chemenu/commands/docs_verify.py
- tools/chemenu/commands/doctor.py
- tools/chemenu/config.py
- tools/chemenu/config_shapes.py
- tools/chemenu/prerequisites.py
- tools/chemenu/settings.py
- tools/chemenu/tests/conftest.py
- tools/chemenu/tests/test_dist_cmd.py
- tools/chemenu/tests/test_preflight.py
- tools/chemenu/tests/test_preflight_pwsh.py
- tools/chemenu/tests/test_settings.py
- tools/chemenu/toolpaths.py
- tools/preflight.ps1
- tools/preflight.sh
- tools/prerequisites.txt
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SnAJ7Z3CpVD3PRbN73QtU2
25 lines
1.5 KiB
Markdown
25 lines
1.5 KiB
Markdown
# Explanation
|
|
|
|
Why the stack is built the way it is. These pages are background for humans and agents alike:
|
|
read by link or on request, never as instruction, and they carry no normative sentence - a rule
|
|
lives in `AGENTS.md` or a `CONTRACT.md`, and a page here only gives its reasons.
|
|
|
|
- [architecture.md](architecture.md) - what the stack is made of, and how its parts divide the
|
|
work
|
|
- [telemetry-and-evaluation.md](telemetry-and-evaluation.md) - how the stack observes what an
|
|
agent did, and how that record turns into a score
|
|
- [pipeline-rationale.md](pipeline-rationale.md) - why the pipeline has four stages
|
|
- [ownership-and-templates.md](ownership-and-templates.md) - why a `.template` split exists, and
|
|
why an instance comes only from a release
|
|
- [language-boundaries.md](language-boundaries.md) - why the control plane is English everywhere
|
|
and the KB language is a value
|
|
- [why-gates-are-code.md](why-gates-are-code.md) - why the gates are code rather than instruction
|
|
- [version-model.md](version-model.md) - why a version number answers a compatibility question
|
|
and a migration question separately
|
|
- [knowledge-and-commitment.md](knowledge-and-commitment.md) - why commitments live in a task
|
|
tracker rather than in `kb/`
|
|
- [configuration-tiers.md](configuration-tiers.md) - why settings sit in three tiers, and what
|
|
keeping secrets out of the tree does not protect against
|
|
- [model-and-effort-selection.md](model-and-effort-selection.md) - which model and effort suit
|
|
which kind of session, for the harness that has to choose
|