Case packet

Neutral case identifier: case-15b46d34f5e07e

The possible directed relationship from Artifact A to Artifact B is under review.

Artifact A

Directory placement is total, frontmatter classification is partial

In a file-based knowledge base, every file has a canonical path before any parser or validator accepts it. Location is therefore physically total: the filesystem assigns every file a value on this axis, with no opt-out. At a chosen routing level, that location is exclusive, even though the path also lies within ancestor scopes. Location is also spatial: co-location creates neighborhoods for scoped search, browsing, and curated indexes. The filesystem supplies the address and neighborhood without metadata synchronization, but it does not enforce the semantic clauses attached to them.

Declared classifications, by contrast, can be optional or mandatory. In Commonplace, frontmatter is optional: the validator treats a file without it as implicit text, but the file declares no type: value. Type is therefore partial over the physical files before validation. A validator can require every admitted artifact to have a type, making classification total over that valid subset. But this is an additional enforcement rule, not a property of the file substrate. Even when present, a type describes a document's structure rather than its canonical neighborhood: one type can appear across many directories, one directory can hold many types, and queries assemble the type's cohort. In this configuration, type labels documents while location partitions the physical space.

Why the asymmetry matters

These surfaces have different native guarantees, not different expressive powers. A policy can be encoded in a directory contract, a required field, a type, or a convention. Moving it between surfaces, however, changes when it applies, how failure appears, and what neighborhood it creates.

The location contract is the [collection]'s COLLECTION.md; position selects it. The path identifies the applicable contract before the document cooperates, including for files with missing or malformed frontmatter. Agents, reviews, or validators must still enforce the contract's semantic clauses. Commonplace places the [text contract]—quality goal, linking policy, and scope—on this surface because those clauses are intended to cover every file in the region.

The type contract is the type-spec; a declaration selects it. It governs structure: schema, required sections, and frontmatter fields. In an opt-in system, it applies only to documents that declare the type. The declaration is portable, however: the same global type can retain its shape when the document moves between collections.

Translating a clause between the surfaces does not preserve their native guarantees:

  • A mandatory type can encode "every valid artifact is theoretical," but a missing or malformed declaration escapes the rule until validation. The resulting cohort also has no canonical neighborhood unless another mechanism builds one.
  • A dedicated directory can encode "everything routed here has Evidence and Reasoning sections," but doing so spends that directory level on shape, prevents other shapes from sharing the same immediate neighborhood, and changes the structural obligation when the document moves.

In Commonplace's opt-in type model, COLLECTION.md and a type-spec are therefore not interchangeable without changes to the enforcement and routing model. This asymmetry explains the older observation that types and directories are orthogonal.

An assignment rule, not an identification

Nothing forces the directory tree to carry collection or text-contract semantics. A KB that routes kind-first can spend its directory tree on type—a decisions/ folder—and gain pre-validation coverage and neighborhood for kind while declaring content area elsewhere. Choosing which classification receives the substrate's native properties is a design decision. Assign the directory tree to the classification that needs:

  • pre-validation coverage, for admission and routing rules that must select a contract even for untyped or malformed files;
  • canonical exclusivity, when one primary classification is needed at a particular routing level, while allowing contracts on ancestor scopes to compose;
  • neighborhood, for clauses about relations among artifacts: link vocabulary, duplicate policy, browse order, index membership.

Classifications that instead need portability—obligations that should travel with an artifact wherever it lives—fit declared axes. Validation can make such an axis mandatory and total over admitted artifacts, but it adds an enforcement dependency. It also does not select a value for malformed files before the check runs.

The assignments can compose within one tree: Commonplace gives ADRs a browsable subdirectory neighborhood inside kb/reference/, while their type-spec carries the structural contract and the surrounding collection retains its text contract.

Moving a file and changing its declared type remain distinct edits, though admission or cross-contract constraints can require both in one valid transition.

Scope

The claim concerns canonical placement in a file-based corpus before validation. A database can make several classification fields mandatory without giving any of them tree locality; filesystem overlays require the KB to designate one canonical location. The claim does not imply that directory contracts enforce their own semantics or that declared metadata cannot be mandatory. It means only that those guarantees come from additional machinery rather than physical placement.

Relevant Notes:

Artifact B

Why notes have types

The type system serves seven distinct roles. Each is developed in its own note or nearby register theory; this page provides context and links.

Agents are stateless and context is finite. [Types give agents structural hints before opening documents] — a spec says "you can implement from this," a structured-claim says "there's a developed argument with evidence," an index says "follow links from here." The type plus description let an agent narrow from hundreds of files to the few it needs without opening any of them.

Metadata enforcement

Navigation depends on metadata existing reliably. The [type system enforces metadata that navigation depends on] — descriptions exist because the [note base type] requires them. Without enforcement, agents and humans under time pressure skip metadata, and the knowledge base degrades to a collection navigable only by opening every document.

Verification

Types must assert [verifiable structural properties, not subject matter]. "This is a design note" is not verifiable — every note in a design KB is about design. "This has Evidence and Reasoning sections" is verifiable. The verification gradient means types can be checked at different levels of cost — from deterministic (does the frontmatter have a description?) through LLM rubric (is the description discriminating?) to corpus-level (does this contradict existing claims?).

Extensibility

Different knowledge domains need different document structures. [Directory-scoped types are cheaper than global types] — the global layer stays thin ([text] and [note]), while each collection has its own types/ subdirectory with templates that extend the base. This keeps per-session context cost low and lets users introduce new types by adding a template locally, with no global configuration changes.

Content-layer identification

Types also help identify which content layer an artifact belongs to. The layer is not always encoded by the type name alone: a note in kb/notes/ is theoretical, a note in kb/reference/ is descriptive, and an instruction is prescriptive. But the type: field plus the collection-local type path gives tools and readers enough information to infer the relevant quality goal: explanatory-reach for theory, fidelity and economy for description, executability and precision for prescription.

This connects the type system to [theories, descriptions, and prescriptions with asymmetric linking]. Once the content layer is deducible from collection and type, validation and review can become layer-specific without adding a separate register: field everywhere.

Output quality

Beyond organisation, types shape what gets written. When a structured-claim template requires Evidence, Reasoning, and Caveats sections, the writer must actually produce those things. With LLMs specifically, three independent arguments support this:

  • [Human writing structures transfer to LLMs because failure modes overlap] — LLMs exhibit human-like failures (conflating evidence with opinion, skipping qualifications), so structures that prevent those failures in humans prevent them in LLMs too.
  • [Structure activates higher-quality training distributions] — structured templates steer autoregressive generation toward scientific papers and formal arguments rather than unstructured web text.
  • [Structured output is easier for humans to review] — separated sections let a reader check facts and logic independently, regardless of how the LLM produced them.

The arguments are independent and complementary. Each stands alone; together they cover the full chain: the LLM might reason better, the output will be shaped better, and the human reader can evaluate it better.

Maturation

Content starts as [text] (no frontmatter, no structure) and gains type information as it develops — gradual typing applied to documents. The maturation path is: raw capture → add frontmatter (note) → accumulate traits → promote to a specific type when structural criteria are met. A bare note that persists without promotion is a signal. This mirrors the broader [constraining pattern]: practices start stochastic and harden as they prove out.

Why free-form, not enum

The type field is a string, not validated against a list. This is deliberate:

  • New domains. Workshop documents, scenario types, recurring tasks — these emerged after the initial type system. A closed enum would have required updating a global definition for each.
  • User adaptation. Installed knowledge bases serve different purposes. A research project might need experiment and literature-review types. A product team might need user-story and retrospective. These should be addable locally.
  • Tolerance of fuzziness. Types are assigned by agents and humans, not compilers. The system must tolerate misclassification — nothing breaks if a type is wrong or novel. Types are search aids, not enforcement boundaries.

Convention establishes common values. Directory types/ folders document structural expectations. But the system doesn't require permission to use a new value.

Relevant Notes:

  • [available types] — the taxonomy: base types table and migration history
  • [directory-scoped-types-are-cheaper-than-global-types] — the economic argument for thin global types and local extension
  • [a-knowledge-base-holds-theories-descriptions-and-prescriptions-with-asymmetric-linking] — explains the content-layer role that type and collection jointly identify
  • [a-functioning-kb-needs-a-workshop-layer-not-just-a-library] — the workshop layer that will need its own type extensions

Under-review context phrase

establishes that type is opt-in and free-form, the premise that makes type partial rather than total