torben
c64479fe02
Files changed: - AGENTS.md - CHANGES.md - ENVIRONMENT.md.template - SOUL.md - SOUL.md.template - USER.md.template - VERSION - docs/ownership-and-templates.md - docs/version-model.md - instructions/CONTRACT.md - instructions/dev/doc-pull-through.md - instructions/dev/stack-close/SKILL.md - instructions/dev/stack-dev/SKILL.md - instructions/dev/version-parts.md - instructions/setup-instance.md - kb/CONVENTIONS.md - kb/CONVENTIONS.md.template - kb/concepts/COLLECTION.md - kb/sources/COLLECTION.md - tools/CONTRACT.md - tools/chemenu/commands/types_cmd.py - tools/chemenu/commands/version_cmd.py - tools/chemenu/tests/test_toc.py - tools/chemenu/tests/test_version_cmd.py - tools/chemenu/toc.py - tools/chemenu/version.py - types/comparison.md - types/concept.md - types/entity.md - types/lint-report.md - types/source.md
5.8 KiB
profile, outbound, required_by_stack
| profile | outbound | required_by_stack | ||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| concepts |
|
false |
kb/concepts/ - Collection Contract
Ideas rather than things: architectures, patterns, protocols, workflows, recurring problems, and the decisions taken about them. A concept explains how or why, where an entity page records what.
Quality goal: explanatory sufficiency - the page should answer why it is done this way without the reader having to open the entity pages that use it. If the explanation only makes sense once you already know the system, it is on the wrong page.
Inherits kb/CONTRACT.md for the rules the stack enforces - linking mechanics, provenance, citation, the confidence machinery - and kb/CONVENTIONS.md for what this instance decided: language, naming forms, tone, relationship labels, the confidence rubric. Neither is restated here.
Contents
Types offered
concept (tools/wikitool types describe concept). The concept_type: field
picks the area:
| Area | Holds |
|---|---|
architectures/ |
Shape and structure: how a system is cut up, and why the cuts fall where they do |
patterns/ |
Reusable solution shapes that hold across more than one subject |
protocols/ |
Communication protocols and standards, named in their usual spelling |
workflows/ |
Procedures and processes that recur across projects |
decisions/ |
Architectural and design decisions (see below) |
problems/ |
Recurring problems and the approaches taken to them |
These are areas, not collections: they inherit this contract and carry no
COLLECTION.md of their own.
Nobody assigns them by hand — the mapping is the layout: in
types/concept.md, and wikitool new puts a new page straight there. A page
sitting anywhere else is reported by wikitool lint as misplaced;
wikitool move --page "<title>" moves it to its computed location.
The split is not a matter of taste but what makes the catalog's shard threshold
effective at all: index rebuild splits per area, and a collection without
areas never splits — with 80 pages in a single table the threshold was a dead
value here. None of the six areas is currently above it, so none gets a shard of
its own; when one grows into it, that happens without anyone acting.
Decisions
An architectural decision is an ordinary concept page with concept_type: decision
(tools/wikitool types describe concept) - not a separate format, and not a separate location.
There is no adr-NNN--prefixed filename and no dedicated directory: naming follows
kb/CONVENTIONS.md § Naming like every other concept, and the page
lives in kb/concepts/ like every other concept.
The body is organic prose under this collection's usual sections, not a fixed template. What it
still has to carry: what was decided, what forced the decision, what it costs (not only what it
buys), and a link to every entity the decision affects. A **Status:** line is optional - most
decision pages in this instance carry none, because the page's own prose already says whether the
decision stands.
A decision superseded by a later one is never deleted or rewritten. The new page declares
supersedes pointing at it; the old one needs no edge back, because its inbound view renders the
replacement.
concept_type: decision is also the one subtype kb/CONTRACT.md's confidence
machinery treats differently: confidence decay skips it structurally, because elapsed time does
not falsify a decision - only a later decision superseding it does.
Authorised labels
The outbound: block above is what wikitool lint and xref add check: which labels a page in
this collection may use, per destination. The catalogue they are drawn from - and what each one
asserts - is instructions/link-taxonomy.md, which binds
nothing on its own.
The widest authorisation in this instance, because argumentation is what concept pages do. Note that the operational labels are absent: a concept does not depend-on anything - the entity implementing it does.
addresses is the one that pairs with this collection's own subtypes: a concept_type: decision
or a mechanism pointing at the concept_type: problem it answers. Without it, the collection can
declare a problem and never say what was done about it. alternative-to is self-dual and written
once per pair - see instructions/link-taxonomy.md.
Adding a label here is a deliberate contract change, not a way around a refusal.
Outbound linking
A concept links to every entity that implements or uses it. A concept with no inbound entity
link is usually either premature or misfiled - wikitool lint reports it as an orphan.
Where two concepts compete, do not argue the comparison inside either page; create a page in
kb/comparisons/ and link both to it.
What does not belong here
- A concrete, pointable thing - that is an entity.
- A head-to-head evaluation of alternatives - that is a comparison.
- Generic textbook explanation with no connection to anything in this wiki. If no entity here uses it, the page is not earning its keep.