coulomb/info-tech-canon
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

ITC-WP-0012: integrate Repository Layout Standard

Browse Source 
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:
Bernd Worsch
2026-06-13 14:25:54 +02:00
parent 0ce66ef784
commit f7ad73d9da
28 changed files with 1145 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files

62
infospace/evaluations/repository-layout/consumer-adoption-brief.md Normal file
View File

@@ -0,0 +1,62 @@
---
id: repository-layout/consumer-adoption-brief
title: Repository Layout Standard Consumer Adoption Brief
status: candidate
standard: standard/repository-layout
workplan: ITC-WP-0012
---
# Repository Layout Standard Consumer Adoption Brief
## Purpose
Use this brief as the seed for adopting the InfoTechCanon Repository Layout
Standard in a consumer repository. The adoption and any repo-specific
implementation belong in the consumer's own repository, not in InfoTechCanon
(same boundary as WP-0009 — `repository scope` is producer-only).
The layout is a **recommendation, not a strict requirement**. Adopt the parts
that fit and declare the conformance level you reach.
## Canon Inputs
- `infospace/standards/repository-layout/InfoTechCanonRepositoryLayoutStandard.md`
- `infospace/evaluations/repository-layout/source-demand.md`
- `infospace/evaluations/repository-layout/placement-decision.yaml`
- `infospace/evaluations/repository-layout/reconciliation.yaml`
- `infospace/models/governance/InfoTechCanonPurposeDemandExtension.md`
- `infospace/patterns/intent-scope-purposes.md`
## Adoption Steps For A Consumer Repo
1. Add `INTENT.md` and `SCOPE.md` at the repository root, keeping intent
(aspiration) and scope (current boundary) distinct — do not collapse them.
2. Decide which canonical directories the repo needs from the set
`research/ demand/ spec/ workplans/ docs/ wiki/ issues/ history/`, mapping
each to the canon model it references (Information Space, Governance,
Purpose/Demand, Task) rather than redefining those concepts.
3. Route un-reviewed inbound through `demand/`; promote to `workplans/` only
after a review/decision trail (no demand-as-task).
4. Apply the `yymmdd-` prefix in `research/` and `history/` so explorations and
archives stay chronologically retrievable.
5. Adopt the SCOPE→INTENT operating mode: work = closing the gap from current
SCOPE to target INTENT, refining both as learning accrues.
6. Declare a `LayoutConformanceLevel` (`minimal` / `core` / `full`) for the repo
and record which directories are intentionally omitted.
## Expected Outputs (in the consumer repo)
- root `INTENT.md` and `SCOPE.md`,
- the chosen canonical directories in use as defined,
- a declared conformance level,
- a short note on intentional omissions and any repo-specific deviations.
## Non-Goals
- Do not modify the Repository Layout Standard from a consumer workplan without a
canon-side EvolutionRequest.
- Do not treat the layout as mandatory; partial conformance is valid.
- Do not let `spec/` or `docs/` silently redefine `SCOPE.md`; scope changes
belong in `SCOPE.md` under governance.
- Do not edit `issues/` as if it were the ticket system of record (it is a
mirror).

116
infospace/evaluations/repository-layout/demand-intake.yaml Normal file
View File

@@ -0,0 +1,116 @@
id: demand/repository-layout/intake
title: Canonical Repository Layout Demand Intake
status: reviewed
type: demand-intake
uses:
- model/purpose-demand-extension
- model/governance
source:
artifact: infospace/evaluations/repository-layout/source-demand.md
arrival_surface: demand/
arrival_note: >-
Arrived in the repo-level demand/ inbound directory, which the source
document itself defines as un-reviewed inbound. Processed here as a
DemandSignal before any canon artifact is authored.
captured_date: "2026-06-08"
resolution:
resolved_date: "2026-06-13"
moved_to: infospace/evaluations/repository-layout/source-demand.md
note: >-
Now reviewed, the raw demand left the demand/ inbound directory (per the
standard's own rule) and is retained as the captured original beside this
evaluation pack. The repo-root demand/ directory was emptied and removed.
follow_up_owner: canon
consumer_purpose:
id: purpose/canonical-repository-layout
concept: ConsumerPurpose
consumer: bernd-worsch / cross-domain (custodian, railiance, markitect, coulomb_social, personhood, foerster_capabilities, netkingdom)
anchored_in: >-
Consumer intent to make documentation across many repositories
retrieval-oriented and uniform, so humans and agents can find the right
information at the right working-memory cost.
declared_purpose: >-
A canonical, recommendation-level documentation layout for repositories —
INTENT.md / SCOPE.md plus research/, demand/, spec/, workplans/, docs/,
wiki/, issues/, history/ — with a SCOPE-to-INTENT gap-closing operating mode.
use_case:
id: usecase/uniform-doc-retrieval
concept: UseCase
description: >-
A maintainer or agent entering any conforming repository can locate
intent, current scope, raw demand, specs, active work, stakeholder docs,
collaborative wiki, mirrored tickets, and archived material by directory
convention rather than per-repo discovery.
demand_signal:
id: signal/repository-layout-recommendation
concept: DemandSignal
observation: >-
An explicit, written recommendation for a canonical repository documentation
layout, distilled from lived practice and offered to the canon to "pick up".
signal_type: explicit-request
strength: single-but-high-intent
provenance:
prior_art:
- CoulombSocial
- HelixForge
- MarkiTect
note: >-
Layout is presented as evolved best practice from these three repos'
documentation experience; yawex prior-art material is named as research/
content. Background doc types (PRD / TechSpec / UseCaseCatalog /
ArchitectureBlueprint) reference the InfoTechPrimers space on coulomb.social.
consumer_need:
id: need/uniform-retrievable-docs
concept: ConsumerNeed
description: >-
Need for a shared, low-friction documentation structure that keeps working
memory uncluttered (history/ out of daily scope) and routes inbound
demand through systematic review (demand/ -> tasks/workplans).
horizon: current
# Preliminary fit only — the binding PurposeFit / placement decision is T02.
preliminary_purpose_fit:
concept: PurposeFit
state: gap
rationale: >-
The canon owns adjacent concepts (Information Space for knowledge packaging
and retrieval; Governance + Purpose/Demand for INTENT/SCOPE/PURPOSES and the
demand/ intake surface; Task for workplans/history) but does not yet own a
named cross-cutting convention that prescribes a canonical repository
documentation directory set. This is a producer-facing convention the canon
does not currently provide.
matched_canon:
- model/information-space
- model/governance
- model/purpose-demand-extension
- model/task
- pattern/intent-scope-purposes
note: Binding fit evaluation and ownership mapping are deferred to T02.
scope_pressure:
concept: ScopePressure
state: flagged-for-review
current_scope_ref: SCOPE.md
pressure: >-
SCOPE.md currently frames the repo as a seed corpus of kernel/models/
standards/profiles/patterns and does not promise a producer-facing repository
documentation-layout convention. Adopting this demand would extend the canon
to own such a convention (working hypothesis: a new standard), so it must go
through governance scope-pressure review rather than silently expanding scope.
alignment_with_producer_intent: >-
Aligns with the canon's stated purpose of providing interoperable, retrievable
structures and seed conventions for infospaces and agent use; the convention
is recommendation-level, matching the canon's non-coercive posture.
recommended_disposition: add_standard_candidate
decision_authority: canon governance
review_gate: ITC-WP-0012-T02
disposition:
intake_outcome: accepted_for_analysis
next_step: >-
Proceed to T02 placement decision (review gate): decide canon ownership,
map each layout element to an existing model, and emit explicit placement +
extension candidates before any standard text is written.
no_artifact_authored: true

163
infospace/evaluations/repository-layout/placement-decision.yaml Normal file
View File

@@ -0,0 +1,163 @@
id: demand/repository-layout/placement-decision
title: Canonical Repository Layout Placement Decision
status: reviewed
type: placement-decision
review_gate: ITC-WP-0012-T02
uses:
- model/purpose-demand-extension
- model/governance
inputs:
demand_intake: infospace/evaluations/repository-layout/demand-intake.yaml
source_artifact: infospace/evaluations/repository-layout/source-demand.md
# ---------------------------------------------------------------------------
# Decision: where does this convention belong in the canon line of structures?
# ---------------------------------------------------------------------------
decision:
placement: standard
proposed_id: itc-repo-layout
proposed_title: InfoTechCanonRepositoryLayoutStandard
proposed_path: infospace/standards/repository-layout/InfoTechCanonRepositoryLayoutStandard.md
conformance_posture: recommendation
rationale: >-
The proposal is a named, cross-cutting documentation convention that spans
several existing models without redefining any of them — the canon's own
definition of a Standard ("cross-cutting conventions or named analytical/
design frameworks", canon.yaml classification). It is a sibling to the
Tagging and CARING standards, not a domain model (it introduces no new domain
entities), not a profile (it is not a concrete proof of a model against a
scenario), and not a pattern (it prescribes a directory contract, not a
reusable solution shape). The source is explicit that it is a recommendation,
so conformance is graded, not mandatory.
rejected_alternatives:
- placement: model
why_not: >-
Would imply new domain concepts the canon must own permanently; the
convention instead references concepts already owned by Information
Space, Governance, Purpose/Demand, and Task.
- placement: profile
why_not: >-
Profiles are concrete proofs of models against a scenario (e.g.
small-saas); a repository documentation layout is a general convention,
not a scenario proof.
- placement: pattern
why_not: >-
Patterns capture a context/problem/solution shape (e.g.
intent-scope-purposes); the demand is a prescriptive directory set and
operating mode, which reads as a standard, not a pattern. The standard
may cite the intent-scope-purposes pattern.
# ---------------------------------------------------------------------------
# Ownership map: each layout element points at the model that already owns the
# concepts it relies on. The standard REFERENCES these; it must not redefine.
# ---------------------------------------------------------------------------
ownership_map:
- element: "INTENT.md / SCOPE.md + SCOPE->INTENT gap-closing operating mode"
owned_by:
- model/governance
- model/purpose-demand-extension
- pattern/intent-scope-purposes
note: >-
INTENT/SCOPE/PURPOSES distinction and the gap-closing loop are already
owned. The standard cites them and locates them as repo-root files.
no_collapse: Keep INTENT vs SCOPE vs PURPOSES distinct.
- element: "demand/"
owned_by:
- model/purpose-demand-extension
note: >-
The raw inbound surface for DemandSignal capture before review. This very
workplan dogfooded it (demand/CanonicalRepositoryLayout.md).
no_collapse: demand/ holds un-reviewed DemandSignals, not Tasks.
- element: "research/"
owned_by:
- model/information-space
note: >-
Exploration results in problem/solution space; yymmdd-prefixed. Knowledge
packaging and retrieval are Information Space concerns.
- element: "spec/ (PRD / TechSpec / UseCaseCatalog / ArchitectureBlueprint)"
owned_by:
- model/governance
- model/information-space
note: >-
Specs provide guardrails (Governance directive surface) packaged as
retrievable knowledge (Information Space). Doc-type background lives in the
InfoTechPrimers space on coulomb.social (external reference).
- element: "workplans/"
owned_by:
- model/task
note: >-
Workplans carry Tasks, registered with the State Hub. Task Model owns
backlog/readiness/commitment/progress/completion semantics.
no_collapse: Workplan/Task are work structure; demand/ is pre-work.
- element: "docs/"
owned_by:
- model/information-space
note: Stakeholder-facing documentation (users, developers, humans, agents).
- element: "wiki/"
owned_by:
- model/information-space
note: Interconnected collective knowledge without a fixed perspective.
- element: "issues/"
owned_by:
- model/task
note: >-
Mirror of an external ticket system to ease access; maps to the Task Model
surface. The standard treats it as a mirror, not the system of record.
- element: "history/"
owned_by:
- model/task
- model/information-space
note: >-
Archive of finished/canceled material; yymmdd-prefixed; out of scope for
daily working memory. Finished/canceled workplans move here (Task
lifecycle) and archived knowledge persists (Information Space).
# ---------------------------------------------------------------------------
# Placement + extension candidates (WP-0009 discipline: explicit, reviewable,
# no silent edits to existing standards/models).
# ---------------------------------------------------------------------------
candidates:
- id: candidate/repository-layout-standard
change_type: new-standard
target: infospace/standards/repository-layout/
summary: >-
Author the InfoTechCanonRepositoryLayoutStandard defining the canonical
directory set, yymmdd-prefix conventions (research/, history/), and the
SCOPE->INTENT operating mode, referencing existing model concepts.
disposition: approved-for-T03
- id: candidate/canon-registration
change_type: registration
target:
- canon.yaml (standards:)
- infospace/infospace.yaml (disciplines:)
- artifact index + retrieval generation
- validation.py structural checks
summary: Register the new standard so it is loaded, indexed, retrievable, and validated.
disposition: approved-for-T03
- id: candidate/conformance-levels
change_type: standard-internal
target: infospace/standards/repository-layout/
summary: >-
Define graded conformance (e.g. minimal / core / full) so adopting repos
can be partial-conformant, honoring the source's recommendation posture.
disposition: approved-for-T03
- id: candidate/dogfood-canon-repo
change_type: repo-reconciliation
target: info-tech-canon repo layout
summary: >-
Reconcile this repo's own layout against the standard and record tensions
(repo already uses spec/, wiki/, workplans/, seeds/; infospace uses the
distinct kernel/models/standards layout). Decide dogfooding extent.
disposition: deferred-to-T04
- id: candidate/consumer-adoption-brief
change_type: consumer-brief
target: infospace/agent/consumer-briefs/ (or evaluations pack)
summary: >-
Adoption brief so the seven tracked domains can opt in from their own
repos; per-repo adoption work stays in consumer repos (WP-0009 boundary).
disposition: deferred-to-T05
disposition:
outcome: extend_scope_via_new_standard
recommended_next_step: Proceed to T03 — author and register the standard.
no_silent_edits: true

80
infospace/evaluations/repository-layout/reconciliation.yaml Normal file
View File

@@ -0,0 +1,80 @@
# Repository Layout Standard — reconciliation against info-tech-canon's own layout
# ITC-WP-0012-T04. Resolves placement-decision candidate/dogfood-canon-repo.
type: repo-reconciliation
workplan: ITC-WP-0012
task: ITC-WP-0012-T04
standard: standard/repository-layout
created: "2026-06-13"
decision:
dogfood_extent: partial
declared_conformance_level: core
summary: >-
info-tech-canon adopts the Repository Layout Standard at recommendation
level, as-is. It already satisfies the core level and is not restructured to
chase full conformance now. The infospace/ content layout is explicitly out
of scope of this documentation-layout convention.
current_layout:
root_documents:
- INTENT.md # present — Governance (Intent)
- SCOPE.md # present — Governance (Scope)
directories_present:
- demand/ # transient inbound; emptied + removed after this demand was resolved
- spec/ # present
- wiki/ # present
- workplans/ # present; State-Hub-registered
- seeds/ # repo-specific: RC seed corpus, not part of the standard's set
- infospace/ # the concrete infospace content (distinct layout, see tension below)
- src/ tests/ # Python service shell, not documentation directories
directories_absent:
- research/ # no dated explorations packaged yet
- docs/ # stakeholder docs live inside infospace/ today
- issues/ # no external-ticket mirror maintained here
- history/ # finished workplans tracked via status, not yet relocated
conformance_assessment:
minimal: satisfied # INTENT.md + SCOPE.md at root
core: satisfied # + demand/ (as-needed), workplans/, docs-equivalent in infospace/
full: not_satisfied # research/, issues/, history/ and yymmdd- prefixes not adopted
note: >-
Conformance is self-declared and graded (standard §7). The canon claims
'core' and omits directories it does not currently need.
tensions:
- id: infospace-content-layout
tension: >-
infospace/ uses a kernel/models/standards/profiles/patterns CONTENT layout,
which is a different concern from this DOCUMENTATION layout. The standard's
§9 already calls this out; the two layouts coexist and are not reconciled
into one.
resolution: keep_distinct
- id: seeds-directory
tension: >-
seeds/ is repo-specific (RC seed corpus) and has no slot in the standard's
canonical set.
resolution: out_of_scope_repo_specific
- id: docs-location
tension: >-
Stakeholder/agent documentation lives under infospace/ (agent briefs,
views, retrieval indexes) rather than a root docs/. Functionally covers the
docs/ purpose without the directory name.
resolution: satisfied_by_equivalent
- id: history-relocation
tension: >-
Finished/canceled workplans currently stay in workplans/ with a status
field rather than moving to history/. The standard recommends relocation.
resolution: deferred
note: >-
Not adopted now to avoid churn against State-Hub workplan conventions;
revisit if workplans/ grows large enough to clutter working memory.
dogfood_actions_taken:
- This demand was processed through demand/ and, once reviewed, the raw file
left demand/ for the evaluation pack (source-demand.md); the empty demand/
directory was removed — exercising the standard's own demand-resolution rule.
not_done_now:
- Creating research/, issues/, or history/ directories.
- Relocating finished workplans to history/.
- Restructuring infospace/ (explicitly a separate content-layout concern).

32
infospace/evaluations/repository-layout/source-demand.md Normal file
View File

@@ -0,0 +1,32 @@
This is a canonical layout for repository contained documentation information. There are various perspectives
on why to document what how. This guide provides a system to allow for efficient retrieval of information.
The structure is based in best practices from the CoulombSocial, HelixForge, MarkiTect experiences and will evolve over time.
This is a recommendation not a strict requirement.
Please base the layout of repositories on the following outline:
INTENT.md captures the aspiration and boundries. We will be working to explore the problemspace and implement a
solution and capture a top level view of what we achieve in a SCOPE.md file.
Our mode of operation will be closing the gap of SCOPE to INTENT while learning and refining both where necessary. There should be a canonical set of directories for documentation structuring our mode of work as follows.
research/ is a directory to provide results about explorations in the problem and solution space. Each exploration should have a yymmdd-prefix to the markdown file or subdirectory if multiple files or sources are provided. The yawex prior art stuff should go there.
demand/ is a inbound directory for feature requests, requirements, suggestions and opportunities to improve.
This directory should contain what has not been systematically reviewed and captured in tasks or workplans.
Information here can be raw and needs additional scrutiny to decide if the implementation should pick up on
the demand and how.
spec/ is a directory for specification files that provide guidance and guardrails for the implementation. Typically we will establish a ProductRequirementsDocument.md and TechnicalSpecificationDocument.md and maybe UseCaseCatalog.md and ArchitectureBlueprint.md files. Background information on those types of documents can be found in the InfoTechPrimers space on coulomb.social.
workplans/ is a directory for all workplan.md that contain tasks for implementation. Those will be registered with the statehub and should conform to the standards provided by the statehub infrastructure. Workplans that have been finished or canceled should move to history
docs/ is a directory for documentation targeted at stakeholders for the repo be it users, developers, humand or agents. If documentation is wrong or stale it can and should be rewritten based on what the repo actually does.
wiki/ is a directory for interconnected collective gathering of information without a specific perspective. This
directory is powerful if connected with an wiki ui where creators, users and investors can collaborate.
issues/ all or some of this information might be captured systematically as tickes in a ticket system.
This directory can provide a mirror of relevant open tickets to ease access to the information from customer
support, dev-sec-ops work organization tickets and the like.
history/ is a directory to move material to that is no longer needed but should be kept around. Use yymmdd-prefix to mark when some file or directory has been archived. Stuff in history should only be considered if some research or diagnostic needs it. Files here are out of scope for regular daily tasks to not boggle down working memory unnecessarily.