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

id, title, short_name, type, standard_family, repository_context, recommended_path, status, version, canonical_owner, namespace, classification, primary_cluster, conformance_posture, imports, related, owned_concepts, provenance

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

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 DemandSignals; 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:

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.