info-tech-canon/infospace/standards/repository-layout/InfoTechCanonRepositoryLayoutStandard.md

---
id: itc-repo-layout:RepositoryLayoutStandard
title: InfoTechCanon Repository Layout Standard
short_name: ITC-REPO-LAYOUT
type: standard
standard_family: InfoTechCanon
repository_context: info-tech-canon
recommended_path: standards/repository-layout/InfoTechCanonRepositoryLayoutStandard.md
status: RC1-seed
version: 0.1.0-RC1
canonical_owner: InfoTechCanonRepositoryLayoutStandard
namespace: itc-repo-layout
classification: standard
primary_cluster: documentation-convention
conformance_posture: recommendation
imports:
  - InfoTechCanonCore
  - InfoTechCanonInformationSpaceModel
  - InfoTechCanonGovernanceModel
  - InfoTechCanonTaskModel
related:
  - InfoTechCanonKernelMap
  - InfoTechCanonPurposeDemandExtension
  - IntentScopePurposesPattern
owned_concepts:
  - CanonicalRepositoryLayout
  - RepositoryDocumentationDirectory
  - LayoutConformanceLevel
  - ScopeIntentOperatingMode
provenance:
  source_demand: infospace/evaluations/repository-layout/source-demand.md
  demand_intake: infospace/evaluations/repository-layout/demand-intake.yaml
  placement_decision: infospace/evaluations/repository-layout/placement-decision.yaml
  prior_art:
    - CoulombSocial
    - HelixForge
    - MarkiTect
---

# InfoTechCanon Repository Layout Standard

**Short Name:** `ITC-REPO-LAYOUT`
**Document Status:** Seed Standard Release Candidate 1
**Version:** 0.1.0-RC1
**Repository Context:** `info-tech-canon`
**Document Type:** InfoTechCanon Domain Standard
**Conformance Posture:** Recommendation (graded, not mandatory)
**Intended Audience:** Repository maintainers, project owners, DevSecOps teams,
documentation authors, knowledge-system builders, and AI agents that retrieve
from or write into repositories.

---

# 1. Purpose

The **InfoTechCanon Repository Layout Standard** defines a canonical,
retrieval-oriented documentation layout for repositories: a stable set of
top-level documents and directories so that humans and agents can locate the
right information at the right working-memory cost, in any conforming repository,
by convention rather than per-repo discovery.

It exists to make repository documentation **findable and uniform** without
forcing every repository into a rigid mold. The source demand is explicit that
this is a **recommendation, not a strict requirement**; this standard therefore
encodes graded conformance (§7) so a repository can adopt the parts that fit.

This standard provides:

- a canonical top-level document set (`INTENT.md`, `SCOPE.md`),
- a canonical documentation directory set
  (`research/ demand/ spec/ workplans/ docs/ wiki/ issues/ history/`),
- per-directory semantics that **reference** existing canon model concepts
  rather than redefining them,
- naming conventions (the `yymmdd-` prefix for `research/` and `history/`),
- the SCOPE→INTENT gap-closing operating mode,
- graded conformance levels,
- and anti-patterns.

# 2. Position in InfoTechCanon

The Repository Layout Standard is a **domain standard** within InfoTechCanon —
a named, cross-cutting convention, sibling to the Tagging Standard and the CARING
Access Governance Standard. It introduces no new domain entities of its own; its
per-directory semantics **import** concepts already owned by other artifacts and
must not redefine them:

```text
Information Space Model
  owns knowledge packaging, retrieval, links, briefs, and stakeholder docs.
  -> research/, docs/, wiki/, and the knowledge side of spec/ and history/.

Governance Model
  owns intent, scope, decisions, directives, and acceptance.
  -> INTENT.md, SCOPE.md, and the guardrail side of spec/.

Purpose And Demand Model Extension (candidate)
  owns ConsumerPurpose, DemandSignal, PurposeFit, ScopePressure.
  -> demand/ as the un-reviewed DemandSignal intake surface.

Task Model
  owns work items: backlog, readiness, commitment, progress, completion.
  -> workplans/, issues/ (mirror), and the lifecycle side of history/.

Intent Scope Purposes Pattern (candidate)
  describes the SCOPE->INTENT gap-closing operating mode this standard adopts.
```

This standard owns only the **layout convention** itself: which documents and
directories exist, what each is *for* at the repository level, how they are
named, and how a repository declares the degree to which it conforms.

# 3. Top-Level Documents

A conforming repository SHOULD provide two orientation documents at its root.

| Document | Captures | Canon owner referenced |
| --- | --- | --- |
| `INTENT.md` | The aspiration and boundaries — why the repository exists and what it is trying to become. | Governance (Intent) |
| `SCOPE.md` | A top-level view of what the repository currently achieves, includes, excludes, and promises. | Governance (Scope) |

`INTENT` and `SCOPE` are kept **distinct** (no-collapse guardrail): intent is the
aspiration, scope is the current boundary. Consumer purposes are a third plane and
are **not** recorded here — they belong to the Purpose/Demand surface.

# 4. Canonical Directory Set

Each directory below is a **RepositoryDocumentationDirectory**. The "Owns at repo
level" column states the repository-level purpose; the "Canon concept referenced"
column points at the model that already owns the underlying concept. The standard
never re-defines those concepts.

| Directory | Owns at repo level | Canon concept referenced |
| --- | --- | --- |
| `research/` | Results of explorations in the problem and solution space. Each exploration is a `yymmdd-` prefixed file, or a `yymmdd-` prefixed subdirectory when it has multiple files/sources. | Information Space (knowledge packaging, retrieval) |
| `demand/` | Inbound, **un-reviewed** feature requests, requirements, suggestions, and opportunities. Raw material that still needs scrutiny before becoming work. | Purpose/Demand extension (`DemandSignal` intake) |
| `spec/` | Specification files that provide guidance and guardrails for implementation — typically `ProductRequirementsDocument.md`, `TechnicalSpecificationDocument.md`, and optionally `UseCaseCatalog.md`, `ArchitectureBlueprint.md`. | Governance (directive) + Information Space (packaging) |
| `workplans/` | Workplan files carrying implementation tasks, registered with the State Hub and conforming to its conventions. | Task Model |
| `docs/` | Documentation targeted at stakeholders (users, developers, humans, agents). Rewritten when stale to match what the repo actually does. | Information Space |
| `wiki/` | Interconnected, perspective-free collective knowledge; powerful when backed by a wiki UI for collaboration. | Information Space |
| `issues/` | A mirror of relevant open tickets from an external ticket system, for ease of access. The external system remains the system of record. | Task Model (mirror, not source of truth) |
| `history/` | Material no longer needed for daily work but worth keeping. `yymmdd-` prefixed by archival date; consulted only when research or diagnostics require it, so it does not clutter working memory. | Task Model (lifecycle) + Information Space (archive) |

## 4.1 No-collapse rules

- `demand/` holds un-reviewed `DemandSignal`s; `workplans/` holds committed Tasks.
  Demand is **pre-work** and must not be treated as a Task until reviewed.
- `issues/` is a **mirror**; it does not own ticket state.
- `docs/` is stakeholder-facing truth-to-current-behavior; `wiki/` is
  perspective-free collaborative knowledge; `research/` is dated exploration.
  These are distinct and not interchangeable.
- Finished or canceled workplans **move** from `workplans/` to `history/`.

# 5. Naming Conventions

- **`yymmdd-` prefix** — required for entries in `research/` and `history/`. It
  records *when* an exploration was performed or *when* material was archived,
  giving a chronological, sortable retrieval order. A multi-file exploration uses
  a `yymmdd-` prefixed subdirectory.
- Specification documents in `spec/` use stable, self-describing names
  (`ProductRequirementsDocument.md`, etc.) so they are addressable by convention.

# 6. SCOPE→INTENT Operating Mode

The standard adopts the operating mode named in the source demand and described by
the **Intent Scope Purposes Pattern**:

```text
INTENT defines where the repository is going.
SCOPE  defines where the repository currently is.
Work   = closing the gap from SCOPE to INTENT,
         refining both as learning accrues.
```

`demand/` feeds candidate gap-closers in; reviewed demand becomes `workplans/`
work; `research/` records what was learned while closing the gap; `history/`
retires what is done. This makes the *reason* a repository's interfaces, specs,
and scope evolve traceable rather than accidental.

# 7. Conformance

Because the source is explicit that the layout is a recommendation, conformance is
**graded**. A repository declares its `LayoutConformanceLevel`:

| Level | Requirement |
| --- | --- |
| `minimal` | `INTENT.md` and `SCOPE.md` exist at the root. |
| `core` | `minimal` plus `demand/`, `workplans/`, and `docs/` are present and used as defined. |
| `full` | `core` plus `research/`, `spec/`, `wiki/`, `issues/`, and `history/` are present, with the `yymmdd-` prefix honored in `research/` and `history/`. |

A repository MAY omit any directory it does not need and still claim the highest
level it satisfies. Conformance is self-declared; this standard provides the
vocabulary, not an enforcement gate.

# 8. Anti-Patterns

- **Demand-as-task** — promoting raw `demand/` items straight into work without a
  review/decision trail. Route them through demand review first.
- **Scope creep by directory** — letting `spec/` or `docs/` silently redefine
  `SCOPE.md`; scope changes belong in `SCOPE.md` under governance.
- **Working-memory clutter** — keeping dead material in active directories instead
  of moving it to `history/`.
- **Undated exploration/archive** — `research/` or `history/` entries without a
  `yymmdd-` prefix, losing chronological retrievability.
- **Mirror-as-source** — editing `issues/` as if it were the ticket system of
  record.

# 9. Relationship to This Repository

`info-tech-canon` is itself a producer repository and a candidate adopter. The
reconciliation of this standard against the canon's own layout — and the decision
about how far the canon dogfoods it — is recorded alongside this standard's
evaluation pack (see the repository-layout reconciliation notes). Note that the
canon's `infospace/` uses a distinct **kernel/models/standards** content layout,
which is a separate concern from this **documentation** layout.