{ "commit": "4088f5a1d23be63f43953ed1eae5eb1740f6eb8d", "root": "Meta-model", "rootId": null, "types": [ { "type": "core", "folder": "core", "owner": null }, { "type": "landscape", "folder": "landscape", "owner": null }, { "type": "organization", "folder": "organization", "owner": null }, { "type": "requirements", "folder": "requirements", "owner": null }, { "type": "software", "folder": "software", "owner": null } ], "entities": [ { "id": "01a0b09c-6e48-7e25-abfc-8efc23e2d25a", "address": "core/achievement-kind", "type": "core", "name": "Achievement Kind Schema", "tagline": "Required structure for achievement kind files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "The kind's position within an entry. Spaced in tens so a kind can be added without renumbering the others." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "The kind's position within an entry. Spaced in tens so a kind can be added without renumbering the others." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every heading that groups achievements references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the kind covers" ], [ "`## What it means`", "Yes", "Which achievements belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a framework, a standard" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every heading that groups achievements references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the kind covers" ], [ "`## What it means`", "Yes", "Which achievements belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "An achievement kind answers \"what sort of claim is this bullet?\" — the question a reader cannot otherwise ask of a list that holds a decision, a delivery and an outcome side by side. Its value is that the answer is a reference rather than a word: two bullets under the same kind mean the same sort of thing across every entry, the kinds are visible in the graph as nodes, and changing what a kind covers is one edit rather than a pass over every period.", "tables": [] }, { "heading": "Writing rules", "text": "- `## What it means` says what the kind excludes as well as what it covers, since the boundary\n with the kind beside it is where every disagreement will be. How to decide between two kinds\n is written here, in the instance, and nowhere else.\n- `## What it means` is about the sort of claim, never about how important it is. Importance is\n not an order the model can hold.\n- The H1 names what the claims are — `Architecture`, `Results` — and never the section they sit\n in.", "tables": [] }, { "heading": "File Location", "text": "`model/achievement-kinds/*.md`\n\nA kind owns nothing and nothing owns it: many experiences group their achievements under the same few, and what each kind covers lives here rather than being restated in every entry. It sits at the container root beside `experience-kinds/` rather than inside a profile, because every profile's experiences group by the same set.\n\nThe set is deliberately the instance's own. Which groups a career needs is a fact about that career — a researcher's work falls by publication and grant, a salesperson's by territory and account — and a kind arriving later is one file here, not a change to this metamodel and a release of it.", "tables": [] } ], "owner": null, "path": "core/achievement-kind-schema.md" }, { "id": "01a0d905-a160-77e9-b344-4f37b52b849e", "address": "core/brand", "type": "core", "name": "Brand Schema", "tagline": "Required structure for the brand file — what the company looks and sounds like.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The name the brand goes by — the one the mark spells and the lockup carries" ], [ "`> [Promise]`", "Yes", "One-paragraph statement of what carrying this name promises a reader" ], [ "`## Mark`", "Yes", "Bulleted. What the mark is, in a sentence, then one rule per item: clear space, minimum size, what it sits on" ], [ "`## Color`", "Yes", "Table. One row per color role; its columns are declared below." ], [ "`## Typography`", "Yes", "Table. One row per typeface; its columns are declared below." ], [ "`## Voice`", "Yes", "Table. One row per trait of the company's voice; its columns are declared below." ], [ "`## References`", "Yes", "Table. Where the values are: the tokens, the mark's file, the rulebook; its columns are declared below." ] ] }, { "caption": "`## Color` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Name`", "Yes", "string", "The role's name as the place that masters its value spells it — a token, a swatch name" ], [ "`Means`", "Yes", "string", "What a thing painted in it is saying" ], [ "`Never`", "Yes", "string", "The one misuse it is most often put to" ] ] }, { "caption": "`## Typography` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Face`", "Yes", "string", "The typeface's name as its foundry writes it" ], [ "`Job`", "Yes", "string", "What it sets, and nothing about how" ] ] }, { "caption": "`## Voice` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Trait`", "Yes", "string", "One word for a way the company writes" ], [ "`Means`", "Yes", "string", "What a sentence with the trait does" ], [ "`Never`", "Yes", "string", "What a sentence without it does, specifically" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of file — the tokens, the mark, the rulebook" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The name the brand goes by — the one the mark spells and the lockup carries" ], [ "`> [Promise]`", "Yes", "One-paragraph statement of what carrying this name promises a reader" ], [ "`## Mark`", "Yes", "Bulleted. What the mark is, in a sentence, then one rule per item: clear space, minimum size, what it sits on" ], [ "`## Color`", "Yes", "Table. One row per color role; its columns are declared below." ], [ "`## Typography`", "Yes", "Table. One row per typeface; its columns are declared below." ], [ "`## Voice`", "Yes", "Table. One row per trait of the company's voice; its columns are declared below." ], [ "`## References`", "Yes", "Table. Where the values are: the tokens, the mark's file, the rulebook; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "The brand is what the company looks and sounds like wherever it appears, stated as meaning rather than measure, so that a person or an agent producing anything in the company's name reads one file, finds what each color, face, mark and trait is for, and follows a reference to the bytes. It answers \"what does this look and sound like, and why?\" for someone writing a post, cutting a tile or reviewing a draft. It is not the palette and not the stylesheet, which are built and kept where the References rows point, and it is not the positioning, which the identity's tagline, the vision and the values already hold.", "tables": [] }, { "heading": "Writing rules", "text": "- The page holds no hex code, size, weight, line height or file dimension anywhere. A value\n moves with a release, and a References row says where it is kept.\n- A `## Color` row is named as the place that masters its value names it, so a reader can find\n it there by the same string.\n- A `Means` cell says what a thing in that color, or a sentence with that trait, is saying; a\n `Never` cell names one specific misuse, not the absence of the trait. \"Never decoration\" can be\n checked; \"never misused\" cannot.\n- A `Job` names what a face sets in the words the page uses for it — prose, the ledger, a section\n mark — and says nothing about how it is set.\n- A `Trait` is one a draft can fail. \"Plain\" fails a sentence with an adjective that sells;\n \"professional\" fails nothing.\n- `## Voice` speaks in the company's first person, \"I\" for a company of one and \"We\" for a company\n of more, the same one the instance's values use.\n- `## Mark` says where the shape is mastered and never carries a copy of it, so the mark has one\n source and every render is made from it.\n- The promise is one paragraph and keeps positioning out: what the company is, where it is going\n and what it holds to are the identity's, the vision's and the values' to say.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/brand.md`\n\nA company has one brand, so the type is a file directly in the container rather than a folder (R6, R13), named for the type rather than for the slug of its H1 (R12), which leaves the H1 free to be the name the brand goes by.", "tables": [] } ], "owner": null, "path": "core/brand-schema.md" }, { "id": "01a0c233-ae50-7e67-96c8-bb9a8d116ca7", "address": "core/concept", "type": "core", "name": "Concept Schema", "tagline": "Required structure for concept files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`domain`", "Yes", "ref → domain", "The area of the vocabulary this concept belongs to — the H1 of a file in `domains/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`domain`", "Yes", "ref → domain", "The area of the vocabulary this concept belongs to — the H1 of a file in `domains/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Concept]`", "Yes", "The canonical name of the concept. Every reference to it, from any domain, uses this exact string." ], [ "`> [Definition]`", "Yes", "One-paragraph definition of what the concept is" ], [ "`## Also known as`", "No", "Table. The other names this concept goes by, none of which resolves." ], [ "`## Relations`", "No", "Table. What this concept points at." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the term; its columns are declared below." ] ] }, { "caption": "`## Also known as` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Term`", "Yes", "string", "The other name" ], [ "`Kind`", "Yes", "enum", "`synonym`, `abbreviation`, `translation` or `deprecated`. What the other name is: a second word for the same thing, a short form of it, the same thing in another language, or a name this concept used to go by." ] ] }, { "caption": "`## Relations` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Concept`", "Yes", "ref → concept", "What this concept points at, by its canonical name" ], [ "`Cardinality`", "Yes", "enum", "`one`, `maybe one`, `many` or `one to many`. How many of the target one of these has: exactly one, none or one, none or more, or one or more." ], [ "`As`", "No", "string", "The role the target plays in this relation. Required where two rows name the same concept, which is the only thing that tells them apart." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a standard, a glossary" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Concept]`", "Yes", "The canonical name of the concept. Every reference to it, from any domain, uses this exact string." ], [ "`> [Definition]`", "Yes", "One-paragraph definition of what the concept is" ], [ "`## Also known as`", "No", "Table. The other names this concept goes by, none of which resolves." ], [ "`## Relations`", "No", "Table. What this concept points at." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the term; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A concept is one word the company means something exact by, and it answers \"what do we mean when we say this, and what does it hang off?\" for anyone reading a feature, a process or a seat that names it. It is an entity rather than a heading in a glossary so that a file can cite it, a rename is caught everywhere at once, and the relations between the company's words are rows a check resolves instead of lines in a drawing. A relation is written on one side only, so no two concepts each name the other in `## Relations`.", "tables": [] }, { "heading": "Writing rules", "text": "- The definition says what the thing is, not what a system does with it, and it is written so that someone outside the company could tell one of these from something adjacent.\n- The definition never carries a concept this one hangs off dressed as a link; that concept belongs in `## Relations`, where it resolves.\n- `As` is the name the target goes by in this relation, written as the company says it: `booker`, `primary guest`, `included services`.\n- A `Term` of kind `translation` is the concept's name in a language other than the one the model is written in: what a French customer calls it, in a model kept in English.", "tables": [] }, { "heading": "File Location", "text": "`model/concepts/*.md`\n\nA concept owns nothing, so it is a file, and nothing owns a concept: it sits in the container rather than inside its domain so that a concept of one domain can be named by a concept of another, which an owned name cannot be.", "tables": [] } ], "owner": null, "path": "core/concept-schema.md" }, { "id": "01a0fb19-9589-70e2-aa4e-923ff81c01a8", "address": "core/control", "type": "core", "name": "Control Schema", "tagline": "Required structure for control files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`kind`", "Yes", "enum", "`preventive`, `detective` or `corrective`. Whether it stops the event, finds it, or repairs what it did (COSO; ISO/IEC 27002 control type)." ], [ "`mode`", "Yes", "enum", "`automated` or `manual`. Whether a machine or a person carries it out (COSO)." ], [ "`mitigates`", "No", "array of ref → risk", "The risks it makes less likely or less harmful, each the H1 of a file in `risks/`" ], [ "`enforces`", "No", "array of ref → rule", "The rules it holds a change or an action to, each the H1 of a file in `rules/`" ], [ "`performed-by`", "No", "ref → seat", "The seat that carries it out, for a manual control, the H1 of a file in `seats/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`kind`", "Yes", "enum", "`preventive`, `detective` or `corrective`. Whether it stops the event, finds it, or repairs what it did (COSO; ISO/IEC 27002 control type)." ], [ "`mode`", "Yes", "enum", "`automated` or `manual`. Whether a machine or a person carries it out (COSO)." ], [ "`mitigates`", "No", "array of ref → risk", "The risks it makes less likely or less harmful, each the H1 of a file in `risks/`" ], [ "`enforces`", "No", "array of ref → rule", "The rules it holds a change or an action to, each the H1 of a file in `rules/`" ], [ "`performed-by`", "No", "ref → seat", "The seat that carries it out, for a manual control, the H1 of a file in `seats/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Control]`", "Yes", "The control's name. Everything references the control by this exact string." ], [ "`> [What it does]`", "Yes", "What the control does, in one sentence" ], [ "`## How it is carried out`", "Yes", "What does the work and when, as a reader could check" ], [ "`## Applies to`", "No", "Table. The seats, processes and phases it applies in; its columns are declared below." ], [ "`## References`", "No", "Table. The hook, the workflow, the command or the checklist, and where its results are kept; its columns are declared below." ] ] }, { "caption": "`## Applies to` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Type`", "Yes", "string", "The type of the entity this row names, as its schema is named: `seat`, `process` or `phase`" ], [ "`Entity`", "Yes", "ref → by Type in Owner", "The seat, process or phase, by its canonical name" ], [ "`Owner`", "No", "string", "For a phase, the process that owns it, by its canonical name; blank otherwise" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of thing, a hook, a workflow, a checklist, a test report" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Control]`", "Yes", "The control's name. Everything references the control by this exact string." ], [ "`> [What it does]`", "Yes", "What the control does, in one sentence" ], [ "`## How it is carried out`", "Yes", "What does the work and when, as a reader could check" ], [ "`## Applies to`", "No", "Table. The seats, processes and phases it applies in; its columns are declared below." ], [ "`## References`", "No", "Table. The hook, the workflow, the command or the checklist, and where its results are kept; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A control is what the company does, or has a machine do, so that a risk is less likely or less harmful, or a rule is kept (ISO 31000: a measure that maintains or modifies risk; COSO's control activities). It answers \"what actually stops this, finds it, or repairs it, and is it a machine or a person?\" The control is the entity: a gate's criteria and a check's code stay where they are, and the control says in prose how it is carried out and points at the file that does it. How well it works is measured, where the company measures it, by a KPI that names it in `assesses`, never by a number on this page.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 names a control that mitigates at least one risk or enforces at least one rule, and `mitigates` or `enforces` names that risk or rule. The grammar declares each field on its own, so this rule is the agent pass's to hold.\n- `## How it is carried out` says what does the work and when, as a reader could check: \"the seat check, run by the commit hook and again by the instance check on every pull request, refuses a commit whose seat the named phase does not list\". The hook, the workflow or the command it names goes in `## References`.\n- `## Applies to`, on a control that is a phase's gate, names that phase, and the gate's criteria stay the phase's bullets.\n- `mode` decides `performed-by`: a manual control names a seat there, never a person, and an automated control names none.\n- An `## Applies to` row names a seat, a process or a phase; the grammar reads any type in the Type column, so this is the agent pass's to hold.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/controls/*.md`\n\nNothing owns a control and a control owns nothing: it reaches across the processes and phases it applies in and names the risks and rules it answers to.", "tables": [] } ], "owner": null, "path": "core/control-schema.md" }, { "id": "01a10522-0ea5-7706-b34d-71f2af083427", "address": "core/data-processor", "type": "core", "name": "Data Processor Schema", "tagline": "Required structure for data processor files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`legal-name`", "Yes", "string", "The legal entity the company's contract is with, which may differ from the H1 and from one region to another" ], [ "`countries`", "Yes", "array", "Where the processor processes and stores the data, each an ISO 3166-1 alpha-2 code; where `processing` is `any`, where it stores what it keeps" ], [ "`processing`", "No", "enum", "`fixed` or `any`. `fixed`, which an absent field means, says the processor processes the data where `countries` says; `any` says it may process a request in any country it chooses, and `countries` names where it stores what it keeps." ], [ "`retention`", "No", "string", "How long the processor keeps what it receives, under its own terms" ], [ "`sub-processor-authorization`", "No", "enum", "`general` or `specific`. Whether the contract lets the processor add sub-processors after notice, or only with the company's approval of each (GDPR Art. 28(2); DSG Art. 9(3))." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`legal-name`", "Yes", "string", "The legal entity the company's contract is with, which may differ from the H1 and from one region to another" ], [ "`countries`", "Yes", "array", "Where the processor processes and stores the data, each an ISO 3166-1 alpha-2 code; where `processing` is `any`, where it stores what it keeps" ], [ "`processing`", "No", "enum", "`fixed` or `any`. `fixed`, which an absent field means, says the processor processes the data where `countries` says; `any` says it may process a request in any country it chooses, and `countries` names where it stores what it keeps." ], [ "`retention`", "No", "string", "How long the processor keeps what it receives, under its own terms" ], [ "`sub-processor-authorization`", "No", "enum", "`general` or `specific`. Whether the contract lets the processor add sub-processors after notice, or only with the company's approval of each (GDPR Art. 28(2); DSG Art. 9(3))." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Data processor]`", "Yes", "The name the company calls the processor by. Everything references the processor by this exact string." ], [ "`> [What it does for the company]`", "Yes", "What the processor does for the company, in one sentence" ], [ "`## Own purposes`", "No", "Bulleted. What the vendor does with the data for purposes it decides itself, where for that processing it is a controller and not the company's processor (GDPR Art. 28(10))" ], [ "`## Transfers`", "No", "Table. What makes the disclosure abroad lawful, for each jurisdiction whose law asks; its columns are declared below." ], [ "`## References`", "Yes", "Table. The data processing agreement, the vendor's sub-processor list, its privacy policy and its retention terms; its columns are declared below." ] ] }, { "caption": "`## Transfers` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Jurisdiction`", "Yes", "enum", "`eu`, `ch` or `uk`. The law that asks for a safeguard: the GDPR, the Swiss DSG or the UK GDPR." ], [ "`Safeguard`", "Yes", "string", "The instrument as that law names it, an adequacy decision, standard contractual clauses and their module, binding corporate rules" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document, a data processing agreement, a sub-processor list, a privacy policy" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Data processor]`", "Yes", "The name the company calls the processor by. Everything references the processor by this exact string." ], [ "`> [What it does for the company]`", "Yes", "What the processor does for the company, in one sentence" ], [ "`## Own purposes`", "No", "Bulleted. What the vendor does with the data for purposes it decides itself, where for that processing it is a controller and not the company's processor (GDPR Art. 28(10))" ], [ "`## Transfers`", "No", "Table. What makes the disclosure abroad lawful, for each jurisdiction whose law asks; its columns are declared below." ], [ "`## References`", "Yes", "Table. The data processing agreement, the vendor's sub-processor list, its privacy policy and its retention terms; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A data processor is a party that processes personal data on the company's behalf (GDPR Art. 4(8); DSG Art. 5 lit. k, «Auftragsbearbeiter»). It answers \"who outside the company handles this data, where, under which contract, and how does it reach them lawfully?\" for whoever writes the privacy page, answers a data subject or reviews a vendor. What the company does with the data, and why, is the processing activity's, which names the processor; the processor names no activity.", "tables": [] }, { "heading": "Writing rules", "text": "- The tagline says what the processor does for the company, not what the vendor sells.\n- `legal-name` is the entity the company's contract is with, as the contract writes it.\n- `countries` lists where the data is processed and stored, not where the vendor is incorporated.\n- `processing` is `any` only where the processor's own terms let it run a request in a country it chooses, and the tagline then says so in words.\n- `retention` is the vendor's period in the vendor's words; the company's own retention is the processing activity's.\n- `## Own purposes` names each purpose the vendor decides for itself, in the words of its terms.\n- Each row of `## Transfers` names the instrument as its jurisdiction's law names it.\n- `## References` carries the vendor's sub-processor list as a row, because the list is the vendor's to keep and to announce changes to (GDPR Art. 28(2)).\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/data-processors/*.md`\n\nNothing owns a data processor and a data processor owns nothing: one vendor serves several of the company's processing activities, and each activity names the processors it uses.", "tables": [] } ], "owner": null, "path": "core/data-processor-schema.md" }, { "id": "01a0dd34-8da0-7631-83df-1cf924855e48", "address": "core/decision", "type": "core", "name": "Decision Schema", "tagline": "Required structure for decision files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`decided`", "Yes", "date", "When the call was made, not when it was carried out. For a call still proposed, when it was put forward." ], [ "`kind`", "Yes", "ref → decision-kind", "What sort of call this is, the H1 of a file in `decision-kinds/`" ], [ "`status`", "Yes", "ref → decision-status", "Whether the call is made and still holds, the H1 of a file in `decision-statuses/`" ], [ "`by`", "Yes", "ref → seat", "The seat that made the call, the H1 of a file in `seats/`. Never the person: who held the seat on that date is the profile's." ], [ "`serves`", "No", "array of ref → strategic-objective", "The objectives this call was made for, each the H1 of a file in `strategic-objectives/`" ], [ "`upholds`", "No", "array of ref → value", "The values the call was weighed against, each the H1 of a file in `values/`" ], [ "`supersedes`", "No", "array of ref → decision", "Earlier calls this one replaces, each the H1 of a file in `decisions/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`decided`", "Yes", "date", "When the call was made, not when it was carried out. For a call still proposed, when it was put forward." ], [ "`kind`", "Yes", "ref → decision-kind", "What sort of call this is, the H1 of a file in `decision-kinds/`" ], [ "`status`", "Yes", "ref → decision-status", "Whether the call is made and still holds, the H1 of a file in `decision-statuses/`" ], [ "`by`", "Yes", "ref → seat", "The seat that made the call, the H1 of a file in `seats/`. Never the person: who held the seat on that date is the profile's." ], [ "`serves`", "No", "array of ref → strategic-objective", "The objectives this call was made for, each the H1 of a file in `strategic-objectives/`" ], [ "`upholds`", "No", "array of ref → value", "The values the call was weighed against, each the H1 of a file in `values/`" ], [ "`supersedes`", "No", "array of ref → decision", "Earlier calls this one replaces, each the H1 of a file in `decisions/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Decision]`", "Yes", "What was decided, stated as a call. Everything references the decision by this exact string." ], [ "`> [Statement]`", "Yes", "One paragraph: the call, in the company's own first person" ], [ "`## The question`", "Yes", "What had to be decided, and why it had to be decided then" ], [ "`## Alternatives`", "Yes", "Table. The options that lost, one row each; its columns are declared below." ], [ "`## Why`", "Yes", "What turned it: the reason the chosen option won, in the terms the call turned on" ], [ "`## Consequences`", "Yes", "What the call committed the company to, what it gave up, and what has to stay true for the call to stay right" ], [ "`## Bears on`", "No", "Table. The entities the call made, changed or ended; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can check the call against; its columns are declared below." ] ] }, { "caption": "`## Alternatives` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Option`", "Yes", "string", "The option, stated as the call it would have been" ], [ "`Why not`", "Yes", "string", "What taking it would have cost, in one or two sentences" ] ] }, { "caption": "`## Bears on` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Type`", "Yes", "string", "The type of the entity this row names, as its schema is named: `product`, `experience`" ], [ "`Entity`", "Yes", "ref → by Type in Owner", "The entity the call bears on, by its canonical name" ], [ "`Owner`", "No", "string", "Where `Type` is an owned type, the entity that owns this one, by its canonical name; blank otherwise" ], [ "`How`", "No", "string", "What the call did to it: made it, changed it, ended it" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document, a specification, a contract, a pull request, a slide" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Decision]`", "Yes", "What was decided, stated as a call. Everything references the decision by this exact string." ], [ "`> [Statement]`", "Yes", "One paragraph: the call, in the company's own first person" ], [ "`## The question`", "Yes", "What had to be decided, and why it had to be decided then" ], [ "`## Alternatives`", "Yes", "Table. The options that lost, one row each; its columns are declared below." ], [ "`## Why`", "Yes", "What turned it: the reason the chosen option won, in the terms the call turned on" ], [ "`## Consequences`", "Yes", "What the call committed the company to, what it gave up, and what has to stay true for the call to stay right" ], [ "`## Bears on`", "No", "Table. The entities the call made, changed or ended; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can check the call against; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A decision is a call the company made on a date, written with the options that lost, so that whoever arrives after it can disagree with a reason rather than a rewrite. It answers \"why is it this way and not the other way, who decided, and does it still hold?\" for someone about to re-open a question that was already closed, or about to act on a call that no longer stands. It is not a strategy, which is the route currently taken and is deleted when replaced; a decision is kept as written for as long as the company exists, and its status says whether it holds. A decision is not rewritten and not removed: `status` is the one field that moves, what replaced the call is read from the later decision's `supersedes`, and every call another supersedes carries one status, never the one most calls still standing carry. A name the decision carries follows the entity it names when that entity is renamed or removed, a `## References` row's `URL` follows the document it points at when that document moves or the address was written wrong on the day, and nothing else moves.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 states what was decided, never the topic: \"Core is vendored at a named release\", not\n \"Core distribution\". A reader who sees only the name knows the call.\n- The statement is a call a reasonable company could have made differently. If no company\n would have chosen otherwise, it describes the work rather than deciding anything.\n- `## The question` names what had to be decided and what made it have to be decided then, a\n deadline, an offer, a finding, and states no reason for the answer; the reasons are `## Why`.\n- `## Alternatives` carries at least one row, and never the option taken. `Why not` names what\n the option would have cost, in the terms the call turned on, not that it was worse.\n- `## Why` gives the reason the chosen option won, concretely enough that a reader could tell\n whether it would still win today. A reason that would equally support any of the\n alternatives supports none.\n- `## Consequences` names what the company is now committed to and what it gave up, and states\n what has to stay true for the call to stay right, because that is what a reader watches for.\n- `decided` is the date the call was made, at the precision the source states, never the date\n it was carried out. A call still proposed carries the date it was put forward, and takes the\n date of the call when its status leaves the proposed state, the file renamed where the year\n moved.\n- `by` names the seat, never the person, as a seat is person-neutral. In a company of one that\n is one seat; in a company of more it is the seat that answered for the call, and a call that\n several seats made names the one that would have had the last word.\n- `upholds` names a value only where it actually turned the call. A value that would be cited\n by any call the company makes tells a reader nothing.\n- `serves` names an objective only where the call was made for it; a call that serves no\n written objective is still a decision, and gains no invented one.\n- `serves` names the objective the decision serves, never the strategy it follows: which route a\n call sits on is read from the strategy that serves the same objective, and a strategy the call\n produced or changed is a `## Bears on` row.\n- Every row of `## Bears on` names an entity the call made, changed or ended. An entity the\n call merely mentions is not borne on.\n- `## Consequences` closes with one dated sentence saying so where a call is dropped and nothing\n replaced it.\n- The page is written in the company's own first person, \"I\" for a company of one, \"we\"\n otherwise, and the same one throughout the instance.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/decisions/*.md`\n\nNothing owns a decision and a decision owns nothing: a call bears on entities of every type and belongs to none of them, as a question does. The filename is not the slug of the H1, which is what R12 does by default. It is the year in `decided`, then a `-`, then a slug naming the call, chosen as an experience's is: `2026-architect-role.md`, `2026-vendored-core.md`. The folder then sorts as a log and reads as one. The year must be the year in `decided`, the rest must be a slug by R12, and the two together must be unique in the folder.", "tables": [] } ], "owner": null, "path": "core/decision-schema.md" }, { "id": "01a0dd34-8da0-7615-9223-70458cc2b8b0", "address": "core/decision-kind", "type": "core", "name": "Decision Kind Schema", "tagline": "Required structure for decision kind files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every decision references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the kind covers" ], [ "`## What it means`", "Yes", "Which calls belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a governance framework, a mandate" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every decision references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the kind covers" ], [ "`## What it means`", "Yes", "Which calls belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A kind answers \"what sort of call is this?\", the question a reader cannot otherwise ask of a folder that holds a hire, a license and a data model side by side. Its value is that the answer is a reference rather than a word: two decisions of one kind mean the same sort of thing, the kinds are visible in the graph as nodes, and a page can draw the calls of one kind together.", "tables": [] }, { "heading": "Writing rules", "text": "- `## What it means` says what the kind excludes as well as what it covers, since the boundary\n with the kind beside it is where every disagreement will be.\n- `## What it means` is about the sort of call, never about how large it was, how it turned out\n or who made it. Those belong to the decision.\n- The H1 names what the calls are, `Architecture`, `Career`, and never the section or the type\n they sit in.", "tables": [] }, { "heading": "File Location", "text": "`model/decision-kinds/*.md`\n\nA kind owns nothing and nothing owns it: many decisions claim the same few, and what each kind means lives here rather than being restated on every call. It sits at the container root beside `experience-kinds/`, because every decision in the instance claims one of the same set.\n\nThe set is the instance's own, as an experience kind's is. Which sorts of call a company distinguishes, an architecture from a hire from a price, is a fact about that company, and a kind arriving later is one file here, not a change to this metamodel and a release of it.", "tables": [] } ], "owner": null, "path": "core/decision-kind-schema.md" }, { "id": "01a0dd34-8da0-7db6-9762-c04c62f55fe0", "address": "core/decision-status", "type": "core", "name": "Decision Status Schema", "tagline": "Required structure for decision status files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every decision references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the state means" ], [ "`## What it means`", "Yes", "When a call is in this state, when it leaves it, and what a reader may rely on while it is" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the status; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a governance framework, a mandate" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every decision references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the state means" ], [ "`## What it means`", "Yes", "When a call is in this state, when it leaves it, and what a reader may rely on while it is" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the status; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A status answers \"is this call made, and does it still hold?\" for someone about to act on it. A decision file is never rewritten to say something else, so the status is the one thing on it that moves, and what each state licenses a reader to do is written once here rather than guessed from a word.", "tables": [] }, { "heading": "Writing rules", "text": "- `## What it means` says what a reader may rely on: a proposed call is not acted on, a\n standing call is, a replaced one is read through the decision that replaced it.\n- `## What it means` says how a call leaves the state, which decision or event moves it on, so\n that a status is never changed by hand without a reason the model can show.\n- `## What it means`, on every status but the one for a call that holds as written, says which\n decision or event moves a call into it. (The half \"an instance has exactly one status for a\n call that holds as written\" is dropped: no single page can break it.)\n- `## What it means` is about whether the call is made and holds, never about how well it went.\n What came of a call is the next decision's question or a period's result.\n- The H1 names the state of the call, `Standing`, `Revised`, and never a verdict on it.", "tables": [] }, { "heading": "File Location", "text": "`model/decision-statuses/*.md`\n\nA status owns nothing and nothing owns it: every decision carries one, and what each state means lives here rather than in a token whose meaning every reader guesses. It sits at the container root beside `decision-kinds/`, because every decision in the instance is in one of the same set of states.\n\nThe set is the instance's own. Which states a company lets a call be in, whether a call can be proposed before it is made, whether a dropped call is told from a replaced one, is a fact about the company, and a state arriving later is one file here, not a change to this metamodel.", "tables": [] } ], "owner": null, "path": "core/decision-status-schema.md" }, { "id": "01a0c233-ae50-7bfb-8010-1e997f829ce3", "address": "core/domain", "type": "core", "name": "Domain Schema", "tagline": "Required structure for domain files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Domain]`", "Yes", "The canonical name of the domain. A concept's or a product's `domain` references this exact string." ], [ "`> [Scope]`", "Yes", "One-paragraph statement of what this domain covers and what it leaves to another" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the area; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a charter, a map of the area" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Domain]`", "Yes", "The canonical name of the domain. A concept's or a product's `domain` references this exact string." ], [ "`> [Scope]`", "Yes", "One-paragraph statement of what this domain covers and what it leaves to another" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the area; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A domain is one area of the company — the words it means something exact by there, and the products it ships there — and it answers \"where does this belong, and who decides what it means?\" for a reader looking a term or a product up and for a writer placing a new one. It holds no definitions and lists nothing: what a domain contains is read from the concepts and products naming it.", "tables": [] }, { "heading": "Writing rules", "text": "- The scope says what the domain covers and names at least one thing it deliberately leaves to another domain, because a boundary stated from one side only is not a boundary.\n- The H1 names the area, not the team that owns it or the system that implements it.\n- The page carries no diagram and no list of the domain's concepts or its products. Each is a second copy of what those files already say.", "tables": [] }, { "heading": "File Location", "text": "`model/domains/*.md`\n\nA domain owns nothing, so it is a file: its concepts and its products name it rather than sit inside it, because a concept one domain owned could not be named by a concept of another.", "tables": [] } ], "owner": null, "path": "core/domain-schema.md" }, { "id": "01a02f41-4da0-7f80-93be-7ae6d0bfc85d", "address": "core/experience", "type": "core", "name": "Experience Schema", "tagline": "Required structure for experience files.", "fields": { "owner": "profile" }, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`start`", "Yes", "date", "When the period began" ], [ "`end`", "No", "date", "Absent means the period is ongoing." ], [ "`kind`", "Yes", "ref → experience-kind", "What sort of period this is — the H1 of a file in `experience-kinds/`" ], [ "`organization`", "No", "ref? → identity", "Where the period was spent. What it names depends on the `kind` — an employer, a client, a host, an awarding body — and each kind says which. It draws an edge when it names the company this instance describes, and stays a fact when it names anyone else." ], [ "`capacity`", "No", "string", "The capacity the subject served in, where the H1 does not already name it: a job title or a part such as speaker or author" ], [ "`url`", "No", "string", "The entry's own address on the web" ], [ "`skills`", "No", "array of ref → skill", "Each entry is the H1 of a file in `skills/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`start`", "Yes", "date", "When the period began" ], [ "`end`", "No", "date", "Absent means the period is ongoing." ], [ "`kind`", "Yes", "ref → experience-kind", "What sort of period this is — the H1 of a file in `experience-kinds/`" ], [ "`organization`", "No", "ref? → identity", "Where the period was spent. What it names depends on the `kind` — an employer, a client, a host, an awarding body — and each kind says which. It draws an edge when it names the company this instance describes, and stays a fact when it names anyone else." ], [ "`capacity`", "No", "string", "The capacity the subject served in, where the H1 does not already name it: a job title or a part such as speaker or author" ], [ "`url`", "No", "string", "The entry's own address on the web" ], [ "`skills`", "No", "array of ref → skill", "Each entry is the H1 of a file in `skills/`" ] ] } }, { "heading": "Sections", "text": "An `end` date with nothing beside it is read anyway: the reader supplies a reason, and usually a worse one than the truth. The section is optional because most periods need none — a talk ends when it has been given — and a required one would manufacture noise, or invent. It is only meaningful where `end` is set; an ongoing period has not ended.\n\nIt is prose rather than a frontmatter field because a reason is a sentence: it wraps, it may carry a colon, and R8 keeps frontmatter for short facts. It is deliberately not an enum either. A closed set of endings — resigned, redundancy, contract end — flattens the one thing that carries the meaning, does not survive the move between employment cultures, and would be the most sensitive field in the model to filter on. What is worth recording here is a sentence someone wrote on purpose, not a token someone selected.", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Title]`", "Yes", "The canonical name of this period" ], [ "`> [Tagline]`", "Yes", "One-paragraph summary of the period" ], [ "`## Achievements`", "No", "Grouped. Bulleted. What was accomplished in this period, under `###` headings that name achievement kinds" ], [ "`## Ending`", "No", "Why the period ended, where a bare `end` date would otherwise be read into. One or two sentences." ], [ "`## References`", "No", "Table. What a reader can check this entry against" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a register entry, a recording, a certificate, a product" ], [ "`URL`", "Yes", "string", "Where it is" ] ] }, { "caption": "`## Achievements` is grouped under these headings:", "columns": [ "Heading", "Required", "Type", "Description" ], "rows": [ [ "`Kind`", "No", "ref → achievement-kind", "The kind every bullet below it is chiefly evidence of" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Title]`", "Yes", "The canonical name of this period" ], [ "`> [Tagline]`", "Yes", "One-paragraph summary of the period" ], [ "`## Achievements`", "No", "Grouped. Bulleted. What was accomplished in this period, under `###` headings that name achievement kinds" ], [ "`## Ending`", "No", "Why the period ended, where a bare `end` date would otherwise be read into. One or two sentences." ], [ "`## References`", "No", "Table. What a reader can check this entry against" ] ] } }, { "heading": "Purpose", "text": "An experience is one dated period in a profile's history, and the place a skill claim gets its evidence. It answers \"what did this person do here, and what does that show?\" — so it is written from the person's side, not the organization's. What the organization is, what a skill means and how strongly the person claims it are all somewhere else; what only this file holds is what happened, when, and what it evidences.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 names the part the subject played, or `capacity` carries it: the field is filled where the\n H1 does not already name the part, and left absent where it does. An entry named for what it\n delivered, or for the event it happened at, does not say who the subject was on it. An entry\n named for a position does, and repeating it in the field would be the same fact twice. Which\n of those an instance writes is the instance's own convention and no rule here fixes it; the\n field is what carries the part when the H1 does not.\n- `capacity` is the part, not the employer and not the client. Who the work was done for is\n `organization`. Who it was done through is not a field at all: it is the period that contains\n this one, and an instance that wants it stated reads it from there.\n- Every entry in `skills:` is one the body shows. A skill listed and not evidenced belongs in\n the profile's table or nowhere; here it is a claim with nothing under it.\n- An `## Achievements` bullet states an outcome, one idea each. \"Responsible for the platform\"\n is a job description; \"held platform cost flat as volume grew to 89M events a year\" is an\n achievement. Where a number, a system or a named result exists, it goes in the bullet.\n- `## Achievements`, where an instance defines achievement kinds, groups them: each bullet sits\n under the heading of the one kind it is chiefly evidence of, headings follow the kinds'\n `rank`, and a kind with nothing in the entry has no heading. An instance that defines none\n writes a flat list.\n- `## Achievements` puts the broadest claim first within a kind; peers follow the order they\n happened in, and a bullet that points back comes directly after what it points to — or names\n it, where the grouping would part them.\n- `## Achievements` holds no list of tools or stack, since that is not an achievement: what was\n built with a tool says so in the bullet that built it.\n- The tagline of a period still running says so, and the period has no `end` — a reader sees a\n tagline and does not see an absent field.\n- The H1 of a one-off — a talk, a certification, an award or a publication — comes with `end`\n set equal to `start`, since a one-off is not a period. Left absent it would read as still\n running, and no other field says otherwise. The two being equal is what makes it a one-off,\n and the interval that shared value denotes is how precisely it is placed: `2012-05-04 ..\n 2012-05-04` is a day, `2016-10 .. 2016-10` a month, `2002 .. 2002` an event known only to its\n year. A period that genuinely ran a whole year is not written `2002 .. 2002` — it takes the\n months it ran, `2002-01 .. 2002-12`, which is also the only way to tell the two apart.\n- `url` is the entry's own address and nothing else — the conference's page, the recording,\n the published case study. A link that lets a reader check a claim the entry makes is not the\n entry's address; it is a reference, and it goes in the table.\n- `What` names the kind of document, not its significance. \"Commercial register entry\" is a\n fact about the link; \"proof that the company existed\" is a reading of it.\n- The H1 of a one-off comes with `organization` naming whoever hosted, awarded or published it,\n where that is someone other than the person; a one-off the person put out themselves, on\n their own site or channel, has none.\n- `## Ending` is written in the person's own voice and looks forward: what the period had\n settled, and what it made the next thing. It is neither an achievement nor a grievance.", "tables": [] }, { "heading": "File Location", "text": "`model/profiles//experiences/*.md`\n\nAn experience is owned by a profile and cannot exist without it, so it nests inside the profile's folder rather than sitting at the root with a `profile:` field pointing back. The filename is not the slug of the H1, which is what R12 does by default. It is the start year, then a `-`, then a slug naming the period — chosen, not derived: the H1 says what happened and makes a long name that neither sorts nor scans, `organization` is optional so a required filename cannot come from it, and one organization covers several periods anyway. Whoever writes the file picks the shortest thing that identifies it — `2018-northwind-atelier.md`, `2019-orbit-conference.md`, `2026-career-break.md` — and the folder then sorts chronologically and reads as a career. The year must be the year in `start`, the rest must be a slug by R12, and the two together must be unique in the folder.", "tables": [] } ], "owner": null, "path": "core/experience-schema.md" }, { "id": "01a06385-9d00-7eef-86a5-d2218d053998", "address": "core/experience-kind", "type": "core", "name": "Experience Kind Schema", "tagline": "Required structure for experience kind files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every experience references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the kind covers" ], [ "`## What it means`", "Yes", "Which periods belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a classification, a standard" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every experience references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the kind covers" ], [ "`## What it means`", "Yes", "Which periods belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A kind answers \"what sort of period is this?\" — the question a reader cannot otherwise ask of a folder that holds a degree, a conference talk and a decade of employment side by side. Its value is that the answer is a reference rather than a word: two experiences of the same kind mean the same thing, the kinds are visible in the graph as nodes, and changing what a kind covers is one edit rather than a scan of every period.", "tables": [] }, { "heading": "Writing rules", "text": "- `## What it means` says what the kind excludes as well as what it covers. The boundary between\n a role and a project, or a project and a community entry, is where every disagreement will be.\n- `## What it means` is about the sort of period, never about how it went, how long it lasted or\n how senior it was. Those belong to the period.\n- The H1 names what the period *is*, not the type it belongs to: `Role`, not `Experience`.\n- `## What it means` says which one `organization` means under this kind — an employer, a\n client, a host, an awarding body — since the field means a different thing under each kind.\n That sentence has nowhere else to live.\n- `## What it means` carries no dates and governs none. How a date on an experience reads is the\n experience's business whatever kind it is, and a kind claiming otherwise would make an absent\n `end` mean two things and resolve it by a label.", "tables": [] }, { "heading": "File Location", "text": "`model/experience-kinds/*.md`\n\nA kind owns nothing and nothing owns it: many experiences claim the same few, and what each kind means lives here rather than being restated on every period. It sits at the container root beside `skills/` rather than inside a profile, because the same kinds are claimed by every profile in the instance.\n\nThe set is deliberately the instance's own. A career acquires categories — a self-directed period, an advisory seat, a board — and a kind arriving later is one file here, not a change to this metamodel and a release of it.", "tables": [] } ], "owner": null, "path": "core/experience-kind-schema.md" }, { "id": "01a0c234-71a0-7313-94b7-15be3be5e2d3", "address": "core/feature", "type": "core", "name": "Feature Schema", "tagline": "Required structure for feature files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`products`", "Yes", "array of ref → product", "The products this feature is assembled into" ], [ "`concepts`", "No", "array of ref → concept", "The concepts this feature operates on" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`products`", "Yes", "array of ref → product", "The products this feature is assembled into" ], [ "`concepts`", "No", "array of ref → concept", "The concepts this feature operates on" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Feature]`", "Yes", "The canonical name of the feature" ], [ "`> [What it gives]`", "Yes", "One-paragraph statement of what someone can do with this that they could not without it" ], [ "`## Description`", "Yes", "What the feature does, and where it stops" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the feature; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — documentation, a demonstration, a place to use it" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Feature]`", "Yes", "The canonical name of the feature" ], [ "`> [What it gives]`", "Yes", "One-paragraph statement of what someone can do with this that they could not without it" ], [ "`## Description`", "Yes", "What the feature does, and where it stops" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the feature; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A feature is one thing a product lets someone do, and it answers \"what is this for, and which products have it?\" for a reader deciding what to build, sell or document. It is the unit product documentation is organized along, so a feature nobody can name the user of is a component and belongs in neither this type nor this folder.", "tables": [] }, { "heading": "Writing rules", "text": "- The tagline says what someone can now do, in their words, and never names a screen, a service or a vendor.\n- `## Description` says where the feature stops as plainly as what it does, because the boundary is what tells two neighboring features apart.\n- The H1 names the capability, not the vendor that supplies it. Where a vendor is what varies, the vendor is a concept the feature names and not a feature of its own.\n- The page says nothing about a release, a ticket or a delivery date: those move, and a feature outlives all three.\n- `What` in `## References` names the kind of thing a row opens, never the surface, product or vendor by name.", "tables": [] }, { "heading": "File Location", "text": "`model/features/*.md`\n\nA feature owns nothing, so it is a file. It is not owned by a product either: a feature is assembled into several, so the edge is written here, on the side that can hold more than one.", "tables": [] } ], "owner": null, "path": "core/feature-schema.md" }, { "id": "01a0f10d-64f0-71c7-8329-86453b047994", "address": "core/identifier", "type": "core", "name": "Identifier Schema", "tagline": "Required structure for the identifier file: what an entity's id looks like in this instance.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`format`", "Yes", "enum", "`uuidv7` or `pattern`. `uuidv7` is a UUID version 7 (RFC 9562), written in lowercase; `pattern` is whatever the `pattern` field matches." ], [ "`pattern`", "No", "string", "A regular expression every id matches in full, from `^` to `$`. Written when `format` is `pattern`, and absent otherwise." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`format`", "Yes", "enum", "`uuidv7` or `pattern`. `uuidv7` is a UUID version 7 (RFC 9562), written in lowercase; `pattern` is whatever the `pattern` field matches." ], [ "`pattern`", "No", "string", "A regular expression every id matches in full, from `^` to `$`. Written when `format` is `pattern`, and absent otherwise." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "What the instance calls its ids" ], [ "`> [Statement]`", "Yes", "One paragraph on what an id here is for, and who holds on to one" ], [ "`## References`", "No", "Table. The specification the format follows; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a specification, a registry" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "What the instance calls its ids" ], [ "`> [Statement]`", "Yes", "One paragraph on what an id here is for, and who holds on to one" ], [ "`## References`", "No", "Table. The specification the format follows; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "The identifier file says what shape the `id` on every page takes, so that a person, an agent or an outside system holding an id knows what it is, and so that the checks can hold every page to that shape. The rules an id obeys are the same in every instance and are R18's, not this page's: it is set once, never changed and never reused.", "tables": [] }, { "heading": "Writing rules", "text": "- A `pattern` matches nothing taken from the entity: not its name, its type, its language or its owner, since each of those can change and the id cannot.\n- The statement names who relies on the id: a tracker, a graph, a link somebody wrote down.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/identifier.md`\n\nAn instance has one way of writing ids, so the type is a file directly in the container rather than a folder (R6, R13), named for the type rather than for the slug of its H1 (R12), which leaves the H1 free to be a name.", "tables": [] } ], "owner": null, "path": "core/identifier-schema.md" }, { "id": "01a04c7b-6b80-73dc-8007-6a193b1138d3", "address": "core/identity", "type": "core", "name": "Identity Schema", "tagline": "Required structure for the identity file — who the company is.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`email`", "No", "string", "Where to reach the company — a role address such as `info@` serves. No commit is judged by it: a person commits under their profile's `email`." ], [ "`location`", "No", "string", "Where the company works from" ], [ "`url`", "No", "string", "The company's own address on the web" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`email`", "No", "string", "Where to reach the company — a role address such as `info@` serves. No commit is judged by it: a person commits under their profile's `email`." ], [ "`location`", "No", "string", "Where the company works from" ], [ "`url`", "No", "string", "The company's own address on the web" ] ] } }, { "heading": "Sections", "text": "A presence is a place the company maintains a page on, named by the place and addressed by that page — never a single post, an article or a recording, which document an experience and belong in that experience's `## References`.", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The company's canonical name" ], [ "`> [Tagline]`", "Yes", "One-paragraph statement of what the company is" ], [ "`## What it is`", "Yes", "What the company does, and for whom" ], [ "`## Also at`", "No", "Table. One row per presence the company maintains elsewhere; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the company; its columns are declared below." ] ] }, { "caption": "`## Also at` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Where`", "Yes", "string", "The place, in plain words — GitHub, LinkedIn" ], [ "`URL`", "Yes", "string", "The company's own page there" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a register entry, articles of association" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The company's canonical name" ], [ "`> [Tagline]`", "Yes", "One-paragraph statement of what the company is" ], [ "`## What it is`", "Yes", "What the company does, and for whom" ], [ "`## Also at`", "No", "Table. One row per presence the company maintains elsewhere; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the company; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "Identity is the company itself: the entity every other file in the instance is about. It answers \"whose model is this?\" — which nothing else does, because a repository folder's name is a path, and R2 and R3 exist to keep a canonical name out of a path. Without it an instance describes a company it never names. A fact lives in one place: where identity and a profile would state the same thing, an address, identity holds it and the profile carries its own only where it differs, and a mail address is two facts, the company's here and a person's own on their profile.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 is the company's name as the company writes it, not a description of it. A company of\n one may name a person, and then a profile of the same person carries the same name — that is\n expected, not a collision to resolve: the types are different, and a reference carries the\n type it resolves under (R4), so the shared name sends no reader to the wrong page.\n- The tagline says what the company is, not what it aspires to. Where it is going is the\n vision's business.\n- `## What it is` says what the company does and for whom, in the company's own voice. It is\n not a history and not a pitch; an achievement belongs to a profile's experience.\n- One row per place in `## Also at`, and a place the company no longer maintains has no row:\n the table is what a reader will follow.\n- `URL` in `## Also at` is the page that is the company's own on that place, not a search, a\n feed or a post. What a reader lands on has to be the company.", "tables": [] }, { "heading": "File Location", "text": "`model/identity.md`\n\nA company has one identity, so the type is a file directly in the container rather than a folder (R6, R13). The filesystem carries the cardinality: there is nowhere to put a second one. The file is named for the type, not for the slug of its H1 (R12), which leaves the H1 free to be the company's name.\n\nThe file is the graph's root as well as its subject: every other file in the instance is about the company it names, and none has to say so. A page names the identity only where the company is itself the fact, as an experience does when the period was spent there.", "tables": [] } ], "owner": null, "path": "core/identity-schema.md" }, { "id": "01a0d896-7c40-707d-92ca-c0568838830a", "address": "core/kpi", "type": "core", "name": "KPI Schema", "tagline": "Required structure for KPI files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`owner`", "Yes", "ref → seat", "The seat accountable for improving it, the H1 of a file in `seats/`" ], [ "`measures`", "No", "ref → process", "The process whose performance it measures, the H1 of a process file. Absent where it measures none." ], [ "`assesses`", "No", "array of ref → control", "The controls whose effectiveness this KPI's number tells, each the H1 of a file in `controls/`. Absent where it assesses none." ], [ "`serves`", "No", "array of ref → strategic-objective", "The objectives it indicates progress toward, the H1 of a file in `strategic-objectives/`" ], [ "`unit`", "Yes", "string", "What one value is counted in, with its period where it has one: `hours`, `deployments per week`, `percent of deployments`" ], [ "`direction`", "Yes", "enum", "`lower`, `higher` or `target`. Which way is better: down, up, or toward a band, where too high and too low are both worse." ], [ "`read-with`", "No", "array of ref → kpi", "The KPIs it is read beside, because each can be moved alone at the other's cost — the H1 of a file in `kpis/`" ], [ "`can-cost`", "No", "array of ref → value", "The values that pushing this number can wear down, each the H1 of a file in `values/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`owner`", "Yes", "ref → seat", "The seat accountable for improving it, the H1 of a file in `seats/`" ], [ "`measures`", "No", "ref → process", "The process whose performance it measures, the H1 of a process file. Absent where it measures none." ], [ "`assesses`", "No", "array of ref → control", "The controls whose effectiveness this KPI's number tells, each the H1 of a file in `controls/`. Absent where it assesses none." ], [ "`serves`", "No", "array of ref → strategic-objective", "The objectives it indicates progress toward, the H1 of a file in `strategic-objectives/`" ], [ "`unit`", "Yes", "string", "What one value is counted in, with its period where it has one: `hours`, `deployments per week`, `percent of deployments`" ], [ "`direction`", "Yes", "enum", "`lower`, `higher` or `target`. Which way is better: down, up, or toward a band, where too high and too low are both worse." ], [ "`read-with`", "No", "array of ref → kpi", "The KPIs it is read beside, because each can be moved alone at the other's cost — the H1 of a file in `kpis/`" ], [ "`can-cost`", "No", "array of ref → value", "The values that pushing this number can wear down, each the H1 of a file in `values/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [KPI]`", "Yes", "The canonical name of the quantity. Everything references the KPI by this exact string." ], [ "`> [Definition]`", "Yes", "One sentence of what it measures" ], [ "`## How it is measured`", "Yes", "The calculation, what counts as the event it counts, the window it is taken over, and where the data comes from" ], [ "`## What it can hide`", "Yes", "How it can move while what it stands for does not, and what reading it beside `read-with` catches" ], [ "`## References`", "No", "Table. Where the definition comes from, and where its targets and values are kept; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a standard's definition, a dashboard, a sheet of targets" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [KPI]`", "Yes", "The canonical name of the quantity. Everything references the KPI by this exact string." ], [ "`> [Definition]`", "Yes", "One sentence of what it measures" ], [ "`## How it is measured`", "Yes", "The calculation, what counts as the event it counts, the window it is taken over, and where the data comes from" ], [ "`## What it can hide`", "Yes", "How it can move while what it stands for does not, and what reading it beside `read-with` catches" ], [ "`## References`", "No", "Table. Where the definition comes from, and where its targets and values are kept; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A KPI is a quantity the company has chosen to watch, defined once so that everyone who reads the number means the same thing by it. It answers \"what exactly does this number count, who answers for it, and what could make it lie?\" for someone reading a value, setting a target or deciding whether to trust either. It is not the value and not the target, which move and are kept where the References row points, and it is not a strategy's `## What would show it is working`, which says what to watch for one route; a KPI is watched whichever route is taken.", "tables": [] }, { "heading": "Writing rules", "text": "- The page holds no target, threshold, baseline or measured value, ever. Each moves, and a\n number that moves goes stale in the model without a sound; a References row says where they\n are kept.\n- The H1 names the quantity, not the dashboard or tool that shows it: `Change Lead Time`, not\n `the lead-time chart`.\n- The page is person-neutral, as a seat is: the definition names seats and never who holds them.\n- `## How it is measured` says what counts as the event in this company's terms — what a\n deployment is here, what a failure is — concretely enough that two people counting would get\n the same number. A definition that leaves the event open lets every reader count a different\n thing under one name.\n- `## What it can hide` names a specific way the number improves while the work does not. \"It\n can be misread\" hides nothing a reader can check.\n- `read-with` names a KPI that moves against this one when this one is gamed, never the KPI\n itself and not every KPI of the same process.\n- `can-cost` names a value only where `## What it can hide` says how pushing the number wears\n it down. The field is the edge; the section is the reason, and a name with no reason under it\n is a claim nothing backs.\n- `can-cost` names no value any KPI could cost, since such a value tells a reader nothing.\n- `direction: target` is written only where both too high and too low are worse; an indicator\n that is better lower down to some floor is `lower`.\n- `unit` names the period wherever the value is a rate: `deployments per week`, not `count`.\n- `serves` names an objective only where the KPI moving would actually tell whether that\n objective holds. A KPI that indicates no objective has none, and is still a KPI the company\n watches.\n- `assesses` names a control only where the number moving would tell how well that control works; a KPI that merely shares a subject with a control names none.\n- `## What it can hide`, on a KPI that assesses a control, says what the control lets through\n that the number does not count.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/kpis/*.md`\n\nOne file per key performance indicator. Nothing owns a KPI and a KPI owns nothing, as with `strategic-objective`: it may name the process it measures, and many measure none.", "tables": [] } ], "owner": null, "path": "core/kpi-schema.md" }, { "id": "01a0f254-34f0-709f-b36c-1c67dcc7ae30", "address": "core/localization", "type": "core", "name": "Localization Schema", "tagline": "Required structure for the localization file: the one language an instance is written in.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`locale`", "Yes", "string", "The language the model is written in, as a BCP 47 language tag: `en-US`, `de-CH`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`locale`", "Yes", "string", "The language the model is written in, as a BCP 47 language tag: `en-US`, `de-CH`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "What the instance calls its language" ], [ "`> [Statement]`", "Yes", "One paragraph on who reads the model in that language" ], [ "`## References`", "No", "Table. The standard the tag follows; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a standard, a registry" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "What the instance calls its language" ], [ "`> [Statement]`", "Yes", "One paragraph on who reads the model in that language" ], [ "`## References`", "No", "Table. The standard the tag follows; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "The localization file says which language the model is written in, so that a reader, an agent or a check knows the language every page's names and prose are in, and which language an answer grounded in the model is grounded in. A model is written in one language and is never translated inside itself; a reader in another language reads a rendering of it.", "tables": [] }, { "heading": "Writing rules", "text": "- `locale` is one language tag. Which tags exist is the registry's, and the check holds only the shape.\n- The statement names who reads the model in that language: the owner, a customer, an agent answering in it.\n- The page writes names and prose in the language `locale` names (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/localization.md`\n\nAn instance is written in one language, so the type is a file directly in the container rather than a folder (R6, R13), named for the type rather than for the slug of its H1 (R12), which leaves the H1 free to be a name.", "tables": [] } ], "owner": null, "path": "core/localization-schema.md" }, { "id": "01a0a8b4-7978-7d24-aac9-850b3c9a4d9c", "address": "core/phase", "type": "core", "name": "Phase Schema", "tagline": "Required structure for phase files.", "fields": { "owner": "process" }, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`owner`", "Yes", "ref → seat", "The seat accountable for the phase's outcome, the H1 of a file in `seats/`. Distinct from the **Owner:** line above, which names the type that owns a phase; this field names the seat." ], [ "`executed-by`", "Yes", "array of ref → seat", "The seats that do the phase's work" ], [ "`supported-by`", "No", "array of ref → seat", "The seats consulted in the phase, producing nothing it is graded on" ], [ "`gate-approvers`", "Yes", "array of ref → seat", "The seats that approve passage out of the phase. At least one; a phase nobody approves is an activity inside another phase." ], [ "`escalation-authority`", "Yes", "ref → seat", "The seat that decides when the gate's criteria cannot be met" ], [ "`gate-to`", "No", "ref → phase", "The phase this gate leads to. Absent on the last phase, and only there." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`owner`", "Yes", "ref → seat", "The seat accountable for the phase's outcome, the H1 of a file in `seats/`. Distinct from the **Owner:** line above, which names the type that owns a phase; this field names the seat." ], [ "`executed-by`", "Yes", "array of ref → seat", "The seats that do the phase's work" ], [ "`supported-by`", "No", "array of ref → seat", "The seats consulted in the phase, producing nothing it is graded on" ], [ "`gate-approvers`", "Yes", "array of ref → seat", "The seats that approve passage out of the phase. At least one; a phase nobody approves is an activity inside another phase." ], [ "`escalation-authority`", "Yes", "ref → seat", "The seat that decides when the gate's criteria cannot be met" ], [ "`gate-to`", "No", "ref → phase", "The phase this gate leads to. Absent on the last phase, and only there." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Phase]`", "Yes", "The canonical name of the phase. The owning process's `## Phases` table and the previous phase's `gate-to` reference it by this exact string." ], [ "`> [Goal]`", "Yes", "One-paragraph statement of what the phase is for" ], [ "`## What it takes`", "Yes", "What enters the phase, and what it refuses to start without" ], [ "`## Activities`", "Yes", "Grouped. Numbered. What is done, in the order it is done; where the work differs by track, one `### [Track]` heading per track, each with its own list" ], [ "`## What it produces`", "Yes", "Table. What leaves the phase; its columns are declared below." ], [ "`## What it never does`", "Yes", "Bulleted. One sentence each, of what the phase refuses" ], [ "`## Gate`", "Yes", "Bulleted. The criteria that must be satisfied to leave the phase, one item each" ], [ "`## If not met`", "Yes", "Table. What the escalation authority may decide when the gate's criteria cannot be met, one row each, and where the work goes; its columns are declared below. A paragraph under the table may say what the rows cannot." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the phase; its columns are declared below." ] ] }, { "caption": "`## Activities` is grouped under these headings:", "columns": [ "Heading", "Required", "Type", "Description" ], "rows": [ [ "`Track`", "No", "ref → track", "The track the numbered list below it is the work of, by its canonical name: the H1 of a file in the owning process's `tracks/`" ] ] }, { "caption": "`## What it produces` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Deliverable`", "Yes", "string", "The thing that leaves the phase" ], [ "`Description`", "Yes", "string", "What it is, and what makes it finished" ] ] }, { "caption": "`## If not met` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Outcome`", "Yes", "string", "What the escalation authority may decide, in a few words: `reworked`, `dropped`" ], [ "`Leads to`", "No", "ref → phase", "The phase the work goes to: this one, or one before it in the owning process's `## Phases`. Empty where the process stops." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a rulebook, a checklist" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Phase]`", "Yes", "The canonical name of the phase. The owning process's `## Phases` table and the previous phase's `gate-to` reference it by this exact string." ], [ "`> [Goal]`", "Yes", "One-paragraph statement of what the phase is for" ], [ "`## What it takes`", "Yes", "What enters the phase, and what it refuses to start without" ], [ "`## Activities`", "Yes", "Grouped. Numbered. What is done, in the order it is done; where the work differs by track, one `### [Track]` heading per track, each with its own list" ], [ "`## What it produces`", "Yes", "Table. What leaves the phase; its columns are declared below." ], [ "`## What it never does`", "Yes", "Bulleted. One sentence each, of what the phase refuses" ], [ "`## Gate`", "Yes", "Bulleted. The criteria that must be satisfied to leave the phase, one item each" ], [ "`## If not met`", "Yes", "Table. What the escalation authority may decide when the gate's criteria cannot be met, one row each, and where the work goes; its columns are declared below. A paragraph under the table may say what the rows cannot." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the phase; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A phase is one step of a process and the gate at its end — what enters, what is done, what leaves, and what must be true for it to leave. It answers \"am I done, and who says so?\" for whoever is in it. The gate is the part the model enforces: the document a phase produces scales with the size of the change and may be a conversation rather than a file, and the approval at its end does not scale at all.", "tables": [] }, { "heading": "Writing rules", "text": "- Each `## Gate` criterion is a sentence that can fail: \"the checks pass on the branch\" can,\n \"quality is good\" cannot.\n- `executed-by` names the seats that do the work, never the seat that approves it; a seat that\n only signs belongs in `gate-approvers`.\n- `Outcome` is what the escalation authority decides, in a word or a few, as a past participle\n where it can be: `reworked`, `narrowed`, `dropped`. It is not the gate criterion that failed.\n- An empty `Leads to` stops the process. A hand-off to another process is a stop in this table,\n and the paragraph under it names the process the work goes to.\n- `## If not met` carries a paragraph under the table only for what the rows cannot say, a\n reason or a hand-off, and a page whose rows say everything carries none.\n- `## Activities` treats its `### [Track]` headings as strands of one step and never as\n alternative routes through it, since tracks run together in one pass rather than instead of\n one another, and a phase may produce a deliverable per track in the same pass.", "tables": [] }, { "heading": "File Location", "text": "`model/processes//phases/*.md`\n\nA phase is owned by a process and cannot exist without it, so it nests inside the process's folder rather than sitting at the root with a `process:` field pointing back. The filename is R12's default, the slug of the H1. It carries no position prefix: the order is the owning process's `## Phases` table and the `gate-to` chain, and a third copy on the filename would have to be renamed through the whole folder whenever a phase was inserted.", "tables": [] } ], "owner": null, "path": "core/phase-schema.md" }, { "id": "01a0a8b4-7978-7026-a388-b10e041b45b5", "address": "core/process", "type": "core", "name": "Process Schema", "tagline": "Required structure for process files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`owner`", "Yes", "ref → seat", "The seat accountable for the process as a whole, the H1 of a file in `seats/`" ], [ "`supported-by`", "No", "array of ref → seat", "The seats that keep the process working without being accountable for it" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`owner`", "Yes", "ref → seat", "The seat accountable for the process as a whole, the H1 of a file in `seats/`" ], [ "`supported-by`", "No", "array of ref → seat", "The seats that keep the process working without being accountable for it" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Process]`", "Yes", "The canonical name of the process. Phases and readers reference it by this exact string." ], [ "`> [Purpose]`", "Yes", "One-paragraph statement of what the process is for" ], [ "`## Tracks`", "Yes", "Table. The kinds of thing this process makes, one row each; its columns are declared below." ], [ "`## Phases`", "Yes", "Table. The phases of the process, one row each, in the order the work passes through them; its columns are declared below." ], [ "`## What it never does`", "Yes", "Bulleted. One sentence each, of what the process refuses in every phase" ], [ "`## References`", "No", "Table. The rulebooks the process is run by; its columns are declared below." ] ] }, { "caption": "`## Tracks` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Track`", "Yes", "ref → track", "The track, by its canonical name: the H1 of a file in this process's `tracks/`" ] ] }, { "caption": "`## Phases` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Phase`", "Yes", "ref → phase", "The phase, by its canonical name: the H1 of a file in this process's `phases/`" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a rulebook, a checklist, a mandate" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Process]`", "Yes", "The canonical name of the process. Phases and readers reference it by this exact string." ], [ "`> [Purpose]`", "Yes", "One-paragraph statement of what the process is for" ], [ "`## Tracks`", "Yes", "Table. The kinds of thing this process makes, one row each; its columns are declared below." ], [ "`## Phases`", "Yes", "Table. The phases of the process, one row each, in the order the work passes through them; its columns are declared below." ], [ "`## What it never does`", "Yes", "Bulleted. One sentence each, of what the process refuses in every phase" ], [ "`## References`", "No", "Table. The rulebooks the process is run by; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A process is the path work takes through the company's seats — one folder, the phases in the order they are passed through, and the gate between each pair — and it answers \"what happens next, who does it, and what has to be true before it moves on?\" for someone doing the work or waiting on it. It is not a seat, which says what one seat takes and produces whenever it acts, and it is not a record of work that happened, which is an experience.", "tables": [] }, { "heading": "Writing rules", "text": "- The page is person-neutral, as a seat is: a process names seats and never who holds them.\n- The H1 names the work rather than the tool that carries it: `Delivery`, not `The board`.\n- Each line under `## What it never does` is a sentence an agent can hold a change against.\n \"Never merges without the Owner\" can fail; \"works carefully\" cannot.\n- `## Phases` names a phase by its canonical name and nothing beside it (R3). A path to the\n phase's file is not written there: a path moves, nothing resolves one, and whatever shows the\n model to a reader can make the name a link.\n- `## Tracks` names each track by its canonical name and nothing beside it (R3). What a track\n produces is said once, in the track's own file, and is not repeated here. (The half \"lists\n every track in the folder and nothing else\" is dropped: the instance check that an owner lists\n every track it owns holds it, R5.)", "tables": [] }, { "heading": "File Location", "text": "`model/processes//.md`\n\nA process owns its phases and its tracks and cannot be read without them, so it is a folder rather than a file, as a profile is. The folder is named for the process and holds its own file under that same name, plus the `phases/` and `tracks/` collections the phases and tracks nest in.", "tables": [] } ], "owner": null, "path": "core/process-schema.md" }, { "id": "01a10522-0ee2-785a-915f-8e9b1cd7f5c8", "address": "core/processing-activity", "type": "core", "name": "Processing Activity Schema", "tagline": "Required structure for processing activity files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`legal-basis`", "Yes", "enum", "`consent`, `contract`, `legal-obligation`, `vital-interests`, `public-task` or `legitimate-interests`. The ground the processing rests on (GDPR Art. 6(1))." ], [ "`retention`", "No", "string", "How long the company keeps the data, or the criterion that decides it" ], [ "`surfaces`", "No", "array of ref → surface", "Where a person whose data it is meets the activity, each the H1 of a file in `surfaces/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`legal-basis`", "Yes", "enum", "`consent`, `contract`, `legal-obligation`, `vital-interests`, `public-task` or `legitimate-interests`. The ground the processing rests on (GDPR Art. 6(1))." ], [ "`retention`", "No", "string", "How long the company keeps the data, or the criterion that decides it" ], [ "`surfaces`", "No", "array of ref → surface", "Where a person whose data it is meets the activity, each the H1 of a file in `surfaces/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Processing activity]`", "Yes", "The activity's name. Everything references the activity by this exact string." ], [ "`> [Purpose]`", "Yes", "The purpose of the processing, in one sentence" ], [ "`## Data subjects`", "Yes", "Bulleted. Whose personal data it is, one category of people per item" ], [ "`## Personal data`", "Yes", "Bulleted. Which personal data it processes, one category per item" ], [ "`## Processors`", "No", "Table. The processors the data goes to and what each receives; its columns are declared below. An activity the company does in-house has no rows." ], [ "`## References`", "No", "Table. The record of processing it belongs to, an impact assessment, the privacy page that discloses it; its columns are declared below." ] ] }, { "caption": "`## Processors` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Processor`", "Yes", "ref → data-processor", "The processor the data goes to, the H1 of a file in `data-processors/`" ], [ "`Receives`", "Yes", "string", "What that processor gets, which may be less than the activity holds" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document, a record of processing, an impact assessment, a privacy notice" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Processing activity]`", "Yes", "The activity's name. Everything references the activity by this exact string." ], [ "`> [Purpose]`", "Yes", "The purpose of the processing, in one sentence" ], [ "`## Data subjects`", "Yes", "Bulleted. Whose personal data it is, one category of people per item" ], [ "`## Personal data`", "Yes", "Bulleted. Which personal data it processes, one category per item" ], [ "`## Processors`", "No", "Table. The processors the data goes to and what each receives; its columns are declared below. An activity the company does in-house has no rows." ], [ "`## References`", "No", "Table. The record of processing it belongs to, an impact assessment, the privacy page that discloses it; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A processing activity is one thing the company does with personal data, for one purpose (GDPR Art. 30(1); DSG Art. 12, «Bearbeitungstätigkeit»). It answers \"what do we do with whose data, on what ground, for how long, and who else gets it?\", which is what a record of processing keeps and what a privacy page discloses. The processors it names keep their own facts on their own pages: where they process, under which contract, for how long.", "tables": [] }, { "heading": "Writing rules", "text": "- The tagline states one purpose, as the person whose data it is would understand it.\n- The page is one activity for one ground: processing that rests on two grounds in `legal-basis` is written as two activities.\n- Each item of `## Data subjects` names a category of people, never a person.\n- Each item of `## Personal data` names a category of data, not a field of a database, and says so where it is a special category (GDPR Art. 9; DSG Art. 5 lit. c).\n- Each row of `## Processors` says in `Receives` what reaches that processor and nothing more, so a processor that sees part of the data is never listed as seeing all of it.\n- `retention` states the company's own period or the criterion that decides it; a processor's own period is on the processor's page.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/processing-activities/*.md`\n\nNothing owns a processing activity and a processing activity owns nothing: it names the processors it uses and the surfaces where a person meets it, and belongs to none of them.", "tables": [] } ], "owner": null, "path": "core/processing-activity-schema.md" }, { "id": "01a0c231-9ef8-7add-8875-3ed58850ec6e", "address": "core/product", "type": "core", "name": "Product Schema", "tagline": "Required structure for product files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`domain`", "Yes", "ref → domain", "The area of the company this product belongs to — the H1 of a file in `domains/`" ], [ "`kind`", "Yes", "ref → product-kind", "What sort of thing this product is, the H1 of a file in `product-kinds/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`domain`", "Yes", "ref → domain", "The area of the company this product belongs to — the H1 of a file in `domains/`" ], [ "`kind`", "Yes", "ref → product-kind", "What sort of thing this product is, the H1 of a file in `product-kinds/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Product]`", "Yes", "The canonical name of the product. A feature's `products` references this exact string." ], [ "`> [What it is]`", "Yes", "One-paragraph statement of what the product is and who opens it" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the product; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — documentation, a release page" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Product]`", "Yes", "The canonical name of the product. A feature's `products` references this exact string." ], [ "`> [What it is]`", "Yes", "One-paragraph statement of what the product is and who opens it" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the product; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A product is something the company ships that somebody uses on its own, and it answers \"what does this company actually put in front of people?\" for a reader who has met its values, its strategy and its processes and still cannot name its output. It is not the market it serves, the project that built it or the revenue it earns.", "tables": [] }, { "heading": "Writing rules", "text": "- The tagline names what the product is and who opens it, in that order, and claims nothing about how well it does either.\n- The H1 names the product as the people who use it name it, not as its repository or its internal project is named.\n- `domain` names the one domain whose concepts the product's users came to it for. A product that works across two still names one, and the concepts its features name show the rest.\n- The page says nothing about a release, a version or a roadmap: a product outlives all three.\n- `kind` is the one a reader looking for this product would look under first; a product that\n seems to need two is two products, or sits where most readers would look for it.", "tables": [] }, { "heading": "File Location", "text": "`model/products/*.md`\n\nA product owns nothing, so it is a file. Nothing owns a product either, and it lists no features: a feature names the products it is assembled into, and the edge is written once, on the side that can hold several. A product names the domain it belongs to, as a concept does, and sits in the container rather than inside that domain for the same reason.", "tables": [] } ], "owner": null, "path": "core/product-schema.md" }, { "id": "01a12186-4ca9-72e8-9e81-17ee888e32f6", "address": "core/product-kind", "type": "core", "name": "Product Kind Schema", "tagline": "Required structure for product kind files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "The kind's position wherever products are drawn grouped. Spaced in tens so a kind can be added without renumbering the others." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "The kind's position wherever products are drawn grouped. Spaced in tens so a kind can be added without renumbering the others." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every product references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what sort of thing the products of this kind are" ], [ "`## What it means`", "Yes", "Who opens a product of this kind, which products belong to it, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a classification, a standard" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every product references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what sort of thing the products of this kind are" ], [ "`## What it means`", "Yes", "Who opens a product of this kind, which products belong to it, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A kind answers \"what sort of thing does this company ship?\", the question a reader cannot otherwise ask of a folder that holds a box of pralines, an online shop and the systems behind a store side by side. Its value is that the answer is a reference rather than a word: two products of one kind are the same sort of thing, a surface can draw the products of one kind together, and the chat can say what the company ships from the model rather than from its own reading. A kind holds at least one product; a kind no product names is vocabulary nobody uses, and leaves, once the instance holds a product.", "tables": [] }, { "heading": "Writing rules", "text": "- `## What it means` says who opens a product of this kind, a customer, a franchisee, the\n company's own staff, since that is the one sentence that tells a channel from the systems\n behind it, and it has nowhere else to live.\n- `## What it means` says what the kind excludes as well as what it covers. The boundary\n between a channel and the thing sold through it, or between what IT provides and what the\n business sells, is where every disagreement will be.\n- `## What it means` is about the sort of thing, never about how well a product of it does,\n how many there are or what they earn. Those belong to the product, or to nothing in the\n model.\n- The H1 names what a product of this kind is, `Channel`, `IT product`, and never the type,\n `Product`, a market or a business unit.\n- The page writes names and prose in the model's language (R14), as every page does.", "tables": [] }, { "heading": "File Location", "text": "`model/product-kinds/*.md`\n\nA kind owns nothing and nothing owns it: every product claims one of the same few, and what each kind covers lives here rather than being restated on every product. It sits at the container root beside `products/`, as `question-kinds/` sits beside `questions/`.\n\nThe set is the instance's own, as a question kind's is. What a company ships, chocolate, the channels it sells through, what its IT provides to its staff, is a fact about that company, and a kind arriving later is one file here, not a change to this metamodel and a release of it.", "tables": [] } ], "owner": null, "path": "core/product-kind-schema.md" }, { "id": "01a02f8b-db90-7d28-8506-23282bf3a383", "address": "core/proficiency-level", "type": "core", "name": "Proficiency Level Schema", "tagline": "Required structure for proficiency level files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "Position on the ladder. Spaced in tens so a rung can be added without renumbering the others." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "Position on the ladder. Spaced in tens so a rung can be added without renumbering the others." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every assessment references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the level claims" ], [ "`## What it means`", "Yes", "What someone at this level can actually do" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the level; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a competency framework, a standard" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every assessment references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the level claims" ], [ "`## What it means`", "Yes", "What someone at this level can actually do" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the level; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A proficiency level is one rung of the single ladder every claim in the instance is made against. It answers \"what does this word mean when someone claims a skill at it?\" — for the person making the claim, and for the person weighing it. Its whole value is that the definition sits in one file: two assessments at the same rung mean the same thing, and changing what a rung means is one edit rather than a hundred.", "tables": [] }, { "heading": "Writing rules", "text": "- `## What it means` describes what someone at this level does with *it* — the thing being\n claimed — and never what that thing is. Every rung is claimed against every skill, so anything\n specific to one skill does not belong on a rung.\n- `## What it means` names what this rung has that the rung below does not. Working\n unsupervised, choosing between alternatives, knowing where the thing breaks down: each rung\n earns its place by a difference someone could observe, or the ladder has fewer rungs than it\n claims.\n- The page cites and reproduces no external scale — SFIA, Dreyfus, a set of HR bands — for the\n same reason a skill cites none: the ladder is the instance's own, in its own words.\n- `## What it means` is about capability, never about seniority, tenure or job title. Those are\n the organization's business and they move for reasons that have nothing to do with the claim.", "tables": [] }, { "heading": "File Location", "text": "`model/proficiency-levels/*.md`\n\nA level owns nothing and nothing owns it: many profiles claim the same few, and the definition of each lives here rather than being restated on every assessment. Changing what a level means is then one edit, in one file.", "tables": [] } ], "owner": null, "path": "core/proficiency-level-schema.md" }, { "id": "01a02f3d-4e30-7b02-9ed7-cc37d8a2aa93", "address": "core/profile", "type": "core", "name": "Profile Schema", "tagline": "Required structure for profile files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`nature`", "Yes", "enum", "`human` or `agent`. What holds this profile: a person, or an agent that runs under rulebooks and stands for whichever model runs it." ], [ "`seats`", "No", "array of ref → seat", "The seats this profile holds, each the H1 of a file in `seats/`. Absent for a profile without a seat." ], [ "`email`", "No", "string", "Contact address. On a profile whose `nature` is `human`, also the address the person's own commits are authored under: a commit from it is that person's, whatever seats the profile holds, and passes without trailers." ], [ "`location`", "No", "string", "Where the person works from" ], [ "`image`", "No", "image", "The person's picture, a file in this profile's folder — square, 512×512 recommended, 256–1024 pixels on a side, at most 300 KB" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`nature`", "Yes", "enum", "`human` or `agent`. What holds this profile: a person, or an agent that runs under rulebooks and stands for whichever model runs it." ], [ "`seats`", "No", "array of ref → seat", "The seats this profile holds, each the H1 of a file in `seats/`. Absent for a profile without a seat." ], [ "`email`", "No", "string", "Contact address. On a profile whose `nature` is `human`, also the address the person's own commits are authored under: a commit from it is that person's, whatever seats the profile holds, and passes without trailers." ], [ "`location`", "No", "string", "Where the person works from" ], [ "`image`", "No", "image", "The person's picture, a file in this profile's folder — square, 512×512 recommended, 256–1024 pixels on a side, at most 300 KB" ] ] } }, { "heading": "Sections", "text": "An assessment is a table row rather than a frontmatter field because it is a claim with prose attached, not a short fact, and the evidence under it is a table for the reason stated below. A table renders where a reader looks, has no quoting hazard around a colon or a wrapped line, and declares its columns here exactly as a frontmatter field does.\n\n\n\nEvidence is a table of its own rather than a third column of `## Skills` because a claim rests on more than one thing and a cell holds one line. A paragraph listing four engagements cannot be counted, and breadth is one of the things a level is read from: a capability shown in three engagements has held where the people, the constraints and the stakes changed, which one engagement cannot show however well it went. One fact per row is what makes that breadth readable by anyone, including a machine.\n\n`Experience` is the optional column and sits last. It is optional because a claim at the lower rungs can rest on having been near work rather than on having owned a period of it, and such a row leaves the cell blank rather than inventing a period to fill it. Where the cell is filled, the experience's period is read from the experience and is not written into the sentence as well: a date copied beside a fact the experience already owns is a second copy that nothing keeps true. A period shorter than the experience's is different. The years a practice ran inside a longer role are not a copy of the role's dates but a fact of their own, and the sentence is the only place that holds them, so they stay.\n\nThe column is `What it shows` rather than `Evidence` so that it does not restate the section it sits in, which is the same reason `## References` calls its first column `What`.\n\n\n\nA presence is a place the person maintains a page on, named by the place and addressed by that page — never a single post, an article or a recording, which document an experience and belong in that experience's `## References`.", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The person's canonical name. Everything references the profile by this exact string." ], [ "`> [Tagline]`", "Yes", "One-paragraph summary of the person: what they do, or the claim their work makes" ], [ "`## Skills`", "No", "Table. One row per skill claimed; its columns are declared below." ], [ "`## Evidence`", "No", "Table. Under `## Skills`. One row per fact a claim rests on; its columns are declared below." ], [ "`## Summary`", "No", "A paragraph of context" ], [ "`## Also at`", "No", "Table. One row per presence the person maintains elsewhere; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the person; its columns are declared below." ] ] }, { "caption": "`## Skills` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Skill`", "Yes", "ref → skill", "Must match the H1 of a file in `skills/` exactly" ], [ "`Level`", "Yes", "qualifier → proficiency-level", "Must match the H1 of a file in `proficiency-levels/` exactly" ] ] }, { "caption": "`## Evidence` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Skill`", "Yes", "ref → skill", "The claim this row stands under — the H1 of a file in `skills/`" ], [ "`What it shows`", "Yes", "string", "One sentence naming the thing done, concrete enough that a reader could check it" ], [ "`Experience`", "No", "qualifier → experience", "`skills` lists `Skill`. The period the fact comes from — the H1 of a file in this profile's `experiences/`" ] ] }, { "caption": "`## Also at` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Where`", "Yes", "string", "The place, in plain words — GitHub, LinkedIn, Substack" ], [ "`URL`", "Yes", "string", "The person's own page there" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a register entry, a publication" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The person's canonical name. Everything references the profile by this exact string." ], [ "`> [Tagline]`", "Yes", "One-paragraph summary of the person: what they do, or the claim their work makes" ], [ "`## Skills`", "No", "Table. One row per skill claimed; its columns are declared below." ], [ "`## Evidence`", "No", "Table. Under `## Skills`. One row per fact a claim rests on; its columns are declared below." ], [ "`## Summary`", "No", "A paragraph of context" ], [ "`## Also at`", "No", "Table. One row per presence the person maintains elsewhere; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the person; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A profile is the one page that says who a person or an agent is and what they claim — the entity every experience is owned by, every skill claim is made from and every seat is held by. It answers \"who is this, what can they do, and what is that judgment resting on?\" for someone deciding whether to work with them. It is not a curriculum vitae: what happened, when and where lives in the experiences the profile owns, and what a capability *is* lives in the skill. What only the profile can hold is the claim — this person, this skill, at this level, on this evidence. A person who holds a seat claims the skills the seat requires in their Skills table, with evidence, and where they cannot the gap stays visible as a finding the validation pass reports, never an error and never an invented row, while an agent claims nothing, so a seat it holds reports no gap.", "tables": [] }, { "heading": "Writing rules", "text": "- The tagline and `## Summary` are the person's own, in their own voice: what they do and what\n runs through it. Not their employer's description of the role, and not a job advertisement.\n- The tagline may state the claim the person's work makes rather than describe the work. Then\n the claim is one the model holds elsewhere — a value, or the thread the summary names — and a\n reader can follow it there. A line with nothing behind it is a slogan, and nothing on the page\n tells one from the other except what backs it.\n- A `What it shows` cell states a fact that can be checked — a system, an organization, a\n number, a named outcome. \"Extensive experience\" and \"deep knowledge\" are not evidence.\n- `What it shows` never restates the level. If removing the Level column would lose nothing, the\n row is describing confidence rather than the work.\n- `What it shows` says more than its own row's `Experience` cell; a row that says no more says\n nothing, and is dropped rather than written.\n- `What it shows` is one sentence, under forty words. The sentence does not repeat the period of\n the experience its `Experience` column names; a period of the fact's own, shorter than that\n one, stays in it.\n- `## Evidence` rows run in the order the Skills table lists the skills, and chronologically\n within a skill.\n- One row per place in `## Also at`, and a place the person no longer maintains has no row:\n the table is what a reader will follow.\n- `URL` in `## Also at` is the page that is the person's own on that place, not a search, a feed\n or a post. What a reader lands on has to be the person.\n- `image` is the person, recognizably, as the tagline is their own voice: not a logo, a team or\n an illustration standing in for them. A profile whose nature is `agent` may carry one, and\n then it shows what holds the profile; the rule below that an agent claims no skill does not\n reach it.\n- `nature` says what holds the profile, never how well. A profile whose nature is `agent`\n claims no skill and carries neither a Skills table nor an Evidence table: a claim is a\n person's history with a capability, evidenced by work that stays true after the next\n release, and an agent has no such history. What holds an agent to a seat is the rulebook it\n runs under, never a row it wrote about itself.", "tables": [] }, { "heading": "File Location", "text": "`model/profiles//.md`\n\nA profile owns experiences, so it is a folder rather than a file: `profiles//` holds the profile's own file and an `experiences/` folder beside it. Removing a person is then one operation and an orphaned experience is unrepresentable.", "tables": [] } ], "owner": null, "path": "core/profile-schema.md" }, { "id": "01a0d1c8-57f8-7233-ac27-d1160347d7a8", "address": "core/question", "type": "core", "name": "Question Schema", "tagline": "Required structure for question files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`kind`", "Yes", "ref → question-kind", "What the question is about, the H1 of a file in `question-kinds/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`kind`", "Yes", "ref → question-kind", "What the question is about, the H1 of a file in `question-kinds/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Question]`", "Yes", "The question as a visitor asks it, ending in a question mark. Every reference to it uses this exact string." ], [ "`> [Answer]`", "Yes", "One or two sentences that say where the answer lies and state no fact the model holds elsewhere" ], [ "`## Rests on`", "No", "Table. One row per entity the answer comes from; its columns are declared below. Absent when the answer is mastered here." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the question; its columns are declared below." ] ] }, { "caption": "`## Rests on` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Type`", "Yes", "string", "The type of the entity this row names, as its schema is named: `profile`, `strategic-objective`" ], [ "`Entity`", "Yes", "ref → by Type in Owner", "The entity the answer comes from, by its canonical name" ], [ "`Owner`", "No", "string", "Where `Type` is an owned type, the entity that owns this one, by its canonical name; blank otherwise" ], [ "`For`", "No", "string", "The part of the answer this entity carries, where the answer rests on more than one" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a post that answers it at length, a standard" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Question]`", "Yes", "The question as a visitor asks it, ending in a question mark. Every reference to it uses this exact string." ], [ "`> [Answer]`", "Yes", "One or two sentences that say where the answer lies and state no fact the model holds elsewhere" ], [ "`## Rests on`", "No", "Table. One row per entity the answer comes from; its columns are declared below. Absent when the answer is mastered here." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the question; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A question answers \"where in the model is the answer to what people actually ask?\" It is the bridge from a visitor's words to the company's. The facts stay where they are mastered, and the question names them, so a fact changed on its own page is changed for every question that rests on it and no answer goes stale. What no other entity holds, a stance, a boundary, a claim the model deliberately does not make, is mastered on the question itself.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 is worded as people ask, not as the model names things: \"Can Robert still write code himself?\", not \"Software engineering proficiency\". A question worded in the model's own vocabulary adds nothing the words search did not already find.\n- The answer routes. It may say what kind of thing the answer is and where it lies, and it may say what the model does not claim; it states no count, version, date or fact that another entity holds, because that would be a second copy nothing keeps true.\n- The answer, where there is no `## Rests on`, is mastered on the question. It states only what no other entity holds: a stance, a boundary, or a claim the model deliberately does not make. A fact that belongs on an entity is written on that entity, and the question rests on it.\n- The answer draws on no entity without a row in `## Rests on`, and no row names an entity the answer does not draw on.\n- The page writes names and prose in American English (R14). A visitor asking in German is matched by the chat, not by a German question.\n- `kind` is the one a visitor would look under first. A question that seems to need two is either two questions or is filed where most visitors would look for it.\n\nThe answer is required, because a question with no answer is an open issue and not an entity: what the model is asked and cannot answer yet is a change to the model, written as one, and the question follows it. `## Rests on` is optional, because some honest answers rest on nothing else in the model. What that costs is that no check can tell a question resting on nothing on purpose from one whose rows were forgotten; the writing rules and the owner's review of each question carry that, as they carry the rest of what an answer may say.", "tables": [] }, { "heading": "File Location", "text": "`model/questions/*.md`", "tables": [] } ], "owner": null, "path": "core/question-schema.md" }, { "id": "01a0ddf7-ed40-7c28-9b18-65b95ea6de95", "address": "core/question-kind", "type": "core", "name": "Question Kind Schema", "tagline": "Required structure for question kind files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "The kind's position wherever questions are drawn grouped. Spaced in tens so a kind can be added without renumbering the others." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "The kind's position wherever questions are drawn grouped. Spaced in tens so a kind can be added without renumbering the others." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every question references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the questions of this kind are about" ], [ "`## What it means`", "Yes", "Which questions belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a classification, a standard" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every question references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the questions of this kind are about" ], [ "`## What it means`", "Yes", "Which questions belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A kind answers \"what is this question about?\", the question a visitor asks of a list too long to read, when what they want is the part of it that concerns them. Its value is that the answer is a reference rather than a word: the kinds are nodes in the graph, a surface can draw the questions of one kind together or one from each, and the chat can say what the model answers about from the model rather than from its own reading. A kind holds at least two questions, unless the instance holds only one, and a question alone is filed under the nearest kind until a second arrives.", "tables": [] }, { "heading": "Writing rules", "text": "- `## What it means` says what the kind excludes, since the boundary with the kind beside it is\n where every disagreement will be. (The reader-agreement half is dropped; this is its checkable\n sibling.)\n- `## What it means` is about what the visitor has in mind when they ask, never about which\n entity the answer rests on.\n- The H1 names the kind as a visitor would read it above the questions it holds, `Career`,\n `Brand`, and never the type or the section the answers sit in.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/question-kinds/*.md`\n\nA kind owns nothing and nothing owns it: every question claims one of the same few, and what each kind covers lives here rather than being restated on every question. It sits at the container root beside `questions/`, because every question in the instance claims one of the same set.\n\nThe set is the instance's own, as an achievement kind's is. What a company's visitors ask about, a career, a product's fit, a hotel's matching and privacy, is a fact about that company, and a kind arriving later is one file here, not a change to this metamodel and a release of it.", "tables": [] } ], "owner": null, "path": "core/question-kind-schema.md" }, { "id": "01a0fb19-9552-78c5-9105-3fa9c4659b23", "address": "core/risk", "type": "core", "name": "Risk Schema", "tagline": "Required structure for risk files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`owner`", "Yes", "ref → seat", "The seat accountable for the risk, the H1 of a file in `seats/`" ], [ "`threatens`", "No", "array of ref → strategic-objective", "The objectives it would affect, each the H1 of a file in `strategic-objectives/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`owner`", "Yes", "ref → seat", "The seat accountable for the risk, the H1 of a file in `seats/`" ], [ "`threatens`", "No", "array of ref → strategic-objective", "The objectives it would affect, each the H1 of a file in `strategic-objectives/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Risk]`", "Yes", "The risk's name, stated as the event. Everything references the risk by this exact string." ], [ "`> [What could happen]`", "Yes", "What could happen, in one sentence" ], [ "`## Cause`", "Yes", "What would bring it about (ISO 31000: risk source)" ], [ "`## Consequence`", "Yes", "What it would do to the company's objectives (ISO 31000: consequence)" ], [ "`## References`", "No", "Table. The register or tracker that keeps its current rating and its history; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document, a risk register, a tracker" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Risk]`", "Yes", "The risk's name, stated as the event. Everything references the risk by this exact string." ], [ "`> [What could happen]`", "Yes", "What could happen, in one sentence" ], [ "`## Cause`", "Yes", "What would bring it about (ISO 31000: risk source)" ], [ "`## Consequence`", "Yes", "What it would do to the company's objectives (ISO 31000: consequence)" ], [ "`## References`", "No", "Table. The register or tracker that keeps its current rating and its history; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A risk is what could go wrong: an event that would affect the company's objectives, from a cause, with a consequence (ISO 31000's risk source, event and consequence; BMM's risk as a potential impact of loss). It answers \"what are we guarding against, and who answers for it?\" A downside only: an opportunity is what an objective or a strategy already pursues. The controls that mitigate it and the rules it motivates name it; it names none of them.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 is written as an event, not as a feeling or a gap: \"a secret reaches a transcript\", not \"security\".\n- The page carries no likelihood, impact or score. Those are assessments that move, and the model holds how things are made and not their state (R17), as a KPI holds its definition and none of its values. Where the company rates its risks, `## References` points at where it does.\n- `owner` names the seat, never the person, as a seat is person-neutral.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/risks/*.md`\n\nNothing owns a risk and a risk owns nothing: what could go wrong reaches across the company, and its owner is a seat it names, not a folder it sits in.", "tables": [] } ], "owner": null, "path": "core/risk-schema.md" }, { "id": "01a0fb19-951b-79e6-aaf4-dfd05c5bdc60", "address": "core/rule", "type": "core", "name": "Rule Schema", "tagline": "Required structure for rule files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`modality`", "Yes", "enum", "`must`, `must not` or `may`. What the statement does: obliges, forbids or permits (SBVR's obligation, prohibition and restricted permission)." ], [ "`protects`", "No", "array of ref → value", "The values the rule keeps from being broken, each the H1 of a file in `values/`" ], [ "`serves`", "No", "array of ref → strategic-objective", "The objectives the rule serves, each the H1 of a file in `strategic-objectives/` (BMM: a directive supports a goal)" ], [ "`motivated-by`", "No", "array of ref → risk", "The risks that are the reason for it, each the H1 of a file in `risks/` (BMM: a directive is motivated by a potential impact)" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`modality`", "Yes", "enum", "`must`, `must not` or `may`. What the statement does: obliges, forbids or permits (SBVR's obligation, prohibition and restricted permission)." ], [ "`protects`", "No", "array of ref → value", "The values the rule keeps from being broken, each the H1 of a file in `values/`" ], [ "`serves`", "No", "array of ref → strategic-objective", "The objectives the rule serves, each the H1 of a file in `strategic-objectives/` (BMM: a directive supports a goal)" ], [ "`motivated-by`", "No", "array of ref → risk", "The risks that are the reason for it, each the H1 of a file in `risks/` (BMM: a directive is motivated by a potential impact)" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Rule]`", "Yes", "The rule's name. Everything references the rule by this exact string." ], [ "`> [Statement]`", "Yes", "The rule itself, written so that it can be kept or broken" ], [ "`## Why`", "Yes", "The reason for the rule, in a paragraph" ], [ "`## Applies to`", "No", "Table. The seats the rule binds and the processes and phases it applies in; its columns are declared below. A rule with no rows applies everywhere." ], [ "`## References`", "No", "Table. The law, standard or document it complies with, or where it came from; its columns are declared below." ] ] }, { "caption": "`## Applies to` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Type`", "Yes", "string", "The type of the entity this row names, as its schema is named: `seat`, `process` or `phase`" ], [ "`Entity`", "Yes", "ref → by Type in Owner", "The seat, process or phase, by its canonical name" ], [ "`Owner`", "No", "string", "For a phase, the process that owns it, by its canonical name; blank otherwise" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document, a law, a standard, a policy" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Rule]`", "Yes", "The rule's name. Everything references the rule by this exact string." ], [ "`> [Statement]`", "Yes", "The rule itself, written so that it can be kept or broken" ], [ "`## Why`", "Yes", "The reason for the rule, in a paragraph" ], [ "`## Applies to`", "No", "Table. The seats the rule binds and the processes and phases it applies in; its columns are declared below. A rule with no rows applies everywhere." ], [ "`## References`", "No", "Table. The law, standard or document it complies with, or where it came from; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A rule is a statement under the company's own authority that obliges, forbids or permits something (SBVR; BMM's directive). It answers \"what must, must not or may happen here, and why?\" for a person or an agent about to act. It is for what reaches across: a refusal only one seat, one process or one phase makes stays in that page's `## What it never does`. Whether a machine or a person holds a change to the rule is read from the controls that enforce it, which name the rule; the rule names none of them. A rule binds more than one seat, process or phase, or is what a control checks, and a refusal only one of them makes stays in that page's `## What it never does`. A rule with no `## Applies to` rows applies everywhere and so binds them all.", "tables": [] }, { "heading": "Writing rules", "text": "- The statement says one thing, as the people it binds would say it, and could be kept or broken. A statement nobody could tell was kept or broken is advice and is not written (SBVR: no business rule is an advice).\n- `motivated-by` names a risk only where the rule exists because of it.\n- An `## Applies to` row names a seat, a process or a phase; the grammar reads any type in the Type column, so this is the agent pass's to hold.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/rules/*.md`\n\nNothing owns a rule and a rule owns nothing: a rule reaches across the seats, processes and phases it binds and belongs to none of them.", "tables": [] } ], "owner": null, "path": "core/rule-schema.md" }, { "id": "01a0a6a7-53f8-7824-b858-32860e752f35", "address": "core/seat", "type": "core", "name": "Seat Schema", "tagline": "Required structure for seat files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`requires`", "No", "array of ref → skill", "The skills the seat needs, each the H1 of a file in `skills/`. Absent while nobody has said what the seat needs." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`requires`", "No", "array of ref → skill", "The skills the seat needs, each the H1 of a file in `skills/`. Absent while nobody has said what the seat needs." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Seat]`", "Yes", "The canonical name of the seat. Profiles reference the seat by this exact string." ], [ "`> [Purpose]`", "Yes", "One-paragraph statement of what the seat is for" ], [ "`## What it takes`", "Yes", "What the holder is handed, and what the seat refuses to start without" ], [ "`## What it produces`", "Yes", "What leaves the seat, and in what form" ], [ "`## What it never does`", "Yes", "Bulleted. One sentence each, of what the seat refuses whoever holds it" ], [ "`## References`", "No", "Table. The documents the seat works by — a rulebook, a mandate; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a rulebook, a glossary, a mandate" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Seat]`", "Yes", "The canonical name of the seat. Profiles reference the seat by this exact string." ], [ "`> [Purpose]`", "Yes", "One-paragraph statement of what the seat is for" ], [ "`## What it takes`", "Yes", "What the holder is handed, and what the seat refuses to start without" ], [ "`## What it produces`", "Yes", "What leaves the seat, and in what form" ], [ "`## What it never does`", "Yes", "Bulleted. One sentence each, of what the seat refuses whoever holds it" ], [ "`## References`", "No", "Table. The documents the seat works by — a rulebook, a mandate; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A seat is a responsibility the company needs filled — one file, named once, held by whichever profile lists it. It answers \"what does this seat take, produce and refuse, and what must whoever holds it be able to do?\" for someone filling it, holding it or handing work to it. It is not a person's history in the seat, which lives on the profile and in its experiences, and it is not a process, which says when the seat acts.", "tables": [] }, { "heading": "Writing rules", "text": "- The page is person-neutral: no name, employer, date or number from any profile, and never who\n holds the seat. Who holds it is the profile's fact.\n- The H1 names the seat, so a second holder would still be called that: `Owner`, not\n `Entrepreneur`; `Reviewer`, not the reviewer's name.\n- Each line under `## What it never does` is a sentence an agent can hold an output against.\n \"Never merges\" can fail; \"acts responsibly\" cannot.\n- `requires` lists what the seat needs, not what its current holder happens to have.", "tables": [] }, { "heading": "File Location", "text": "`model/seats/*.md`\n\nA seat owns nothing and nothing owns it, so it is a file. A profile holds one by listing it, and the seat never names its holder; what a seat names is the skills it requires.", "tables": [] } ], "owner": null, "path": "core/seat-schema.md" }, { "id": "01a02f31-3488-773e-a919-f51e729f2ba4", "address": "core/skill", "type": "core", "name": "Skill Schema", "tagline": "Required structure for skill files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`group`", "No", "string", "Free-text grouping, e.g. `Testing`. Whether a group becomes an entity of its own is deliberately open." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`group`", "No", "string", "Free-text grouping, e.g. `Testing`. Whether a group becomes an entity of its own is deliberately open." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Skill]`", "Yes", "The canonical name. Profiles, experiences and seats reference this exact string." ], [ "`> [Definition]`", "Yes", "One-paragraph definition of what the skill is" ], [ "`## In practice`", "No", "What someone using this skill actually does" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the skill; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a framework, a standard" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Skill]`", "Yes", "The canonical name. Profiles, experiences and seats reference this exact string." ], [ "`> [Definition]`", "Yes", "One-paragraph definition of what the skill is" ], [ "`## In practice`", "No", "What someone using this skill actually does" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the skill; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A skill is a capability a person can claim, an experience can evidence and a seat can require — one file, named once, referenced by every profile that claims it. It answers \"what is this, and what does doing it look like?\" for a reader who may claim it, assess it or hire for it. It is not any one person's history with the capability: that lives in the profile's Skills table as a level, in the Evidence table under it and in the experiences that list the skill.", "tables": [] }, { "heading": "Writing rules", "text": "- The definition starts with the thing itself, never with a wrapper — not \"The practice of\",\n \"The discipline of\", \"The ability to\".\n- `## In practice` is person-neutral: no name, employer, date or number from any profile. A\n second profile must be able to claim the skill without a word changing.\n- `## In practice` is written in the imperative without a subject — \"Assess …\", \"Translate …\",\n \"Engage …\" — never \"Someone doing this …\" or \"They …\".\n- The page names products and tools only in a closing clause of the form `Typical tools: …`, and\n only where a product is what the skill is done with. A product is not a skill.\n- The page cites and reproduces none of the public vocabularies (SFIA, ESCO, O*NET, Lightcast),\n which may be consulted to find the grain and to check for gaps. The vocabulary is the\n instance's own.", "tables": [] }, { "heading": "File Location", "text": "`model/skills/*.md`\n\nA skill owns nothing, so it is a file. Nothing owns a skill either: a profile claims one and a seat requires one, and it outlives both.", "tables": [] } ], "owner": null, "path": "core/skill-schema.md" }, { "id": "01a03a36-9dc8-749f-a36f-4d922c5d16a8", "address": "core/source", "type": "core", "name": "Source Schema", "tagline": "Required structure for source files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`url`", "No", "string", "Where the source lives, for a person or a sync to open" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`url`", "No", "string", "Where the source lives, for a person or a sync to open" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The canonical name. Everything references the source by this exact string." ], [ "`> [Description]`", "No", "One-paragraph description of what the source holds" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the source; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — its documentation, an export's format" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The canonical name. Everything references the source by this exact string." ], [ "`> [Description]`", "No", "One-paragraph description of what the source holds" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the source; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A source is the answer to \"if this page is wrong, where does it get fixed?\" Every other core type names one, so no page is of unknown origin, and naming it by canonical name means a system's name and address are written once rather than on every page that came from it. A source is where a fact is *mastered* — the place with the authority to change it — not merely where it was seen.", "tables": [] }, { "heading": "Writing rules", "text": "- The description says what the source holds and whether anything syncs from it. A reader\n deciding where to make a correction needs both halves, and the second one is what says\n whether an edit here would survive.\n- The description says what a `source-id` is in the source, where the source issues identifiers\n — a record key, a directory id, an entry's `id` in a named folder. Without that sentence a\n `source-id` is an opaque string that only its author can resolve.\n- The page sets `url` where the source has an address a person or a sync could open, and leaves\n it absent where it has none. A repository with no remote has none, and the empty field says\n so.\n- The description names the place with authority over the fact, not the place the fact was read.\n If correcting a page means editing somewhere else first, that somewhere else is the source.", "tables": [] }, { "heading": "File Location", "text": "`model/sources/*.md`\n\nA source is where a page's facts come from: the repository itself, or a system the company already runs that a sync writes from. One file per source, so a page can name where it was mastered by canonical name rather than restating a system's name and address on every entry. Nothing owns a source and a source owns nothing. Every other core type carries a required `source` field naming one, so no page is of unknown origin, and an optional `source-id` — the page's identifier inside that source — so a sync can find it again.", "tables": [] } ], "owner": null, "path": "core/source-schema.md" }, { "id": "01a10522-0f1d-7d35-be0a-34aacbf7ad04", "address": "core/stored-item", "type": "core", "name": "Stored Item Schema", "tagline": "Required structure for stored item files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`mechanism`", "Yes", "enum", "`local-storage`, `session-storage`, `cookie`, `indexeddb` or `cache`. How the browser keeps it: the two Web Storage areas, an HTTP cookie, an IndexedDB database or the Cache API (WHATWG HTML, Storage Standard)." ], [ "`necessity`", "Yes", "enum", "`strictly-necessary` or `optional`. Whether the service the visitor asked for needs it (ePrivacy Directive Art. 5(3)). What follows from it differs by jurisdiction and is the law's, which the instance's rules cite." ], [ "`duration`", "No", "string", "How long it stays, where the mechanism does not decide it" ], [ "`surfaces`", "Yes", "array of ref → surface", "The surfaces that set it, each the H1 of a file in `surfaces/`" ], [ "`set-by`", "No", "ref? → data-processor", "The party that sets or reads it, where that is not the company. A name that resolves is a processor; one that does not stays a name." ], [ "`activity`", "No", "ref → processing-activity", "The activity it serves, where what it holds is personal data, the H1 of a file in `processing-activities/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`mechanism`", "Yes", "enum", "`local-storage`, `session-storage`, `cookie`, `indexeddb` or `cache`. How the browser keeps it: the two Web Storage areas, an HTTP cookie, an IndexedDB database or the Cache API (WHATWG HTML, Storage Standard)." ], [ "`necessity`", "Yes", "enum", "`strictly-necessary` or `optional`. Whether the service the visitor asked for needs it (ePrivacy Directive Art. 5(3)). What follows from it differs by jurisdiction and is the law's, which the instance's rules cite." ], [ "`duration`", "No", "string", "How long it stays, where the mechanism does not decide it" ], [ "`surfaces`", "Yes", "array of ref → surface", "The surfaces that set it, each the H1 of a file in `surfaces/`" ], [ "`set-by`", "No", "ref? → data-processor", "The party that sets or reads it, where that is not the company. A name that resolves is a processor; one that does not stays a name." ], [ "`activity`", "No", "ref → processing-activity", "The activity it serves, where what it holds is personal data, the H1 of a file in `processing-activities/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Key]`", "Yes", "The key or cookie name exactly as the code writes it. Everything references the item by this exact string." ], [ "`> [What it holds]`", "Yes", "What the item holds and why, in one sentence" ], [ "`## References`", "No", "Table. The code that sets it, the provider's documentation; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document, a source file, a provider's documentation" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Key]`", "Yes", "The key or cookie name exactly as the code writes it. Everything references the item by this exact string." ], [ "`> [What it holds]`", "Yes", "What the item holds and why, in one sentence" ], [ "`## References`", "No", "Table. The code that sets it, the provider's documentation; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A stored item is one thing a surface keeps on a visitor's device under one name: a Web Storage key, a cookie, an IndexedDB database or a cache (ePrivacy Directive Art. 5(3); FMG Art. 45c). It answers \"what does this page leave in the browser, for how long, and who reads it?\", which is what a privacy page or a cookie policy discloses. Its H1 is the key, so what the code writes and what the model holds can be compared by name.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 is the key as the code writes it, character for character.\n- The tagline says what the item holds and why, in the words a privacy page would use.\n- The page leaves `duration` out for `session-storage`, which ends with the tab, and states it for any other mechanism, as the code sets it or as \"until the visitor clears it\".\n- `necessity` is `strictly-necessary` only where the service the visitor asked for fails without the item.\n- The page leaves `set-by` out for an item the company's own code sets.\n- The page sets `activity` only where what the item holds is personal data.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/stored-items/*.md`\n\nNothing owns a stored item and a stored item owns nothing: one key is set by several surfaces of an instance, and it names each of them.", "tables": [] } ], "owner": null, "path": "core/stored-item-schema.md" }, { "id": "01a0a48a-b970-7f8e-b95f-0769904c5a94", "address": "core/strategic-objective", "type": "core", "name": "Strategic Objective Schema", "tagline": "Required structure for strategic objective files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`adopted`", "Yes", "date", "When this objective began directing the work" ], [ "`horizon`", "No", "date", "By when it should hold. Absent where the objective is a standing one." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`adopted`", "Yes", "date", "When this objective began directing the work" ], [ "`horizon`", "No", "date", "By when it should hold. Absent where the objective is a standing one." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Objective]`", "Yes", "The canonical name, the objective stated as a phrase. Everything references the objective by this exact string." ], [ "`> [Statement]`", "Yes", "One-paragraph statement of what must become true" ], [ "`## What it makes true`", "Yes", "What is concretely different when it holds, and what falls outside it" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the objective; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a plan, a board paper" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Objective]`", "Yes", "The canonical name, the objective stated as a phrase. Everything references the objective by this exact string." ], [ "`> [Statement]`", "Yes", "One-paragraph statement of what must become true" ], [ "`## What it makes true`", "Yes", "What is concretely different when it holds, and what falls outside it" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the objective; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A strategic objective is what must become true for the vision to be reached — the layer between a direction that holds still and the strategies that change under it. It answers \"what are we trying to make true, that we are not sure of yet?\" for someone weighing whether a piece of work is worth doing at all. A `horizon` that passes with the objective unmet is a decision and not a fact: the objective is restated, re-dated or deleted, and leaving it to age is none of those.", "tables": [] }, { "heading": "Writing rules", "text": "- The statement says what must become true, never by what means. A means is a strategy, and an\n objective that names one has already chosen a route the model cannot then see being chosen.\n- The statement names something the company could fail at. An objective no outcome could\n contradict is the vision restated in longer words.\n- `## What it makes true` is concrete enough that a reader could tell whether it holds today,\n and it states what falls outside it, because an objective silent on its boundary is read as\n covering everything.\n- The page sets `horizon` only where a real date exists. A standing objective leaves it absent\n rather than inventing one, and an invented horizon is a claim like any other.\n- The page is written in the company's own first person — \"I\" for a company of one, \"we\"\n otherwise — and the same one throughout the instance.", "tables": [] }, { "heading": "File Location", "text": "`model/strategic-objectives/*.md`\n\nOne file per objective. Nothing owns an objective and an objective owns nothing, as with `value` — and a strategy cites the objective it serves by name, which a heading in a shared document could not offer.", "tables": [] } ], "owner": null, "path": "core/strategic-objective-schema.md" }, { "id": "01a0a48b-9818-7d5d-a7eb-46aee2dfe2a7", "address": "core/strategy", "type": "core", "name": "Strategy Schema", "tagline": "Required structure for strategy files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`adopted`", "Yes", "date", "When this strategy began deciding things" ], [ "`serves`", "Yes", "array of ref → strategic-objective", "The objectives this strategy pursues — the H1 of a file in `strategic-objectives/`" ], [ "`upholds`", "No", "array of ref → value", "The values that constrain the route chosen — the H1 of a file in `values/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`adopted`", "Yes", "date", "When this strategy began deciding things" ], [ "`serves`", "Yes", "array of ref → strategic-objective", "The objectives this strategy pursues — the H1 of a file in `strategic-objectives/`" ], [ "`upholds`", "No", "array of ref → value", "The values that constrain the route chosen — the H1 of a file in `values/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Topic] Strategy`", "Yes", "The canonical name, ending in \"Strategy\". Everything references the strategy by this exact string." ], [ "`> [Statement]`", "Yes", "One-paragraph statement of the approach" ], [ "`## The approach`", "Yes", "How, concretely enough that someone could follow it" ], [ "`## What it rules out`", "Yes", "The options this choice forecloses" ], [ "`## What would show it is working`", "Yes", "What is observable, early enough to change course" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the strategy; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a plan, a board paper" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Topic] Strategy`", "Yes", "The canonical name, ending in \"Strategy\". Everything references the strategy by this exact string." ], [ "`> [Statement]`", "Yes", "One-paragraph statement of the approach" ], [ "`## The approach`", "Yes", "How, concretely enough that someone could follow it" ], [ "`## What it rules out`", "Yes", "The options this choice forecloses" ], [ "`## What would show it is working`", "Yes", "What is observable, early enough to change course" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the strategy; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A strategy is how an objective gets reached — one route among routes that could all have been taken, written so that the choice is visible as a choice. It answers \"why this way and not the other way?\" for someone who arrives after the decision and would otherwise re-open it.", "tables": [] }, { "heading": "Writing rules", "text": "- The statement is a choice a reasonable company could have made differently. If no company\n would choose the opposite, it describes the work rather than choosing a route.\n- `## The approach` names what is actually done, in the terms the route actually turns on:\n tools where it turns on tools, timing where it turns on timing, what is automated and what\n deliberately is not. A strategy that could be pursued by any means at all has chosen nothing.\n- `## What it rules out` names specific foreclosed options, not their absence. \"We do not do bad\n work\" rules nothing out; an option a reader can imagine the company taking does.\n- `## What would show it is working` states something observable while there is still time to\n change course. A measure that only arrives at the horizon is a verdict rather than an\n instrument, and the objective is where a verdict belongs.\n- The statement says how, never where. A strategy restating the vision has skipped the objective\n that was supposed to sit between them.\n- `upholds` names the values that actually constrained the route, where any did. A citation that\n would be equally true of any strategy the company might have chosen instead tells a reader\n nothing.\n- The page is written in the company's own first person — \"I\" for a company of one, \"we\"\n otherwise — and the same one throughout the instance.", "tables": [] }, { "heading": "File Location", "text": "`model/strategies/*.md`\n\nOne file per strategy. Nothing owns a strategy and a strategy owns nothing, as with `strategic-objective`.", "tables": [] } ], "owner": null, "path": "core/strategy-schema.md" }, { "id": "01a08666-4360-7bac-8ac9-4b7c234e01fc", "address": "core/surface", "type": "core", "name": "Surface Schema", "tagline": "Required structure for surface files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a record key, an entry id. Absent when the source has none, as a repository does not." ], [ "`production`", "Yes", "enum", "`built` or `written`. `built` means a script writes the surface and holds its rules; `written` means a person or an agent writes it from this file." ], [ "`built-by`", "No", "string", "The repository whose build writes the surface. Present exactly when `production` is `built`." ], [ "`url`", "No", "string", "Where the surface is published. Absent where it has no address, as a document does not." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a record key, an entry id. Absent when the source has none, as a repository does not." ], [ "`production`", "Yes", "enum", "`built` or `written`. `built` means a script writes the surface and holds its rules; `written` means a person or an agent writes it from this file." ], [ "`built-by`", "No", "string", "The repository whose build writes the surface. Present exactly when `production` is `built`." ], [ "`url`", "No", "string", "Where the surface is published. Absent where it has no address, as a document does not." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Surface]`", "Yes", "The canonical name. Everything references the surface by this exact string." ], [ "`> [Description]`", "Yes", "One-paragraph description of what this surface is and who reaches it" ], [ "`## What it shows`", "Yes", "Bulleted. One item per unit the surface presents, naming the unit and what fills it" ], [ "`## Projection rules`", "No", "Bulleted. How the model becomes this surface: what is carried, what is left out and why. Required for a `written` surface, absent for a `built` one." ], [ "`## Constraints`", "No", "Bulleted. What the published result must satisfy, each written so a reader can pass or fail it" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the surface; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a platform's published limits, a style guide" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Surface]`", "Yes", "The canonical name. Everything references the surface by this exact string." ], [ "`> [Description]`", "Yes", "One-paragraph description of what this surface is and who reaches it" ], [ "`## What it shows`", "Yes", "Bulleted. One item per unit the surface presents, naming the unit and what fills it" ], [ "`## Projection rules`", "No", "Bulleted. How the model becomes this surface: what is carried, what is left out and why. Required for a `written` surface, absent for a `built` one." ], [ "`## Constraints`", "No", "Bulleted. What the published result must satisfy, each written so a reader can pass or fail it" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the surface; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A surface is a place the company publishes from the model. For a written surface, this file is what somebody needs in order to write it: which of the model's facts reach it, in what shape and what the result has to satisfy. For a built surface, it is what somebody needs in order to know the place exists, what it presents and which repository holds its rules. Either way it answers \"if I had to rebuild this from the model today, what would I have to know, and where would I find it?\" — for a person, and for an agent. It is not a record of what the surface currently shows, which is R17's business and belongs in a validation report.", "tables": [] }, { "heading": "Writing rules", "text": "- `production` says who holds the rules. A `written` surface carries `## Projection rules`,\n because nothing re-runs a person. A `built` surface carries none and names the repository in\n `built-by`, because the script is the projection and a second copy of a rule is what this\n model exists to end.\n- The H1 names the page, never the place that carries it. The place is what a profile's or an\n identity's `## Also at` lists, and a surface named for it would turn that table's `Where`\n column from data into references.\n- A line of `## What it shows` names a unit the surface itself has, in the words the surface\n uses for it, and then what fills it. A reader has to be able to find that unit by that name\n while looking at the surface. It names the unit as the place a rule lands, never what that\n unit currently holds — not a count, not a sample, not its present wording.\n- Each line of `## Projection rules` states what the surface does with the model, not what the\n model contains. A rule that could be read off an entity is a fact restated, and the entity is\n where it lives.\n- Each line of `## Constraints` is written as a check: something a reader looking at the\n published result can pass or fail. \"Every unit that can appear alone pairs the name with a\n role or a domain\" can be failed; \"the tone is professional\" cannot.\n- `## Constraints` names the number and where it was read wherever the surface imposes a limit.\n A limit quoted from memory is a claim like any other.\n- The page never states what the surface currently shows. That is an observation, true on the\n day it was written and unfalsifiable here afterwards (R17).", "tables": [] }, { "heading": "File Location", "text": "`model/surfaces/*.md`\n\nA surface is a place the company publishes from the model. A place is published when anyone can reach it without asking; a bundle handed to whoever requests it is not a surface. One file per surface, so every place the model reaches is named in the model, and a reader who finds no file for a place can take that as meaning the model does not reach it. Nothing owns a surface and a surface owns nothing.", "tables": [] } ], "owner": null, "path": "core/surface-schema.md" }, { "id": "01a0bfb0-acf0-79e1-bc25-474cf0bd7ac0", "address": "core/track", "type": "core", "name": "Track Schema", "tagline": "Required structure for track files.", "fields": { "owner": "process" }, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Track]`", "Yes", "The canonical name of the track. The owning process's `## Tracks` table and a phase's `### [Track]` headings reference it by this exact string." ], [ "`> [Produces]`", "Yes", "One-paragraph statement of what one pass down this track leaves behind" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the track; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a rulebook, a checklist" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Track]`", "Yes", "The canonical name of the track. The owning process's `## Tracks` table and a phase's `### [Track]` headings reference it by this exact string." ], [ "`> [Produces]`", "Yes", "One-paragraph statement of what one pass down this track leaves behind" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the track; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A track is one kind of thing a process makes, and it answers “which of the things this process makes is this step about?” for a reader of a phase whose work differs by what is being made. It is an entity so that the answer is a reference rather than a word: a phase that heads its activities with a track names something that exists, a track renamed is renamed in one place with every mention held to it, and the tracks are visible in the graph as nodes. It points at nothing. Which seats work a track and what they do on it are said by the phases.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 names what the track makes, not who makes it: `Code`, not `Engineering`.\n- The tagline says what is left behind when a change has run down the track, as a thing a\n reader could point at: “a merged change to the platform”, not “development work”.\n- The page carries the track's name and what it produces, and nothing more. R9 lets a page hold\n sections of its own, so no script refuses one here; what a track would say in it belongs to\n the phase that does the work or to the process that owns the track.", "tables": [] }, { "heading": "File Location", "text": "`model/processes//tracks/*.md`\n\nA track is owned by a process and cannot exist without it, so it nests inside the process's folder beside `phases/`. The filename is R12's default, the slug of the H1.", "tables": [] } ], "owner": null, "path": "core/track-schema.md" }, { "id": "01a02f39-6248-779b-b3d9-aed29f14e367", "address": "core/value", "type": "core", "name": "Value Schema", "tagline": "Required structure for value files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Value]`", "Yes", "The canonical name. Everything references the value by this exact string." ], [ "`> [Statement]`", "Yes", "One-paragraph statement of the value" ], [ "`## In practice`", "Yes", "What following this value looks like, and what breaking it looks like" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the value; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a code of conduct, a handbook" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Value]`", "Yes", "The canonical name. Everything references the value by this exact string." ], [ "`> [Statement]`", "Yes", "One-paragraph statement of the value" ], [ "`## In practice`", "Yes", "What following this value looks like, and what breaking it looks like" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the value; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A value is something the company holds itself to, written so that a strategy, a seat or a process can cite it — which is why it is one file rather than a heading in a list. It answers \"what does this company refuse to trade away, and how would anyone know?\" for someone deciding whether to work here, or deciding a hard case where two good options disagree. It is not an aspiration and not a slogan: a value nobody could act against is decoration.", "tables": [] }, { "heading": "Writing rules", "text": "- `## In practice` speaks in the company's own first person — \"I\" for a company of one, \"We\"\n for a company of more — and the same one throughout the instance. Which pronoun is the\n instance's business; that it is first person is not.\n- `## In practice` is never addressed at the reader — \"You should …\" — and never written as an\n instruction. A value is a commitment the company makes, not advice it gives.\n- `## In practice` opens with what we do, in situations that have actually come up. Its second\n half is one sentence beginning \"I never …\" / \"We never …\", and it names the specific way this\n value gets broken — not its absence.\n- `## In practice` names a situation in both halves, not an adjective. \"We write the decision\n down before the code\" can be checked against last week; \"We value quality\" cannot be checked\n against anything.\n- The statement is a sentence someone could disagree with. If no reasonable company would hold\n the opposite, it is a slogan and the value it is standing in for has not been written yet.", "tables": [] }, { "heading": "File Location", "text": "`model/values/*.md`\n\nOne file per value. Both source instances kept their values in a single document with a heading per value, and a heading has no canonical name — so no strategy, seat or process could cite the value it upholds, which is the one thing a company's values are for.", "tables": [] } ], "owner": null, "path": "core/value-schema.md" }, { "id": "01a04c7b-6b80-711e-bc03-252a77c875ab", "address": "core/vision", "type": "core", "name": "Vision Schema", "tagline": "Required structure for the vision file — the future the company is working toward.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `model/sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "Short name for the vision, the thing people call it" ], [ "`> [Statement]`", "Yes", "One-paragraph statement of the future being worked toward" ], [ "`## What it means`", "Yes", "What is true when it holds, and what it excludes" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the vision; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a talk, an article" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "Short name for the vision, the thing people call it" ], [ "`> [Statement]`", "Yes", "One-paragraph statement of the future being worked toward" ], [ "`## What it means`", "Yes", "What is true when it holds, and what it excludes" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the vision; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A vision is the future state the company is working toward, stated so that a decision can be weighed against it. It is not a plan and not a strategy: it says where, never how, and it holds still while the ways of getting there change.", "tables": [] }, { "heading": "Writing rules", "text": "- The statement is one someone could work toward and could fail at. If no decision could\n contradict it, it is a slogan and not a vision.\n- The statement could not be written as a value, or it has not said where it is going: a value\n says what we hold to whatever happens, a vision says what we are trying to make happen.\n- The page says where, not how. A named tool, a named surface or a dated milestone is a plan,\n and plans move faster than a vision should.\n- `## What it means` says what is true when it holds — concretely enough that a reader could\n tell whether it does — and what falls outside it. What is out of scope is stated, because a\n vision silent on its boundary is read as covering everything.\n- The page is written in the company's own first person, as values are: \"I\" for a company of\n one, \"we\" otherwise.", "tables": [] }, { "heading": "File Location", "text": "`model/vision.md`\n\nA company has one vision, so the type is a file directly in the container rather than a folder (R6, R13), named for the type rather than for the slug of its H1 (R12).", "tables": [] } ], "owner": null, "path": "core/vision-schema.md" }, { "id": "01a1226b-c58f-7a35-85fb-6ccaa493cc9f", "address": "landscape/data-object", "type": "landscape", "name": "Data Object Schema", "tagline": "Required structure for data object files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source, an element's GUID in an architecture tool. Absent when the source has none." ], [ "`realizes`", "Yes", "ref → concept", "The concept whose data this is, the H1 of a file in `concepts/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source, an element's GUID in an architecture tool. Absent when the source has none." ], [ "`realizes`", "Yes", "ref → concept", "The concept whose data this is, the H1 of a file in `concepts/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Data object]`", "Yes", "The canonical name, as the people who keep it name it" ], [ "`> [What it holds]`", "Yes", "One-paragraph statement of what it holds and in what form" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the data object; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a data dictionary, a schema, an architecture view" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Data object]`", "Yes", "The canonical name, as the people who keep it name it" ], [ "`> [What it holds]`", "Yes", "One-paragraph statement of what it holds and in what form" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the data object; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A data object answers \"in what form, and where, does the company keep this?\" for whoever maps a concept to the systems that hold it, migrates one of them or answers for a record. It is the layer below the concept: what a system stores, not what the business means by it. Data whose meaning nobody can name has no page here, as a function nobody uses has none. A field list is left for later.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 names the data as the people who keep it name it, `Invoice record`, `ARTICLE`, never as\n the concept it realizes, which has its own page.\n- The tagline says what the data object holds and in what form, a table, a file, a message, and\n claims nothing about its quality.\n- `realizes` names the one concept this is the data of; data that is the data of two concepts is two\n data objects.\n- The page writes names and prose in the model's language (R14), as every page does.", "tables": [] }, { "heading": "File Location", "text": "`model/data-objects/*.md`\n\nA data object is owned by nothing: several systems hold one, so it is a file, and each system's `## Holds` row names it.", "tables": [] } ], "owner": null, "path": "packs/landscape/data-object-schema.md" }, { "id": "01a12c14-d5fb-7268-ae0c-299f194e8ffb", "address": "landscape/environment", "type": "landscape", "name": "Environment Schema", "tagline": "Required structure for environment files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none." ], [ "`rank`", "Yes", "number", "The environment's place on the path from a developer's machine to the customer, the order every list of copies sorts by. Spaced in tens so one can be added without renumbering the others." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none." ], [ "`rank`", "Yes", "number", "The environment's place on the path from a developer's machine to the customer, the order every list of copies sorts by. Spaced in tens so one can be added without renumbering the others." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Environment]`", "Yes", "The canonical name, as the people who deploy to it say it. Every system that runs there references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what runs here and for whom" ], [ "`## What it means`", "Yes", "What is deployed here, who may deploy to it, what data it holds, real customers' or synthetic, and which environments are not it" ], [ "`## References`", "No", "Table. What a reader can open to reach the environment; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a console, a runbook, the pipeline that deploys here" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Environment]`", "Yes", "The canonical name, as the people who deploy to it say it. Every system that runs there references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what runs here and for whom" ], [ "`## What it means`", "Yes", "What is deployed here, who may deploy to it, what data it holds, real customers' or synthetic, and which environments are not it" ], [ "`## References`", "No", "Table. What a reader can open to reach the environment; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "An environment answers \"where does this copy stand, and what may it touch?\" in the company's words, and carries once the order every drawing and every list of copies sorts by. A copy of a software runs in exactly one environment, and a platform runs in one too, so an agent that reads a copy's page follows `environment` to what it may touch there. An environment no system names is vocabulary nobody uses, and leaves, once the instance holds a system.", "tables": [] }, { "heading": "Writing rules", "text": "- `## What it means` says what data the environment holds and who may deploy to it, since that is what an agent asks before it acts, and which environments are not it.\n- The H1 names the environment as its deployers say it, never its rank and never the platform under it.\n- `## What it means` is the one place that says what data the environment holds, real customers' or synthetic: no field says it, until an instance needs it as a fact with a check.\n- The page writes names and prose in the model's language (R14), as every page does.", "tables": [] }, { "heading": "File Location", "text": "`model/environments/*.md`\n\nAn environment owns nothing and nothing owns it: every copy that runs there names it, and what the environment is for lives here rather than being restated on every copy. It sits beside `systems/` as `system-kinds/` does.\n\nThe set is the instance's own, in the company's words: `Production`, `UAT`, `Northflank Test`. An environment arriving later is one file here, not a change to this metamodel.", "tables": [] } ], "owner": null, "path": "packs/landscape/environment-schema.md" }, { "id": "01a1226b-c5d5-7dcd-8295-40de820876db", "address": "landscape/service", "type": "landscape", "name": "Service Schema", "tagline": "Required structure for service files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source, an element's GUID in an architecture tool. Absent when the source has none." ], [ "`provided-by`", "Yes", "array of ref → system", "The systems that expose this service, each the H1 of a file in `systems/`; several where several realize one" ], [ "`realizes`", "No", "array of ref → feature", "The features this service gives people, through the products that carry them, each the H1 of a file in `features/`" ], [ "`serves`", "No", "array of ref → process", "The processes this service carries, each the H1 of a process's own file" ], [ "`domain`", "No", "ref → domain", "The area of the company the service belongs to, the H1 of a file in `domains/`, written beside `realizes` where the features alone do not place it" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source, an element's GUID in an architecture tool. Absent when the source has none." ], [ "`provided-by`", "Yes", "array of ref → system", "The systems that expose this service, each the H1 of a file in `systems/`; several where several realize one" ], [ "`realizes`", "No", "array of ref → feature", "The features this service gives people, through the products that carry them, each the H1 of a file in `features/`" ], [ "`serves`", "No", "array of ref → process", "The processes this service carries, each the H1 of a process's own file" ], [ "`domain`", "No", "ref → domain", "The area of the company the service belongs to, the H1 of a file in `domains/`, written beside `realizes` where the features alone do not place it" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Service]`", "Yes", "The canonical name of the service, as its consumers call it" ], [ "`> [What it exposes]`", "Yes", "One-paragraph statement of what the service exposes and to whom" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the service; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — an interface description, a vendor's documentation, an architecture view" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Service]`", "Yes", "The canonical name of the service, as its consumers call it" ], [ "`> [What it exposes]`", "Yes", "One-paragraph statement of what the service exposes and to whom" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the service; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A service answers \"what does this system offer the others, and who depends on it?\", the question an outage or a replacement asks first. ArchiMate 4's application and technology services are both specializations of the Common Domain's Service, so it is one type and has no kind. A system's own `realizes` and `serves` stay for an instance that models no services.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 names the service as its consumers call it, `Invoice feed`, `Price lookup`, never by the\n system behind it.\n- The tagline says what is exposed and to whom, in the consumer's words.\n- `provided-by` names the systems that expose the service, never one that only calls it.\n- `realizes` names features in the words of those features; a service nobody outside its system\n uses realizes nothing.\n- `domain` groups what a context offers outward: an API, an SDK client and a set of MCP tools\n that consumers call apart are three services provided by the same system, each named as its\n consumers call it, and the domain is what groups them, never one service that bundles them. A\n service names no bounded context, since a pack names only core's types and its own (R20); a\n context realizes domains, so a service in a domain stands beside the context of that domain.\n- The page writes names and prose in the model's language (R14), as every page does.", "tables": [] }, { "heading": "File Location", "text": "`model/services/*.md`\n\nA service is owned by nothing, and several systems may provide one, so the edge is written here: a connection row on a system can then be held to the services that system provides.", "tables": [] } ], "owner": null, "path": "packs/landscape/service-schema.md" }, { "id": "01a12186-4d00-7c74-84cd-5cde349d9b40", "address": "landscape/system", "type": "landscape", "name": "System Schema", "tagline": "Required structure for system files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source, an element's GUID in an architecture tool. Absent when the source has none." ], [ "`kind`", "Yes", "ref → system-kind", "What sort of system this is, the H1 of a file in `system-kinds/`; its `element` says which ArchiMate element a system of this kind is" ], [ "`vendor`", "No", "string", "Who makes it, where the model has no page for the party: a name, not a reference. Written only on a system naming no `processor`; where one is named, that page says which party the company's contract is with, and a maker who is another party is named in the tagline." ], [ "`lifecycle`", "No", "enum", "`planned`, `active`, `retiring` or `retired`. The stage the system is in, not a date: `planned` before it runs, `active` while it does, `retiring` while a successor takes over, `retired` once nothing runs on it." ], [ "`criticality`", "No", "enum", "`high`, `medium` or `low`. What stops when it stops." ], [ "`owner`", "No", "ref → seat", "The seat accountable for what the system does for the business, the H1 of a file in `seats/`" ], [ "`operator`", "No", "ref → seat", "The seat that runs it, the H1 of a file in `seats/`" ], [ "`processor`", "No", "ref → data-processor", "The party outside the company that runs it where it handles personal data, the H1 of a file in `data-processors/`; the contract sits on that page" ], [ "`part-of`", "No", "ref → system", "The system this one runs on or in, the H1 of another file in `systems/`: the device a terminal is, the node an application runs on. Written on the part; the whole lists nothing." ], [ "`instance-of`", "No", "ref → system", "The system this one is a running copy of, the H1 of another file in `systems/`, written on the copy; the software page names nothing. One level deep: the page named leaves `instance-of` empty, so a copy is never a copy of a copy." ], [ "`environment`", "No", "ref → environment", "Where this system runs, in the path from a developer's machine to the customer, the H1 of a file in `environments/`. Written on a copy, and on a platform, which runs somewhere too." ], [ "`domain`", "No", "ref → domain", "The area of the company the system belongs to where it realizes no feature, the H1 of a file in `domains/`" ], [ "`realizes`", "No", "array of ref → feature", "The features this system gives, each the H1 of a file in `features/`" ], [ "`serves`", "No", "array of ref → process", "The processes this system carries where no feature names it yet, each the H1 of a process's own file" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source, an element's GUID in an architecture tool. Absent when the source has none." ], [ "`kind`", "Yes", "ref → system-kind", "What sort of system this is, the H1 of a file in `system-kinds/`; its `element` says which ArchiMate element a system of this kind is" ], [ "`vendor`", "No", "string", "Who makes it, where the model has no page for the party: a name, not a reference. Written only on a system naming no `processor`; where one is named, that page says which party the company's contract is with, and a maker who is another party is named in the tagline." ], [ "`lifecycle`", "No", "enum", "`planned`, `active`, `retiring` or `retired`. The stage the system is in, not a date: `planned` before it runs, `active` while it does, `retiring` while a successor takes over, `retired` once nothing runs on it." ], [ "`criticality`", "No", "enum", "`high`, `medium` or `low`. What stops when it stops." ], [ "`owner`", "No", "ref → seat", "The seat accountable for what the system does for the business, the H1 of a file in `seats/`" ], [ "`operator`", "No", "ref → seat", "The seat that runs it, the H1 of a file in `seats/`" ], [ "`processor`", "No", "ref → data-processor", "The party outside the company that runs it where it handles personal data, the H1 of a file in `data-processors/`; the contract sits on that page" ], [ "`part-of`", "No", "ref → system", "The system this one runs on or in, the H1 of another file in `systems/`: the device a terminal is, the node an application runs on. Written on the part; the whole lists nothing." ], [ "`instance-of`", "No", "ref → system", "The system this one is a running copy of, the H1 of another file in `systems/`, written on the copy; the software page names nothing. One level deep: the page named leaves `instance-of` empty, so a copy is never a copy of a copy." ], [ "`environment`", "No", "ref → environment", "Where this system runs, in the path from a developer's machine to the customer, the H1 of a file in `environments/`. Written on a copy, and on a platform, which runs somewhere too." ], [ "`domain`", "No", "ref → domain", "The area of the company the system belongs to where it realizes no feature, the H1 of a file in `domains/`" ], [ "`realizes`", "No", "array of ref → feature", "The features this system gives, each the H1 of a file in `features/`" ], [ "`serves`", "No", "array of ref → process", "The processes this system carries where no feature names it yet, each the H1 of a process's own file" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [System]`", "Yes", "The canonical name of the system, as the people who use or run it name it" ], [ "`> [What it does]`", "Yes", "One-paragraph statement of what the system does and for whom" ], [ "`## Connects to`", "No", "Table. One row per integration this system takes data over, written on the side that takes it; its columns are declared below." ], [ "`## Holds`", "No", "Table. One row per concept this system keeps data of; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the system; its columns are declared below." ] ] }, { "caption": "`## Connects to` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`System`", "Yes", "ref → system", "The system the data comes from, by its canonical name" ], [ "`As`", "No", "string", "The interface the connection goes through, by its own name: `Payment network – Tillpay`. Required where two rows name the same system (R16)." ], [ "`Service`", "No", "qualifier → service", "`provided-by` lists `System`. The service of that system the connection calls, by its canonical name" ], [ "`Carries`", "No", "qualifier → concept", "What the connection carries, by the concept's canonical name" ], [ "`Via`", "No", "string", "How it is carried: a protocol, a file, a message queue" ] ] }, { "caption": "`## Holds` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Concept`", "Yes", "ref → concept", "What the system keeps data of, by its canonical name" ], [ "`Data object`", "No", "qualifier → data-object", "`realizes` lists `Concept`. The representation this system keeps of the concept, by its canonical name" ], [ "`Access`", "Yes", "enum", "`master`, `writes` or `reads`. The one system whose copy leads, a system that writes a copy, or one that only reads (ArchiMate 4, access relationship)." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — an operations manual, a vendor's documentation, an architecture view" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [System]`", "Yes", "The canonical name of the system, as the people who use or run it name it" ], [ "`> [What it does]`", "Yes", "One-paragraph statement of what the system does and for whom" ], [ "`## Connects to`", "No", "Table. One row per integration this system takes data over, written on the side that takes it; its columns are declared below." ], [ "`## Holds`", "No", "Table. One row per concept this system keeps data of; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the system; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A system answers \"what does this run on, what does it carry, who owns it and what breaks when it stops?\" for whoever plans a replacement, answers for an outage or asks which system masters a customer record. It is the layer below the feature: what IT buys, builds, runs and retires, whatever it is made of. It is not a product, which is what somebody uses on its own, and not a feature, which is what they do with it; a system that gives people something to do realizes a feature, and the feature says what.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 names the system as the people who run it name it, `Kassensystem`, `Filialsystem`, and\n never by its vendor alone where a word of their own exists; the vendor goes to `vendor`. An\n architecture tool's habit of writing both into one name, `Kassensystem – Tillworks Retail`,\n splits into the H1 and the field. Software a vendor runs and the company only connects to is\n named as its runners name it, which is the vendor's own name for it, `GitHub`, `Cloud Run`,\n and `vendor`, or the `processor` where one is named, still says who stands behind it.\n- `vendor` is written only where no `processor` is: a processor is a page with a legal name and a\n contract on it, and a vendor named beside it is, nearly always, the same party written twice,\n once in a form nothing resolves. Where the maker is another party than the one the contract is\n with, a terminal one company makes and an acquirer runs, the tagline names the maker, as a\n word, not a field. A system naming no processor keeps its vendor as a name.\n- The tagline says what the system does and for whom, and claims nothing about how well.\n- `kind` names what sort of system it is, what it is made of and who runs it, not what it is for:\n a payment terminal is of a kind whose `element` is `device` whatever it runs, and the software on\n it, where that is a system of its own, is of an application kind and `part-of` the terminal.\n- `realizes` names features of the products staff and customers open, in the words of those\n features; a system that gives nobody anything to do, a network, a camera, realizes nothing and\n names its `domain`, or the processes it `serves`, instead.\n- `## Connects to` is written on the system that takes the data. An exchange both ways is two\n rows, one on each page.\n- `## Holds` names concepts, not tables or files, and one system holds a concept as `master`:\n the one whose copy the others are copies of. A row with `writes` or `reads` alone is right where\n the master stands on another system; a concept only one system keeps, as a cache keeps queue\n jobs, is that system's as `master`.\n- `## Holds` names a concept once per data object the system keeps of it, and once where it keeps\n none, each at its strongest access: a system that writes a concept reads it too, and a row for\n each would draw one edge twice.\n- `## Holds` names the data object the system keeps of the concept where one is modeled, and leaves\n the cell blank where it keeps the concept in no form the model names yet.\n- `## Connects to` names the service the connection calls where one is modeled, in the same row as\n the interface it goes through.\n- `instance-of` makes a software that runs in several environments one page for the software and\n one per running copy. The software page carries what is the same wherever it runs: its kind, its owner, what it\n holds and the master's row among it, the services it provides and the features it realizes. A\n copy carries what differs where it runs: its platform, its operator, its environment and the\n connections it takes there, and repeats nothing the software page says.\n- A copy writes no `## Holds` row: the data it keeps is the software's, and a copy that claimed\n `master` beside the software's row is refused by the one-master rule.\n- `## Connects to` on a copy names what that copy takes data from there: in production the\n production database, locally the one on the laptop. A connection the software takes everywhere\n is written on the software page once.\n- The H1 of a copy names the software and its environment as the people who run it say it,\n `Billing service (production)`, so the two are told apart in every list. A database, a queue or a\n cache is a system too, and its copies follow the same pattern.\n- `instance-of` names the same software running elsewhere. Another product in the same role, an\n object store that is one product on a laptop and another in production, is a system of its own,\n with its own kind, vendor or processor and lifecycle, and the service both provide, `provided-by`\n both, is what joins them; a copy's `## Connects to` row names the system of its own environment\n with that service in `Service`.\n- The page states no cost, no license count, no version, no port, no command and no log path.\n Those move, and a contract register, a configuration database or a runbook holds them;\n `## References` names the runbook, the log console and the repository whose README carries the\n commands, one row each, so an agent reading the page finds where to look.", "tables": [] }, { "heading": "File Location", "text": "`model/systems/*.md`\n\nA system owns nothing and nothing owns it, so it is a file. What it runs on or in is its `part-of`, so a terminal moves from one node to another by editing a line and no file moves, and a device that holds no application is a page like any other.", "tables": [] } ], "owner": null, "path": "packs/landscape/system-schema.md" }, { "id": "01a12230-c82d-71c9-9871-a01cbb55497e", "address": "landscape/system-kind", "type": "landscape", "name": "System Kind Schema", "tagline": "Required structure for system kind files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "The kind's position wherever systems are drawn grouped. Spaced in tens so a kind can be added without renumbering the others." ], [ "`element`", "Yes", "enum", "`application-component`, `node`, `system-software`, `device`, `equipment` or `communication-network`. The ArchiMate 4 element a system of this kind is, an internal active structure element of the Application or Technology Domain (chapters 9 and 10), read by a generator in either direction; the kind is that element's profile-based specialization (§14.2)." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`rank`", "Yes", "number", "The kind's position wherever systems are drawn grouped. Spaced in tens so a kind can be added without renumbering the others." ], [ "`element`", "Yes", "enum", "`application-component`, `node`, `system-software`, `device`, `equipment` or `communication-network`. The ArchiMate 4 element a system of this kind is, an internal active structure element of the Application or Technology Domain (chapters 9 and 10), read by a generator in either direction; the kind is that element's profile-based specialization (§14.2)." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every system references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what sort of system this kind holds" ], [ "`## What it means`", "Yes", "What a system of this kind is made of, who runs or holds it, and which systems are not of it" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a classification, a standard" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every system references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what sort of system this kind holds" ], [ "`## What it means`", "Yes", "What a system of this kind is made of, who runs or holds it, and which systems are not of it" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A kind answers \"what sort of system is this?\" in the company's words, `SaaS`, `Store device`, `Cloud platform`, and carries once the one fact a tool needs, which element it is, so the system page says what staff say and the element comes back exact from an architecture tool, and the kind where the tool carries a specialization. A kind holds at least one system; a kind no system names is vocabulary nobody uses, and leaves, once the instance holds a system.", "tables": [] }, { "heading": "Writing rules", "text": "- `## What it means` says what a system of this kind is made of and who runs or holds it, since\n that is what tells a device in a store from the software on it, and it has nowhere else to live.\n- `## What it means` says what the kind excludes as well as what it covers.\n- `element` is the ArchiMate element and nothing more: two kinds may share one, `SaaS` and\n `Deployment` are both an application component, and the kind is what tells them apart.\n- The H1 names what the system is, `SaaS`, `Store device`, and never the element,\n `Application component`, or the type, `System`.\n- The page writes names and prose in the model's language (R14), as every page does.", "tables": [] }, { "heading": "File Location", "text": "`model/system-kinds/*.md`\n\nA kind owns nothing and nothing owns it: every system claims one of the same few, and what each kind covers lives here rather than being restated on every system. It sits beside `systems/` as `product-kinds/` sits beside `products/`.\n\nThe set is the instance's own. A kind arriving later is one file here, not a change to this metamodel and a release of it.", "tables": [] } ], "owner": null, "path": "packs/landscape/system-kind-schema.md" }, { "id": "01a114eb-b0a9-7c5a-b639-9033f599f5f9", "address": "organization/group", "type": "organization", "name": "Group Schema", "tagline": "Required structure for group files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`kind`", "Yes", "ref → group-kind", "What kind of group this is, the H1 of a file in `group-kinds/`; its `in-line` says whether the group stands in the disciplinary line" ], [ "`rank`", "No", "number", "The group's place in the company's own order of its groups, spaced in tens. Unique across all groups (R9). A group without one comes after the ranked ones, ordered by name. A disbanded group keeps its page, so the page drops its `rank` before another group takes the number." ], [ "`part-of`", "No", "ref → group", "The unit this one sits in, one step up the disciplinary line. Absent at the top and for a group outside the line." ], [ "`guides`", "No", "array of ref → job", "The jobs whose discipline this group sets, wherever the people who do them sit, each the H1 of a file in `jobs/`: the professional line" ], [ "`start`", "No", "date", "When the group was formed, for a group that is not standing" ], [ "`end`", "No", "date", "When the group was disbanded: the last day it existed, as R9 reads an `end`. A person who moves to another unit is in the new one from the next day, so the old unit's `end` is the day before the move. Absent while it exists. A disbanded group keeps its page." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`kind`", "Yes", "ref → group-kind", "What kind of group this is, the H1 of a file in `group-kinds/`; its `in-line` says whether the group stands in the disciplinary line" ], [ "`rank`", "No", "number", "The group's place in the company's own order of its groups, spaced in tens. Unique across all groups (R9). A group without one comes after the ranked ones, ordered by name. A disbanded group keeps its page, so the page drops its `rank` before another group takes the number." ], [ "`part-of`", "No", "ref → group", "The unit this one sits in, one step up the disciplinary line. Absent at the top and for a group outside the line." ], [ "`guides`", "No", "array of ref → job", "The jobs whose discipline this group sets, wherever the people who do them sit, each the H1 of a file in `jobs/`: the professional line" ], [ "`start`", "No", "date", "When the group was formed, for a group that is not standing" ], [ "`end`", "No", "date", "When the group was disbanded: the last day it existed, as R9 reads an `end`. A person who moves to another unit is in the new one from the next day, so the old unit's `end` is the day before the move. Absent while it exists. A disbanded group keeps its page." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The group's name. Every reference uses this exact string." ], [ "`> [Purpose]`", "Yes", "What the group is for, in one paragraph" ], [ "`## Responsibilities`", "No", "Bulleted. What the group answers for, one item each" ], [ "`## People`", "No", "Table. The people who sit in the group, each with the job they do there and their place in it; its columns are declared below." ], [ "`## Openings`", "No", "Table. The positions the group is looking to fill, one row per job and place; its columns are declared below." ], [ "`## Direction`", "No", "Table. Which human of the group directs which agent in it, one row per agent and human, written only where not every human directs every agent; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the group — a charter, a mandate; its columns are declared below." ] ] }, { "caption": "`## People` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Profile`", "Yes", "ref → profile", "The person, the H1 of a profile" ], [ "`Job`", "No", "qualifier → job", "What the person does in the group, the H1 of a file in `jobs/`. In the person's unit in the line it is the job they are employed as; in a group outside the line, the job they do there. A person who does two jobs in a group has a row for each. Blank where the person is not employed in a job here, as an agent is not." ], [ "`Place`", "Yes", "enum", "`Lead`, `Deputy`, `Member` or `Staff`. The person's place in the group: the one who leads it, one who stands in for the lead, one who sits in it, or one who serves its lead from beside them, as an assistant does." ] ] }, { "caption": "`## Openings` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Job`", "Yes", "ref → job", "The job that is open, the H1 of a file in `jobs/`" ], [ "`Place`", "Yes", "enum", "`Lead`, `Deputy`, `Member` or `Staff`. The place in the group that is open, as in `## People`. An open `Lead` beside a `Lead` in `## People` is the search for a successor while the present lead stays." ], [ "`Count`", "No", "number", "How many openings the row stands for. Blank is one." ], [ "`Since`", "No", "date", "From when the position is to be filled" ] ] }, { "caption": "`## Direction` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Agent`", "Yes", "ref → profile", "The agent, the H1 of a profile whose `nature` is `agent`, named in `## People`" ], [ "`Directed by`", "Yes", "qualifier → profile", "One human of the group who directs it, the H1 of a profile whose `nature` is `human`, named in `## People`. An agent directed by two of them has a row for each." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a charter, a mandate" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Name]`", "Yes", "The group's name. Every reference uses this exact string." ], [ "`> [Purpose]`", "Yes", "What the group is for, in one paragraph" ], [ "`## Responsibilities`", "No", "Bulleted. What the group answers for, one item each" ], [ "`## People`", "No", "Table. The people who sit in the group, each with the job they do there and their place in it; its columns are declared below." ], [ "`## Openings`", "No", "Table. The positions the group is looking to fill, one row per job and place; its columns are declared below." ], [ "`## Direction`", "No", "Table. Which human of the group directs which agent in it, one row per agent and human, written only where not every human directs every agent; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the group — a charter, a mandate; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A group is a unit of the company, or a team drawn from its units, and answers \"who sits together, under whom, and whose standard do they work to?\" Its `## People` rows are its positions, each one person in one job in one place; a position is a job in a group, and a row, not a page. A position that is open is a row of `## Openings` until someone fills it, and the person then takes a row of `## People` in the same change. In a group whose kind is in the line, a person answers to the person whose `Place` is `Lead`, and that lead to the lead of the unit its `part-of` names, as Gabler's Einliniensystem has it. Its `guides` is the professional line, the professional right to direct of a matrix, the fachliches Weisungsrecht: the unit that sets a discipline's standard lists that discipline's jobs, and the standard holds wherever the people who do them sit. A group outside the line is where an agent sits, and every human named in it directs every agent named in it: `Lead` and `Deputy` say who answers for the group, not who alone may direct, and a person who must not direct its agents is not in that group. Where a company grants direction per agent rather than per group, as a platform does that binds each agent to its controller, the group says so in `## Direction`, one row per agent and human, a fact about the two rather than a second position for the agent; a group without the section keeps the rule, the group stays the one unit its people work in, and who directs an agent is still read from its page. The checks hold the norms that follow from this: a person sits in at most one unit in the line, only a human sits in one, only a human leads or deputizes, a group has one lead, a person has one place in a group, a group whose `part-of` names a staff unit is of a staff kind, a group outside the line that names an agent names a human beside it, and a `## Direction` row names an agent and a human that `## People` names, once per pair.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 names the group as the company calls it, without its kind: `Engineering`, not `Engineering department`.\n- The tagline says what the group is for, not who sits in it.\n- `guides` names only jobs whose discipline the group sets, not jobs that merely work with it.\n- `## Openings` holds a job and place in one row; `Count` says how many, a whole number above zero.\n- `## Direction` names every human who directs an agent it names: an agent with a row there is directed by the humans its rows name and no other, and an agent without one by every human in the group.", "tables": [] }, { "heading": "File Location", "text": "`model/groups/*.md`\n\nA group owns nothing and nothing owns it, so it is a file. Its place in the tree is its `part-of`, so a reorganization edits one field and moves no file, and a team drawn across units stands beside them.", "tables": [] } ], "owner": null, "path": "packs/organization/group-schema.md" }, { "id": "01a114eb-b0e2-7773-b742-d5556cadc57b", "address": "organization/group-kind", "type": "organization", "name": "Group Kind Schema", "tagline": "Required structure for group kind files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`in-line`", "Yes", "enum", "`yes` or `no`. Whether a group of this kind stands in the disciplinary line, and so whether a person named in its `## People` has it as their unit." ], [ "`staff`", "No", "enum", "`yes` or `no`. Whether a group of this kind serves the head of the group its `part-of` names, from beside it rather than below it, as a legal department serves the managing director. Blank is `no`." ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`in-line`", "Yes", "enum", "`yes` or `no`. Whether a group of this kind stands in the disciplinary line, and so whether a person named in its `## People` has it as their unit." ], [ "`staff`", "No", "enum", "`yes` or `no`. Whether a group of this kind serves the head of the group its `part-of` names, from beside it rather than below it, as a legal department serves the managing director. Blank is `no`." ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every group references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the kind covers" ], [ "`## What it means`", "Yes", "Which groups belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — an organization handbook, a framework" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Label]`", "Yes", "The canonical name. Every group references this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph summary of what the kind covers" ], [ "`## What it means`", "Yes", "Which groups belong to this kind, and which do not" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the kind; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A group kind says what kind of group a company has, and whether groups of it stand in the disciplinary line. A standing unit does; a board, a cross-functional team or an initiative team does not, and the people it gathers keep the unit they already sit in. That one fact is what lets a board and a team list people who are already in a unit without giving any person a second disciplinary line. It also decides where a group stands in the tree: only a group of a kind in the line has a `part-of`, and only such a group is named in one. A staff unit is in the line all the same: its people have it as their unit and its lead answers up through its `part-of`, and only how a chart draws it, beside the head it serves, and what may hang below it, only staff, set it apart.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 is the kind's name, singular: `Department`, not `Departments`.\n- `## What it means` names what a group of the kind is for and one kind of group it is not.\n- `in-line` is `yes` only for a kind whose groups hire, appraise and set objectives for the people in them.\n- `staff` is `yes` only on a kind whose `in-line` is `yes`, since staff outside the line serves no head in it.", "tables": [] }, { "heading": "File Location", "text": "`model/group-kinds/*.md`\n\nA group kind owns nothing and nothing owns it, so it is a file. A company names its own kinds; the pack ships none.", "tables": [] } ], "owner": null, "path": "packs/organization/group-kind-schema.md" }, { "id": "01a1199f-28ad-7f8d-93b9-c9b71903339d", "address": "organization/job", "type": "organization", "name": "Job Schema", "tagline": "Required structure for job files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`seats`", "No", "array of ref → seat", "The seats in the company's processes that a person in this job usually holds, each the H1 of a file in `seats/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`seats`", "No", "array of ref → seat", "The seats in the company's processes that a person in this job usually holds, each the H1 of a file in `seats/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Job]`", "Yes", "The canonical name of the job. A group's `guides` and `## People` reference it by this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph statement of what the job is for" ], [ "`## Responsibilities`", "No", "Bulleted. What the job answers for, one item each" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the job — a job description, a career framework; its columns are declared below." ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a job description, a career framework" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Job]`", "Yes", "The canonical name of the job. A group's `guides` and `## People` reference it by this exact string." ], [ "`> [Summary]`", "Yes", "One-paragraph statement of what the job is for" ], [ "`## Responsibilities`", "No", "Bulleted. What the job answers for, one item each" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the job — a job description, a career framework; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A job is what a person is employed as and, in a group outside the line, the job someone does there, the same wherever they sit: one file, named once, done in as many groups as the company has. It answers \"what does this job answer for, and which seats in the company's processes does a person in it usually take?\" It is not a seat, core's own type: a responsibility in a process, taken by whoever the process hands it to whatever job they are employed in. It is not a position either, which is a job in a group, one person's row in the group's `## People`, and which no page holds.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 names the job as the company titles it, singular and person-neutral: `Backend Engineer`, not `Backend Engineers` and not the name of anyone who does it.\n- The tagline says what the job is for, not who holds it.\n- `seats` names only seats a holder of the job takes in the company's processes, not seats that a person happens to hold beside the job.", "tables": [] }, { "heading": "File Location", "text": "`model/jobs/*.md`\n\nA job owns nothing and nothing owns it, so it is a file. A group names it in its `guides` and in its `## People` rows, and the job never names a group or a person.", "tables": [] } ], "owner": null, "path": "packs/organization/job-schema.md" }, { "id": "01a12af5-ba03-7c84-98a2-79c3c0928b4c", "address": "requirements/requirement", "type": "requirements", "name": "Requirement Schema", "tagline": "Required structure for requirement files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source, the label a specification gives it: `FR-011`. Absent when the source has none." ], [ "`kind`", "Yes", "enum", "`functional`, `quality` or `constraint`. A result or behavior a function of the product provides; a quality concern no functional requirement covers, how fast, how safe, how available; or a limit on the solution beyond what the other two need (IREB CPRE glossary)." ], [ "`modality`", "Yes", "enum", "`must`, `should` or `may`. Binding; binding unless a reason to depart is understood and stated; or permitted (RFC 2119)." ], [ "`follows`", "No", "array of ref → rule", "The company's rules this requirement carries into the product, each the H1 of a file in `rules/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source, the label a specification gives it: `FR-011`. Absent when the source has none." ], [ "`kind`", "Yes", "enum", "`functional`, `quality` or `constraint`. A result or behavior a function of the product provides; a quality concern no functional requirement covers, how fast, how safe, how available; or a limit on the solution beyond what the other two need (IREB CPRE glossary)." ], [ "`modality`", "Yes", "enum", "`must`, `should` or `may`. Binding; binding unless a reason to depart is understood and stated; or permitted (RFC 2119)." ], [ "`follows`", "No", "array of ref → rule", "The company's rules this requirement carries into the product, each the H1 of a file in `rules/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Requirement]`", "Yes", "The requirement's short name. Everything references it, and a test or a code comment cites it, by this exact string." ], [ "`> [Statement]`", "Yes", "The requirement itself: one thing a product could be shown to meet or to miss" ], [ "`## Why`", "Yes", "The need behind the statement, in a paragraph" ], [ "`## Fit criterion`", "Yes", "How anyone can tell the requirement is met, measured where it can be (Volere)" ], [ "`## Applies to`", "Yes", "Table. The features, products and use cases the requirement is about, at least one; its columns are declared below." ], [ "`## References`", "No", "Table. The specification it was drawn from, the standard behind it, the test that proves it; its columns are declared below." ] ] }, { "caption": "`## Applies to` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Type`", "Yes", "enum", "`feature`, `product` or `use-case`. The type of the entity this row names, as its schema is named." ], [ "`Entity`", "Yes", "ref → by Type", "The feature, product or use case, by its canonical name" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a specification, a standard, a test" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Requirement]`", "Yes", "The requirement's short name. Everything references it, and a test or a code comment cites it, by this exact string." ], [ "`> [Statement]`", "Yes", "The requirement itself: one thing a product could be shown to meet or to miss" ], [ "`## Why`", "Yes", "The need behind the statement, in a paragraph" ], [ "`## Fit criterion`", "Yes", "How anyone can tell the requirement is met, measured where it can be (Volere)" ], [ "`## Applies to`", "Yes", "Table. The features, products and use cases the requirement is about, at least one; its columns are declared below." ], [ "`## References`", "No", "Table. The specification it was drawn from, the standard behind it, the test that proves it; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A requirement is one statement of what a product must do or be, written so that it can be shown met or missed (ISO/IEC/IEEE 29148), and it answers \"what exactly is this held to, why, and how would anyone tell?\" for whoever builds, tests or accepts it. It is a page so that a test, a code comment or a later specification can cite it by a name and an id no other requirement shares. It is not a rule, which binds the company's own conduct; a requirement that exists because of a rule names it in `follows`.", "tables": [] }, { "heading": "Writing rules", "text": "- The tagline says one thing, so that a product could be shown to meet it or to miss it; a statement that joins two with \"and\" is two requirements.\n- The tagline says what, not how: it names no component, library or vendor unless `kind` is `constraint`.\n- `modality` is the strength the tagline states, and a tagline that says \"must not\" carries `must`.\n- `## Fit criterion` names what is observed and what counts as met, with the measure and the conditions it is taken under where it is a quantity; \"works well\" is no criterion.\n- `kind` is `quality` where `## Fit criterion` measures how well the product does something rather than whether it does it.\n- `## Applies to` names the narrowest subject that carries the requirement: a feature where one feature does, a product where every feature of it does.\n- `follows` names a rule only where the requirement exists because of it.\n- `## Why` says the need, not the solution.\n- `source-id`, on a page drawn from a specification, is the label the specification gives it, so a test that cites the label still finds the page.\n- The page holds no priority, status, release or date; each moves, and a References row says where they are kept.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/requirements/*.md`\n\nA requirement owns nothing and nothing owns it, so it is a file. What it is about is its `## Applies to`, a feature, a product or a use case, so a requirement that holds for a whole product is written once and not on each feature.", "tables": [] } ], "owner": null, "path": "packs/requirements/requirement-schema.md" }, { "id": "01a12af5-b9cd-7a47-aec7-4fe31d66d287", "address": "requirements/use-case", "type": "requirements", "name": "Use Case Schema", "tagline": "Required structure for use case files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`level`", "Yes", "enum", "`very high summary`, `summary`, `user goal` or `subfunction`. How high the goal stands against what a primary actor gets done in one sitting: well above it, above it, at it, or below it (Cockburn's goal levels, drawn as cloud, kite, waves at sea and fish). The four are listed from the highest down, and the order is read: what a use case includes stands at its level or below." ], [ "`scope`", "No", "enum", "`organization`, `system` or `component`. What the use case treats as the thing under design (Cockburn's design scope)." ], [ "`primary-actor`", "Yes", "ref? → seat", "Whoever has the goal: the H1 of a file in `seats/` where the company has the seat, otherwise the actor's name, which stays a string" ], [ "`features`", "No", "array of ref → feature", "The features the use case asks something of, each the H1 of a file in `features/`" ], [ "`includes`", "No", "array of ref → use-case", "The subordinate use cases its steps call, each the H1 of another file in `use-cases/` (UML include)" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered, the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source. Absent when the source has none, as a repository does not." ], [ "`level`", "Yes", "enum", "`very high summary`, `summary`, `user goal` or `subfunction`. How high the goal stands against what a primary actor gets done in one sitting: well above it, above it, at it, or below it (Cockburn's goal levels, drawn as cloud, kite, waves at sea and fish). The four are listed from the highest down, and the order is read: what a use case includes stands at its level or below." ], [ "`scope`", "No", "enum", "`organization`, `system` or `component`. What the use case treats as the thing under design (Cockburn's design scope)." ], [ "`primary-actor`", "Yes", "ref? → seat", "Whoever has the goal: the H1 of a file in `seats/` where the company has the seat, otherwise the actor's name, which stays a string" ], [ "`features`", "No", "array of ref → feature", "The features the use case asks something of, each the H1 of a file in `features/`" ], [ "`includes`", "No", "array of ref → use-case", "The subordinate use cases its steps call, each the H1 of another file in `use-cases/` (UML include)" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Use case]`", "Yes", "The goal as a short active verb phrase. Everything references the use case by this exact string." ], [ "`> [Goal]`", "Yes", "One paragraph of what the primary actor wants and what they have when it is done" ], [ "`## Stakeholders and interests`", "Yes", "Table. Every party with an interest in how the use case goes, and what each needs from it; its columns are declared below." ], [ "`## Preconditions`", "No", "Bulleted. What the system makes sure of before the use case may start, one item each" ], [ "`## Trigger`", "No", "What starts the use case, which may be a time" ], [ "`## Main success scenario`", "Yes", "Table. The steps from the trigger to the goal when nothing goes wrong, one row each, in order; its columns are declared below." ], [ "`## Extensions`", "No", "Table. Each condition under which a step goes another way, and what happens then; its columns are declared below." ], [ "`## Minimal guarantees`", "Yes", "Bulleted. What holds for every stakeholder however the use case ends, one item each" ], [ "`## Success guarantees`", "Yes", "Bulleted. What holds when the goal is reached, one item each" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the use case; its columns are declared below." ] ] }, { "caption": "`## Stakeholders and interests` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Stakeholder`", "Yes", "ref? → seat", "The party: the H1 of a file in `seats/` where it is a seat, otherwise its name, which stays a string" ], [ "`Interest`", "Yes", "string", "What the party needs from the use case, or needs protected while it runs" ] ] }, { "caption": "`## Main success scenario` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Step`", "Yes", "string", "The step's label, unique on the page, which an extension and a test cite: `1`, `2`" ], [ "`Actor`", "Yes", "ref? → seat", "Who acts in the step: the H1 of a file in `seats/` where it is a seat, otherwise its name, which stays a string" ], [ "`Action`", "Yes", "string", "What the actor does, in one sentence" ] ] }, { "caption": "`## Extensions` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Step`", "Yes", "string", "The label of the step it branches from and one lowercase letter: `2a`" ], [ "`Condition`", "Yes", "string", "What the system can detect that sends the step another way" ], [ "`Handling`", "Yes", "string", "What happens then, and where the scenario goes on" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a specification, a recording of the flow" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Use case]`", "Yes", "The goal as a short active verb phrase. Everything references the use case by this exact string." ], [ "`> [Goal]`", "Yes", "One paragraph of what the primary actor wants and what they have when it is done" ], [ "`## Stakeholders and interests`", "Yes", "Table. Every party with an interest in how the use case goes, and what each needs from it; its columns are declared below." ], [ "`## Preconditions`", "No", "Bulleted. What the system makes sure of before the use case may start, one item each" ], [ "`## Trigger`", "No", "What starts the use case, which may be a time" ], [ "`## Main success scenario`", "Yes", "Table. The steps from the trigger to the goal when nothing goes wrong, one row each, in order; its columns are declared below." ], [ "`## Extensions`", "No", "Table. Each condition under which a step goes another way, and what happens then; its columns are declared below." ], [ "`## Minimal guarantees`", "Yes", "Bulleted. What holds for every stakeholder however the use case ends, one item each" ], [ "`## Success guarantees`", "Yes", "Bulleted. What holds when the goal is reached, one item each" ], [ "`## References`", "No", "Table. What a reader can open to learn more about the use case; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A use case is all the ways of using a system to achieve one goal for one actor (Cockburn and Jacobson), and it answers \"who wants this, what do they get, who else has a stake, and what still holds when it goes wrong?\" for whoever decides what a feature must do before anyone designs it. It is the problem side of a feature: core's feature says what someone can do, and the use case says what they want and what is guaranteed, at the level it names. It is not a design, which the software pack's feature design is, and not a requirement, which states one thing a product is held to and may apply to a use case.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 is the primary actor's goal as a short active verb phrase, `Download an invoice`, and never a screen or a feature's name.\n- The tagline says what the primary actor wants and what they have when it is done, in their words.\n- `level` is `user goal` where the primary actor gets the goal done in one sitting and goes away content; a goal that gathers several of those is a summary, and one that no actor would stop after is a subfunction.\n- `primary-actor` names a seat where the company has one for whoever has the goal, and otherwise the actor as the company calls them: `Customer`, `Payment provider`.\n- `## Stakeholders and interests` names every party whose interest the use case must protect, the primary actor among them, and each Interest says what the party needs, not what it does.\n- Each row of `## Main success scenario` is one actor doing one thing that moves toward the goal; a condition is an extension, never a step.\n- `Action`, in a step that calls a subordinate use case, names that use case by its H1, and every use case in `includes` is named so in some step.\n- `includes` names use cases at the page's `level` or below, in the order `level` lists them: a summary may call a user goal, and a subfunction calls no summary.\n- `Condition`, in `## Extensions`, is something the system can detect, not something an actor feels.\n- `## Minimal guarantees` hold however the use case ends, an extension that gives up included, and `## Success guarantees` only when the goal is reached.\n- `Action` names an aggregate, an invariant or an event, where a step needs one, in words: they are another pack's types, and the page draws no edge to them.\n- The page writes names and prose in American English (R14).", "tables": [] }, { "heading": "File Location", "text": "`model/use-cases/*.md`\n\nA use case owns nothing and nothing owns it, so it is a file. One use case may be called by several others, so the edge is written on the one that calls, in `includes`, and the called use case names none of its callers.", "tables": [] } ], "owner": null, "path": "packs/requirements/use-case-schema.md" }, { "id": "01a0f94d-fa63-7c7e-8af5-b2d7e5b870cf", "address": "software/aggregate", "type": "software", "name": "Aggregate Schema", "tagline": "Required structure for aggregate files.", "fields": { "owner": "bounded-context" }, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`root`", "Yes", "ref → concept-design", "The entity through which the aggregate is reached, a concept design of kind `entity` in the same context (Evans)" ], [ "`members`", "No", "array of ref → concept-design", "The other concept designs the aggregate holds, beside its root" ], [ "`decisions`", "No", "array of ref → decision", "The decisions that shaped this aggregate, the H1s of files in `decisions/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`root`", "Yes", "ref → concept-design", "The entity through which the aggregate is reached, a concept design of kind `entity` in the same context (Evans)" ], [ "`members`", "No", "array of ref → concept-design", "The other concept designs the aggregate holds, beside its root" ], [ "`decisions`", "No", "array of ref → decision", "The decisions that shaped this aggregate, the H1s of files in `decisions/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Aggregate]`", "Yes", "The aggregate's name, usually its root's" ], [ "`> [Consistency]`", "Yes", "What the aggregate keeps consistent, in one sentence" ], [ "`## Invariants`", "Yes", "Table. One rule per row that holds after every change, under a label a test or a code comment cites it by (DDD Crew, Aggregate Design Canvas); its columns are declared below." ], [ "`## Handled commands`", "No", "Table. What the aggregate is asked to do; its columns are declared below." ], [ "`## State transitions`", "No", "Table. The states the aggregate moves through and what moves it, one transition per row (DDD Crew, Aggregate Design Canvas); its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the aggregate; its columns are declared below." ] ] }, { "caption": "`## Invariants` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Label`", "Yes", "string", "What the invariant is cited by: letters, digits and hyphens, unique within the aggregate, such as `INV-T1`" ], [ "`Invariant`", "Yes", "string", "The rule, stated so a test could check it" ] ] }, { "caption": "`## Handled commands` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Command`", "Yes", "string", "The command, in the imperative: \"Issue invoice\"" ], [ "`Emits`", "No", "ref → domain-event", "An event the command emits, by its canonical name, an event of this context; a command that emits two is two rows" ], [ "`When`", "No", "string", "When the command emits this event rather than another, in words; it may cite the invariants it rests on by their labels" ], [ "`Description`", "No", "string", "What it asks for, and what it refuses" ] ] }, { "caption": "`## State transitions` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`From`", "No", "string", "The state the aggregate leaves, blank for the transition that starts it" ], [ "`Command`", "No", "string", "The handled command that moves it, as `## Handled commands` writes it, blank for a step the aggregate takes on its own" ], [ "`To`", "Yes", "string", "The state it reaches; a state that is never a `From` ends the lifecycle" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — an aggregate canvas, a design note" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Aggregate]`", "Yes", "The aggregate's name, usually its root's" ], [ "`> [Consistency]`", "Yes", "What the aggregate keeps consistent, in one sentence" ], [ "`## Invariants`", "Yes", "Table. One rule per row that holds after every change, under a label a test or a code comment cites it by (DDD Crew, Aggregate Design Canvas); its columns are declared below." ], [ "`## Handled commands`", "No", "Table. What the aggregate is asked to do; its columns are declared below." ], [ "`## State transitions`", "No", "Table. The states the aggregate moves through and what moves it, one transition per row (DDD Crew, Aggregate Design Canvas); its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the aggregate; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "An aggregate answers \"what has to stay consistent together, and through what is it changed?\" It is Evans's aggregate: a cluster of concept designs changed only through its root. The invariants are a table and not a numbered list, because they are a set and not a sequence, and a position is no key anything outside can cite. A command is a row here and not a type, because nothing outside the aggregate names it. Each event names its aggregate as `emitted-by`, and a handled command may name the events it emits, one row per command and event, which is where a flow is read from; when it emits one rather than another is said in words, and may cite the invariants it rests on. The root is a concept design of kind entity, since a value object has no identity to reach the rest through. A label stays when its invariant is reworded, a new rule takes a new label, and a removed rule's label is not used again.", "tables": [] }, { "heading": "Writing rules", "text": "- `Invariant` is a rule that holds after every command, stated so a test could check it.\n- `Command` is named in the imperative, and an event in the past tense, so the two are never confused.\n- `source`, on a page drawn from code, names that code, the repository a sync reads, and the module or package is its `source-id`; a page written here that code then follows names the code in `## References` as `Implementation`.\n- An event `Emits` names is one whose `emitted-by` is this aggregate.\n- A `Command` in `## State transitions` is written as `## Handled commands` writes it.", "tables": [] }, { "heading": "File Location", "text": "`model/bounded-contexts//aggregates/*.md`", "tables": [] } ], "owner": null, "path": "packs/software/aggregate-schema.md" }, { "id": "01a0f94d-f9e9-70c4-a498-9e19505fd58d", "address": "software/bounded-context", "type": "software", "name": "Bounded Context Schema", "tagline": "Required structure for bounded context files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`classification`", "Yes", "enum", "`core`, `supporting` or `generic`. How much it matters to build this well: where the company competes, what it needs and builds for itself, or what it could buy (DDD Crew, Bounded Context Canvas)." ], [ "`realizes`", "No", "array of ref → domain", "The domains this context serves, the H1s of files in `domains/`; a context may serve several and a domain be served by several (Vernon)" ], [ "`decisions`", "No", "array of ref → decision", "The decisions that shaped this context, the H1s of files in `decisions/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`classification`", "Yes", "enum", "`core`, `supporting` or `generic`. How much it matters to build this well: where the company competes, what it needs and builds for itself, or what it could buy (DDD Crew, Bounded Context Canvas)." ], [ "`realizes`", "No", "array of ref → domain", "The domains this context serves, the H1s of files in `domains/`; a context may serve several and a domain be served by several (Vernon)" ], [ "`decisions`", "No", "array of ref → decision", "The decisions that shaped this context, the H1s of files in `decisions/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Bounded Context]`", "Yes", "The canonical name of the context" ], [ "`> [Purpose]`", "Yes", "What the context is responsible for, and one thing it leaves to another context" ], [ "`## Responsibilities`", "Yes", "Bulleted. One responsibility each, in business words" ], [ "`## Relationships`", "No", "Table. One row per context this one depends on, written on the downstream side; its columns are declared below." ], [ "`## Consumes`", "No", "Table. One row per domain event this context takes from another; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the context; its columns are declared below." ] ] }, { "caption": "`## Relationships` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Context`", "Yes", "ref → bounded-context", "The upstream context this one depends on, by its canonical name" ], [ "`Pattern`", "Yes", "enum", "`partnership`, `shared kernel`, `customer/supplier`, `conformist`, `anticorruption layer`, `open host service`, `published language`, `separate ways` or `big ball of mud`. How the two contexts relate (DDD Crew, Context Mapping)." ] ] }, { "caption": "`## Consumes` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Type`", "Yes", "string", "The type of what is consumed, as its schema is named: `domain-event`" ], [ "`Entity`", "Yes", "ref → by Type in Context", "What is consumed, by its canonical name" ], [ "`Context`", "Yes", "string", "The context that owns it, by its canonical name" ], [ "`Reaction`", "No", "string", "What this context does in response, naming the handled command in words; a command is a row on its aggregate, and nothing can reference it (Event Modeling, policy)" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a context canvas, a service's documentation" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Bounded Context]`", "Yes", "The canonical name of the context" ], [ "`> [Purpose]`", "Yes", "What the context is responsible for, and one thing it leaves to another context" ], [ "`## Responsibilities`", "Yes", "Bulleted. One responsibility each, in business words" ], [ "`## Relationships`", "No", "Table. One row per context this one depends on, written on the downstream side; its columns are declared below." ], [ "`## Consumes`", "No", "Table. One row per domain event this context takes from another; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the context; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A bounded context answers \"within which boundary does one model, and one meaning of each word, hold?\" It is Evans's bounded context and the solution side of core's domain: a domain says what area of the company something belongs to, and a context says where one model of it is built. It owns the terms of its language, so two contexts may mean different things by one word, which is the problem domain-driven design exists to solve. Its strategic classification departs from Evans, who puts it on the subdomain; it sits here, as the DDD Crew's canvas puts it, so that core's domain stays untouched. A relationship is written on the downstream context, the side that knows it depends, and a symmetric pattern, a partnership or a shared kernel, is written once, on either side.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 is the business's name, not a service's or a team's: \"Billing\", not \"billing-service\".\n- The purpose names one thing the context leaves to another, so its boundary can be read from its first line.\n- `## Consumes` names each event the context consumes, and `## Relationships` names the context it comes from.\n- `Reaction` says what happens here, not in the context that emitted the event.\n- `source`, on a page drawn from code, names that code, the repository a sync reads, and the module or package is its `source-id`; a page written here that code then follows names the code in `## References` as `Implementation`.", "tables": [] }, { "heading": "File Location", "text": "`model/bounded-contexts//.md`\n\nA bounded context owns the terms of its language, its aggregates and its events, so it is a folder and they nest inside it (R5, R6).", "tables": [] } ], "owner": null, "path": "packs/software/bounded-context-schema.md" }, { "id": "01a0f94d-fa2a-7d34-ad48-bda5aa4a62c1", "address": "software/concept-design", "type": "software", "name": "Concept Design Schema", "tagline": "Required structure for concept design files.", "fields": { "owner": "bounded-context" }, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`kind`", "Yes", "enum", "`entity` or `value object`. An entity is defined by an identity that persists through changes to its attributes; a value object is defined only by its attributes and is replaced rather than changed (Evans)." ], [ "`refines`", "No", "ref → concept", "The enterprise concept this term narrows, the H1 of a file in `concepts/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`kind`", "Yes", "enum", "`entity` or `value object`. An entity is defined by an identity that persists through changes to its attributes; a value object is defined only by its attributes and is replaced rather than changed (Evans)." ], [ "`refines`", "No", "ref → concept", "The enterprise concept this term narrows, the H1 of a file in `concepts/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Concept Design]`", "Yes", "The term, as the context's people say it" ], [ "`> [Meaning]`", "Yes", "What the word means in this context, and nowhere else" ], [ "`## Attributes`", "No", "Table. What the term carries; its columns are declared below." ], [ "`## Relations`", "No", "Table. Other terms of the same context this one is related to; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the term; its columns are declared below." ] ] }, { "caption": "`## Attributes` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Attribute`", "Yes", "string", "The attribute's name, as the context's people say it" ], [ "`Term`", "No", "ref → concept-design", "A value object of the same context, by its canonical name, where the attribute is one; an entity is a relation" ], [ "`Type`", "No", "enum", "`string`, `number`, `boolean`, `date`, `timestamp`, `duration`, `version`, `hash`, `path`, `id`, `URL`, `file`, `language` or `map`. A plain type, where the attribute is no term; its unit, or what it is of, goes in the Description." ], [ "`Many`", "No", "enum", "`yes`. The attribute is a list of what `Term` or `Type` names; blank for one." ], [ "`Description`", "No", "string", "What the attribute says" ] ] }, { "caption": "`## Relations` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Concept`", "Yes", "ref → concept-design", "The related term in the same context, by its canonical name" ], [ "`Cardinality`", "Yes", "enum", "`one`, `maybe one`, `many` or `one to many`. How many of the target one of these has: exactly one, none or one, none or more, or one or more." ], [ "`As`", "No", "string", "The role the target plays, required where two rows name the same concept" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a model diagram, a glossary" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Concept Design]`", "Yes", "The term, as the context's people say it" ], [ "`> [Meaning]`", "Yes", "What the word means in this context, and nowhere else" ], [ "`## Attributes`", "No", "Table. What the term carries; its columns are declared below." ], [ "`## Relations`", "No", "Table. Other terms of the same context this one is related to; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the term; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A concept design answers \"what does this word mean here?\" It is one term of a bounded context's ubiquitous language (Evans), and an entity or a value object by its kind. It may refine an enterprise concept of core, which says what the thing is for the whole company; the concept design says what it is inside one context, which is narrower and may differ from another context's term of the same name. A relation is written on one side only, as core's concept relations are, so no two concept designs each name the other in `## Relations`. An attribute names a value object of its own context in `Term` or a plain type in `Type`, exactly one of the two, and an entity it would name is a relation.", "tables": [] }, { "heading": "Writing rules", "text": "- The meaning says what the thing is in this context, not what a system does with it.\n- `kind` follows Evans's test: if every attribute changed, would it still be the same one? Then it is an entity.\n- `source`, on a page drawn from code, names that code, the repository a sync reads, and the module or package is its `source-id`; a page written here that code then follows names the code in `## References` as `Implementation`.", "tables": [] }, { "heading": "File Location", "text": "`model/bounded-contexts//concept-designs/*.md`\n\nA concept design is a term of one context's language and means nothing outside it, so it nests inside its context (R5, R10), and its name is unique within that context (R2).", "tables": [] } ], "owner": null, "path": "packs/software/concept-design-schema.md" }, { "id": "01a0f94d-fa9a-7907-ae3d-621f34d6e909", "address": "software/domain-event", "type": "software", "name": "Domain Event Schema", "tagline": "Required structure for domain event files.", "fields": { "owner": "bounded-context" }, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`emitted-by`", "Yes", "ref → aggregate", "The aggregate whose change the event records, in the same context" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`emitted-by`", "Yes", "ref → aggregate", "The aggregate whose change the event records, in the same context" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Domain Event]`", "Yes", "What happened, in the past tense: \"Invoice issued\"" ], [ "`> [What happened]`", "Yes", "The event in business words, in one sentence" ], [ "`## Payload`", "No", "Table. What the event carries; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the event; its columns are declared below." ] ] }, { "caption": "`## Payload` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`Attribute`", "Yes", "string", "The value's name, as the context's people say it" ], [ "`Term`", "No", "ref → concept-design", "A concept design of the same context, of either kind, by its canonical name, where the value is one" ], [ "`Type`", "No", "enum", "`string`, `number`, `boolean`, `date`, `timestamp`, `duration`, `version`, `hash`, `path`, `id`, `URL`, `file`, `language` or `map`. A plain type, where the value is no term; its unit, or what it is of, goes in the Description." ], [ "`Many`", "No", "enum", "`yes`. The value is a list of what `Term` or `Type` names; blank for one." ], [ "`Description`", "No", "string", "What the value says" ] ] }, { "caption": "`## References` is a table with these columns:", "columns": [ "Column", "Required", "Type", "Description" ], "rows": [ [ "`What`", "Yes", "string", "The kind of document — a message schema, an event catalog" ], [ "`URL`", "Yes", "string", "Where it is" ] ] } ], "table": { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Domain Event]`", "Yes", "What happened, in the past tense: \"Invoice issued\"" ], [ "`> [What happened]`", "Yes", "The event in business words, in one sentence" ], [ "`## Payload`", "No", "Table. What the event carries; its columns are declared below." ], [ "`## References`", "No", "Table. What a reader can open to learn more about the event; its columns are declared below." ] ] } }, { "heading": "Purpose", "text": "A domain event answers \"what happened that other parts of the domain care about?\" It is Evans's and Vernon's domain event, named in the past tense. It is a type and not a row of its aggregate because other contexts consume it and feature designs name it, and a row cannot be named from outside its page. A payload value names a term of the event's own context in `Term`, of either kind, or a plain type in `Type`, exactly one of the two, and a consumer translates a term into its own language.", "tables": [] }, { "heading": "Writing rules", "text": "- The H1 is in the past tense and says what happened, not what should happen next.\n- `source`, on a page drawn from code, names that code, the repository a sync reads, and the module or package is its `source-id`; a page written here that code then follows names the code in `## References` as `Implementation`.", "tables": [] }, { "heading": "File Location", "text": "`model/bounded-contexts//domain-events/*.md`", "tables": [] } ], "owner": null, "path": "packs/software/domain-event-schema.md" }, { "id": "01a0f94d-fada-7269-85c8-f21efe8fb99f", "address": "software/feature-design", "type": "software", "name": "Feature Design Schema", "tagline": "Required structure for feature design files.", "fields": {}, "sections": [ { "heading": "Frontmatter", "text": "", "tables": [ { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`refines`", "No", "ref → feature", "The feature this design builds, the H1 of a file in `features/`; more than one design may refine one feature" ], [ "`contexts`", "Yes", "array of ref → bounded-context", "The contexts the design takes part in, at least one" ], [ "`decisions`", "No", "array of ref → decision", "The decisions that shaped this design, the H1s of files in `decisions/`" ] ] } ], "table": { "caption": null, "columns": [ "Field", "Required", "Type", "Description" ], "rows": [ [ "`id`", "Yes", "string", "What identifies this entity for as long as it exists, in the format `model/identifier.md` declares (R18)" ], [ "`source`", "Yes", "ref → source", "Where this page's facts are mastered — the H1 of a file in `sources/`" ], [ "`source-id`", "No", "string", "The identifier this page has in its source — a directory id, a record key. Absent when the source has none, as a repository does not." ], [ "`refines`", "No", "ref → feature", "The feature this design builds, the H1 of a file in `features/`; more than one design may refine one feature" ], [ "`contexts`", "Yes", "array of ref → bounded-context", "The contexts the design takes part in, at least one" ], [ "`decisions`", "No", "array of ref → decision", "The decisions that shaped this design, the H1s of files in `decisions/`" ] ] } }, { "heading": "Sections", "text": "", "tables": [ { "caption": null, "columns": [ "Section", "Required", "Description" ], "rows": [ [ "`# [Feature Design]`", "Yes", "The design's name" ], [ "`> [What it delivers]`", "Yes", "What the design delivers, in one sentence" ], [ "`## Operational principle`", "Yes", "The one scenario that shows why the design exists (Jackson, The Essence of Software)" ], [ "`## Scenarios`", "No", "One `###` per scenario, headed `