generated from coulomb/repo-seed
ITC-WP-0012: integrate Repository Layout Standard
Register the InfoTechCanon Repository Layout Standard as a domain standard (itc-repo-layout), processed from demand through the canon's Purpose/Demand intake without collapsing existing model concepts. - Register standard in artifacts/index.yaml, canon.yaml, infospace.yaml; regenerate indexes, views, briefs, tree, and validation (validate green). - T04: add reconciliation.yaml (partial/as-is dogfooding, declared core conformance, recorded tensions); resolve the demand by moving it out of demand/ to the evaluation pack as source-demand.md and removing demand/. - T05: add consumer-adoption-brief.md for downstream repos. - Update test artifact/standard counts (60->61, standards 2->3). - Mark T03/T04/T05 done; workplan and registry status -> finished. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,214 @@
|
||||
---
|
||||
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.
|
||||
Reference in New Issue
Block a user