--- id: ITC-WP-0012 type: workplan title: "Canonical Repository Layout Standard Integration" domain: canon repo: info-tech-canon status: finished priority: medium created: "2026-06-08" updated: "2026-06-13" depends_on_workplans: - ITC-WP-0005 - ITC-WP-0006 state_hub_workstream_id: "f40ecb8b-7d81-46e6-a420-f7843f708175" --- # ITC-WP-0012 - Canonical Repository Layout Standard Integration ## Goal Take the raw demand in `demand/CanonicalRepositoryLayout.md` through the canon's own Purpose/Demand intake and integrate it into the canon's line of provided structures (kernel / models / standards / profiles / patterns) **without** silently editing existing models or collapsing concepts. ## Intent `demand/CanonicalRepositoryLayout.md` proposes a canonical, retrieval-oriented documentation layout for repositories — `INTENT.md` / `SCOPE.md` plus `research/`, `demand/`, `spec/`, `workplans/`, `docs/`, `wiki/`, `issues/`, `history/` — distilled from CoulombSocial, HelixForge, and MarkiTect experience. It is explicitly a *recommendation, not a strict requirement*. The document arrived in `demand/`, which it itself defines as un-reviewed inbound. It must therefore be processed as a `DemandSignal` under the Purpose And Demand Model Extension (ITC-WP-0006) before any canon artifact is written. The layout is a **named cross-cutting convention**, so the working hypothesis is that it lands as a new **standard** whose per-directory semantics *reference* existing models (Information Space, Governance + PURPOSES, Task) rather than redefining them. The placement decision is an explicit review gate (T02), not a foregone conclusion. This work follows the WP-0009 discipline: produce a comparison, explicit placement/extension candidates, and reviewable deliverables — never blend the new convention into existing standards by hand. ## Tasks ### T01 - Demand intake ```task id: ITC-WP-0012-T01 status: done priority: high state_hub_task_id: "9ea93c0f-e69b-4ab5-81c4-75d43a4273cf" ``` - Record `demand/CanonicalRepositoryLayout.md` as a `DemandSignal` using the Purpose And Demand Model Extension (`ConsumerPurpose`, `DemandSignal`, `PurposeFit`, `ScopePressure`). - Capture provenance: prior art is the CoulombSocial / HelixForge / MarkiTect documentation practice named in the source. - Assess fit against current SCOPE.md and flag the scope pressure (this proposes a producer-facing convention the canon does not yet own). - Do not author any standard/model artifact in this task — intake only. ### T02 - Placement decision (review gate) ```task id: ITC-WP-0012-T02 status: done priority: high state_hub_task_id: "55232b4f-f286-410e-9795-99c8a2cdf25b" ``` - Decide where the convention belongs in the canon line of structures. Recommendation: a new **standard** (sibling to `tagging/` and `caring/`), not a model, profile, or pattern, because it is a named cross-cutting convention. - Map each layout element to existing canon ownership so nothing is re-defined: - `INTENT.md` / `SCOPE.md` and the SCOPE→INTENT gap-closing loop → Governance + Purpose/Demand extension. - `demand/` → `DemandSignal` intake surface (Purpose/Demand extension). - `research/`, `docs/`, `wiki/` → Information Space Model (knowledge packaging, retrieval, links, briefs). - `spec/` (PRD / TechSpec / UseCaseCatalog / ArchitectureBlueprint) → Governance + Information Space. - `workplans/` and `history/` (finished/canceled move to history) → Task Model + State Hub workplan conventions. - `issues/` → mirror of an external ticket system; map to Task Model surface. - Output explicit placement + extension candidates for review (mirroring WP-0009), not silent edits. ### T03 - Author the standard artifact ```task id: ITC-WP-0012-T03 status: done priority: high state_hub_task_id: "b9e30be4-c567-4a15-a8ee-8d2898dee9a5" ``` - Author `infospace/standards/repository-layout/InfoTechCanonRepositoryLayoutStandard.md` (namespace e.g. `itc-repo-layout`) defining the canonical directory set, the `yymmdd-` prefix conventions (research/, history/), and the SCOPE→INTENT operating mode. - Reference — do not duplicate — concepts owned by Information Space, Governance, Purpose/Demand, and Task models. Honor the no-collapse guardrails. - Encode conformance as a **recommendation** (the source is explicit it is not a strict requirement): define conformance levels so adopting repos can be partial-conformant. - Register the artifact: add to `canon.yaml`, `infospace/infospace.yaml` disciplines, the artifact index, and retrieval generation; add structural validation for the new standard's directories/relationships. ### T04 - Reconcile and regenerate ```task id: ITC-WP-0012-T04 status: done priority: medium state_hub_task_id: "8a89122f-737d-4348-83a8-909b251fa1ae" ``` - Reconcile the standard against this repo's *own* layout and note tensions: the canon already uses `spec/`, `wiki/`, `workplans/`, `seeds/`; the infospace uses the kernel/models/standards layout (a distinct concern from doc layout). Record whether the canon repo will dogfood the convention (e.g. `research/` for the yawex prior art, moving finished workplans to `history/`). - Run `make validate`, `make index`, `make tree`, `make agent-briefs`; commit the regenerated indexes, briefs, tree, and `infospace/validation/latest.json`. - Move `demand/CanonicalRepositoryLayout.md` to its resolved state once captured (per the convention, reviewed demand leaves the raw inbound directory). ### T05 - Consumer adoption brief ```task id: ITC-WP-0012-T05 status: done priority: low state_hub_task_id: "7313abf2-e9d3-40d9-8d27-0279d8f4b36c" ``` - Produce a short adoption brief so the seven tracked domains can opt into the layout from their own repos. Keep per-repo adoption work in those repos, not here (same boundary as WP-0009). ## Acceptance - The demand is recorded as a reviewed `DemandSignal` with explicit purpose fit and scope pressure. - The placement decision and extension candidates are explicit and reviewed before any standard text is written. - A registered `repository-layout` standard exists, references (does not duplicate) existing model concepts, and encodes recommendation-level conformance. - `make validate` is green; indexes, briefs, tree, and validation output are regenerated. - `demand/CanonicalRepositoryLayout.md` no longer sits unreviewed in `demand/`. ## Implementation Notes - Source demand: `demand/CanonicalRepositoryLayout.md` (recommendation, not a strict requirement; prior art = CoulombSocial / HelixForge / MarkiTect). - Follows the WP-0009 pattern: compare, surface candidates, keep consumer adoption in consumer repos. - `state_hub_workstream_id` and per-task `state_hub_task_id` are filled in on registration with the State Hub.