# 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: ```text incoming/ drop zone, un-reviewed, never referenced by canon │ (1) intake ▼ infospace/assimilation//source/ processed input, frozen snapshot │ (2) scope, extract, compare ▼ infospace/assimilation// 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. ```bash slug= mkdir -p infospace/assimilation/$slug/source git mv incoming/ 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//assimilation.yaml` conforming to `infospace/schemas/assimilation.schema.yaml`: ```yaml id: assimilation/ title: source: source_version: "" source_type: external-standard | internal-draft | product-schema | ... source_files: [source/, ...] requested_by: status: intake | scoping | analysis | proposed | decided | closed disposition: observe | map | adopt | adapt | reject # provisional until stage 3 impacts: [] ``` ## 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-.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//` for a broad domain structure, `infospace/standards//` 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**: ```bash 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 ```text [ ] 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 ```