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:

```text
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.

```bash
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`:

```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**:
   ```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
```