info-tech-canon/infospace/assimilation/intake-and-assimilation-practice.md

Intake and Assimilation Practice

Status: Practice (normative for this repository) Applies to: every external or internally-drafted document, schema, vocabulary, or model proposed for absorption into InfoTechCanon Anchors: InfoTechCanonCore §14 (Assimilation Model), §8.13 (ChangeRecord), §8.14 (DecisionRecord), §27.4 (Minimal Assimilation Profile)

---

1. Why this exists

New concepts and terminology arrive continuously — from consumers, from external standards, from Bernd's own drafts. Without a fixed pipeline they either rot in a drop directory or get pasted into the canon without comparison, which is the anti-pattern Core §29.6 names explicitly ("Assimilation by copy-paste").

This practice defines the full path:

incoming/                     drop zone, un-reviewed, never referenced by canon
   │  (1) intake
   ▼
infospace/assimilation/<slug>/source/     processed input, frozen snapshot
   │  (2) scope, extract, compare
   ▼
infospace/assimilation/<slug>/            assimilation workspace + proposals
   │  (3) disposition decision  ← human gate
   ▼
infospace/{models,standards,...}/         canon change (adopt / adapt)
   │  (4) register + regenerate + validate
   ▼
canon.yaml version bump + CHANGELOG.md    new canon version with change notes

Governing rule (Core §14.7): assimilation produces proposals, not automatic canon changes. Steps 1–2 may run unattended. Step 3 requires an explicit disposition recorded by the canon owner.

---

2. The drop zone: incoming/

• incoming/ holds raw, un-reviewed inputs exactly as received. Do not edit them.
• Nothing in the canon (canon.yaml, infospace/artifacts/index.yaml, links from canon documents) may reference a path under incoming/.
• An input may be several files (a Markdown document plus its machine-readable companion). Keep them together; they assimilate as one unit.
• incoming/ is expected to be empty after a processing session. A file remaining there is an unprocessed backlog item, not a resting place.

Related but distinct front doors — do not confuse them:

Directory	Holds	Next step
incoming/	raw candidate material to absorb	this practice
demand/	a stated consumer need, not yet a work item	workplan + design
feedback/	observed utility of existing canon concepts	cite; spawn demand/ only if a gap needs work
seeds/	historical provenance of first-generation canon files	frozen

If an input turns out to be a need rather than a body of knowledge, move it to demand/ and open a workplan instead of an assimilation workspace.

If an input is a report on whether existing concepts hit or missed, move it to feedback/. A single arrival may split: utility evidence stays in feedback/, requested changes go to demand/.

---

3. Stage 1 — Intake

Create the workspace and move the input into it. Use git mv so the provenance chain stays visible in history.

slug=<kebab-slug>
mkdir -p infospace/assimilation/$slug/source
git mv incoming/<file> infospace/assimilation/$slug/source/

The snapshot under source/ is frozen: it is the evidence of what was assimilated and what version it was. Later revisions of the same external body arrive as a new intake with a new source_version, never as an edit in place.

Write infospace/assimilation/<slug>/assimilation.yaml conforming to infospace/schemas/assimilation.schema.yaml:

id: assimilation/<slug>
title: <human title>
source: <source body name and version>
source_version: "<version>"
source_type: external-standard | internal-draft | product-schema | ...
source_files: [source/<file>, ...]
requested_by: <who>
status: intake | scoping | analysis | proposed | decided | closed
disposition: observe | map | adopt | adapt | reject   # provisional until stage 3
impacts: [<artifact ids the input touches>]

4. Stage 2 — Scoping, extraction, comparison

Produce the Minimal Assimilation Profile (Core §27.4). One file per output so each can be reviewed and diffed independently:

File	Content
ASSIMILATION.md	the record: scope, stages, findings, recommendation
source-summary.md	faithful précis of the input, no canon opinion
extracted-concepts.yaml	every concept the input introduces, with its own terms
comparison-matrix.md	each extracted concept classified against the canon
mappings.yaml	concept-level mappings to existing canon owners
proposed-changes.md	concrete, reviewable canon change proposals
open-questions.md	unresolved issues blocking or following adoption

Classify every extracted concept with one of the Core §14.6 result categories: already_covered, covered_differently, broader_than_existing, narrower_than_existing, missing_concept, conflicting_concept, implementation_detail_only, viewpoint_difference, terminology_difference_only.

Two canon principles decide most rows:

• Single canonical owner (Core §6.2) — a concept has exactly one owning artifact. If the input redefines something an existing model owns, that is a mapping or a conflict, never a second definition.
• Import, do not redefine (Core §6.3) — where the input needs a concept the canon already owns, the proposal is an import, not a copy.

5. Stage 3 — Disposition (human gate)

The canon owner records one disposition for the assimilation as a whole, and, where they differ, per proposed change:

Disposition	Meaning	Canon effect
observe	recorded, no change yet	workspace only
map	related to canon via mappings	infospace/mappings/ entries
adopt	taken in essentially as-is	new/extended canon artifact
adapt	taken in, restructured to canon shape	new/extended canon artifact
reject	out of scope or conflicting	rationale in the record

Record the decision in ASSIMILATION.md as a DecisionRecord (Core §8.14): Context, Decision, Options Considered, Rationale, Consequences, Review Trigger. Set status: decided and the final disposition in assimilation.yaml.

For adopt/adapt, open a workplan (workplans/ITC-WP-NNNN-<slug>.md) for any follow-on work that is not completed in the same session — mappings to sibling models, profiles, schemas, consumer alignment notes.

6. Stage 4 — Transforming into the canon

When adopting or adapting, the new artifact is written in canon shape, not pasted:

1. Place it under the correct classification — infospace/models/<domain>/ for a broad domain structure, infospace/standards/<name>/ for a cross-cutting convention or named framework, infospace/patterns/, infospace/profiles/.
2. Head it with canon frontmatter — id, title, short_name, type, status, version, source_version, source_file, canonical_owner, namespace, imports, related, owned_concepts, created_at, updated_at. source_version and source_file preserve the provenance chain back to the frozen snapshot (see CARING for the reference example).
3. Separate normative prose from data. Human-readable normative content goes in the Markdown; enumerations, catalogs and baselines go in a sibling YAML that is the single machine-readable source of truth. Do not maintain the same list in both.
4. Declare owned concepts and imports so ownership stays checkable, and add the imported-from relationships rather than restating imported definitions.
5. Register the artifact:
   • canon.yaml — kernel: / models: / standards: entry with path and status
   • infospace/artifacts/index.yaml — id, path, kind, title, provenance (with source_path pointing at the frozen snapshot), relationships
   • infospace/infospace.yaml — disciplines: entry for the primary document
6. Regenerate and validate:

   make agent-briefs && make index && make tree
   make validate && make test
   

   Generated files (agent briefs, retrieval indexes, views) carry a GENERATED notice — never hand-edit them; fix the source and regenerate.

7. Stage 5 — New canon version with change notes

A canon change that adds, removes, or redefines canonical concepts produces a new canon version.

• Version field: canon.yaml → version, semantic:
  • patch — editorial, generated output, no concept change;
  • minor — new artifact, new concepts, backward-compatible extension;
  • major — a concept is removed, renamed, or its ownership moves; identifiers are durable interfaces, so any break requires migration semantics.
• Change notes: every version gets an entry in CHANGELOG.md at the repo root, structured as a ChangeRecord (Core §8.13): what changed, rationale, whether it is breaking, what it supersedes, and the assimilation or workplan that produced it.
• Artifact status: a newly assimilated artifact enters at proposed or draft status and is promoted only after practical use, even when the canon version itself is released.
• Close the loop: set the assimilation status: closed, add a progress event, and run statehub fix-consistency if workplan files changed.

8. Session checklist

[ ] incoming/ is empty (every input intaken or routed to demand/)
[ ] each input has a frozen source/ snapshot and an assimilation.yaml
[ ] Minimal Assimilation Profile files exist and every concept is classified
[ ] disposition recorded as a DecisionRecord
[ ] adopted artifacts registered in canon.yaml, artifacts/index.yaml, infospace.yaml
[ ] make agent-briefs && make index && make tree && make validate && make test pass
[ ] canon.yaml version bumped and CHANGELOG.md entry written
[ ] follow-on workplan opened for anything deferred