@okfit/profiles 0.3.0 → 0.4.0

package/README.md

@@ -19,7 +19,7 @@ guidance = "Exactly one Project exists and it lives at the bundle root as the pr
 
 [types.Module]
 description = "A unit of code with an owner and a boundary."
-guidance = "One per workspace package, plugin, website, or action. Link to the Decisions that shaped it and the Conventions it is bound by."
+guidance = "One per workspace package, plugin, website, action, test harness, or config dependency. Link to the Decisions that shaped it and the Conventions it is bound by."
 required = ["resource", "kind"]
 
 [types.Module.fields.kind]
@@ -29,11 +29,20 @@ values.package = "A publishable npm package under packages/."
 values.website = "A docs or marketing site, usually RSPress."
 values.plugin = "A Claude Code or editor plugin distributed outside npm."
 values.action = "A GitHub Action."
+values.harness = "A private test-only package or package group that exercises built artifacts and is never published."
+values.config-dependency = "A package consumed through pnpm configDependencies rather than dependencies, loaded before the workspace resolves."
 
 [types.Module.fields.resource]
 description = "A path relative to this concept file, normally escaping the bundle, for example ../../packages/core."
 kind = "path"
 
+[types.Module.fields.layer]
+description = "The dependency layer this module sits in under the repository's own layering scheme, for example L2, so a reader can query every module at one layer."
+
+[types.Module.fields.pins]
+description = "Paths to the sibling Module concepts this module is exact-version-pinned alongside, one entry per sibling."
+kind = "path"
+
 [types.Decision]
 description = "A choice made, the alternatives rejected, and why."
 guidance = "Never edit a stable Decision; deprecate it and write a new one that names it in supersedes. A Decision counts as settled only once a human has verified it."
@@ -59,6 +68,7 @@ values.cli = "A command-line interface: commands, flags, and exit codes."
 values.config = "A configuration file schema other tools read or write."
 values.wire = "A network or IPC wire format."
 values.mcp = "An MCP tool or resource surface."
+values.runtime = "A runtime binding or platform capability consumers invoke rather than a shape they write: worker bindings, environment contracts, platform flags."
 
 [types.Interface.fields.resource]
 description = "A path relative to this concept file, normally escaping the bundle, for example ../../packages/core/src/index.ts."
@@ -69,6 +79,43 @@ description = "Mirrored external material kept under the references directory."
 guidance = "Only for material this repository must cite reliably even if the original moves. Every Reference declares where it came from in sources."
 required = ["sources"]
 
+[types.Runbook]
+description = "A repeatable operational procedure with a trigger and an observable end state."
+guidance = "Write the steps in the order they are performed, not as rules. Name the trigger that starts the procedure and the observable state that means it succeeded."
+
+[types.Runbook.fields.resource]
+description = "A path relative to this concept file to the script, workflow, or config the procedure runs through, when one exists in this repository."
+kind = "path"
+
+[types.Glossary]
+description = "A term this repository uses in its own sense, one term per concept."
+guidance = "Define the term as this repository means it, not as the wider ecosystem means it, and say plainly where the two differ. A term earns a concept on a collision or a trap; one that merely names a Module belongs in that Module."
+
+[types.Limitation]
+description = "A known edge of a contract: something that does not work, and why that is acceptable."
+guidance = "State the condition that triggers it and the observable symptom, not just the cause, and name the Interface or Module whose promise it bounds. If it is fixable and merely unfixed, say what the fix would take."
+
+[types.Limitation.fields.bounds]
+description = "The Interface or Module concept whose promise this limitation bounds."
+kind = "path"
+
+[types.DataModel]
+description = "An internal source-of-truth structure that other artifacts are derived from."
+guidance = "Document the shape from the maintainer's side: what an entry contains, what is derived from it, and what breaks if an entry is wrong. Distinct from Interface, which documents a promise to consumers."
+required = ["resource"]
+
+[types.DataModel.fields.resource]
+description = "A path relative to this concept file, normally escaping the bundle, to the file or directory that holds the structure."
+kind = "path"
+
+[types.Gotcha]
+description = "A state or result that looks like one thing and is the opposite: breakage that is transient, or success that did nothing."
+guidance = "Describe what a reader sees, what they will wrongly conclude, and what is actually true, and point resource at the code or command that produces the misleading signal. Give it a staleness window, since a trap fixed upstream turns into misinformation."
+
+[types.Gotcha.fields.resource]
+description = "A path relative to this concept file to the code, script, or config that produces the misleading signal."
+kind = "path"
+
 [tags.architecture]
 description = "Concerns the shape of the system rather than one module."
 
@@ -83,6 +130,15 @@ description = "Concerns trust boundaries, secrets, permissions, or attack surfac
 
 [tags.performance]
 description = "Concerns speed, memory, or resource cost and the trade-offs made for them."
+
+[tags.dx]
+description = "Concerns the experience of the people and agents who author, build, and debug the code."
+
+[tags.ci]
+description = "Concerns the unattended path: what runs without a human present, and how it fails."
+
+[tags.compat]
+description = "Concerns compatibility across versions of the runtime, the package manager, or a dependency."
 ```
 
 Only `concepts`, `types`, and `tags` carry real vocabulary; the literal's `extensions: {}` is `OkfitConfig`'s one required key and never appears on disk, since the codec folds unknown top-level keys into it (P-24: `fields.<k>.kind = "path"` and the `tags` table are vocabulary only — core enforces none of it yet). `Reference.required = ["sources"]` checks presence only: `sources = []` passes, and each entry's shape is core's `family-invalid` (P-23).
@@ -105,6 +161,11 @@ directories:
   conventions/   -> Convention
   interfaces/    -> Interface
   references/    -> Reference
+  runbooks/      -> Runbook
+  glossary/      -> Glossary
+  limitations/   -> Limitation
+  models/        -> DataModel
+  gotchas/       -> Gotcha
 ```
 
 Each directory carries its own `index.md`. What `okfit init` writes into these files is the CLI plan's concern, not this package's.

package/SoftwareProject.js

@@ -22,7 +22,7 @@ const config = {
 		},
 		Module: {
 			description: "A unit of code with an owner and a boundary.",
-			guidance: "One per workspace package, plugin, website, or action. Link to the Decisions that shaped it and the Conventions it is bound by.",
+			guidance: "One per workspace package, plugin, website, action, test harness, or config dependency. Link to the Decisions that shaped it and the Conventions it is bound by.",
 			required: ["resource", "kind"],
 			fields: {
 				kind: {
@@ -32,12 +32,19 @@ const config = {
 						package: "A publishable npm package under packages/.",
 						website: "A docs or marketing site, usually RSPress.",
 						plugin: "A Claude Code or editor plugin distributed outside npm.",
-						action: "A GitHub Action."
+						action: "A GitHub Action.",
+						harness: "A private test-only package or package group that exercises built artifacts and is never published.",
+						"config-dependency": "A package consumed through pnpm configDependencies rather than dependencies, loaded before the workspace resolves."
 					}
 				},
 				resource: {
 					description: "A path relative to this concept file, normally escaping the bundle, for example ../../packages/core.",
 					kind: "path"
+				},
+				layer: { description: "The dependency layer this module sits in under the repository's own layering scheme, for example L2, so a reader can query every module at one layer." },
+				pins: {
+					description: "Paths to the sibling Module concepts this module is exact-version-pinned alongside, one entry per sibling.",
+					kind: "path"
 				}
 			}
 		},
@@ -66,7 +73,8 @@ const config = {
 						cli: "A command-line interface: commands, flags, and exit codes.",
 						config: "A configuration file schema other tools read or write.",
 						wire: "A network or IPC wire format.",
-						mcp: "An MCP tool or resource surface."
+						mcp: "An MCP tool or resource surface.",
+						runtime: "A runtime binding or platform capability consumers invoke rather than a shape they write: worker bindings, environment contracts, platform flags."
 					}
 				},
 				resource: {
@@ -79,6 +87,43 @@ const config = {
 			description: "Mirrored external material kept under the references directory.",
 			guidance: "Only for material this repository must cite reliably even if the original moves. Every Reference declares where it came from in sources.",
 			required: ["sources"]
+		},
+		Runbook: {
+			description: "A repeatable operational procedure with a trigger and an observable end state.",
+			guidance: "Write the steps in the order they are performed, not as rules. Name the trigger that starts the procedure and the observable state that means it succeeded.",
+			fields: { resource: {
+				description: "A path relative to this concept file to the script, workflow, or config the procedure runs through, when one exists in this repository.",
+				kind: "path"
+			} }
+		},
+		Glossary: {
+			description: "A term this repository uses in its own sense, one term per concept.",
+			guidance: "Define the term as this repository means it, not as the wider ecosystem means it, and say plainly where the two differ. A term earns a concept on a collision or a trap; one that merely names a Module belongs in that Module."
+		},
+		Limitation: {
+			description: "A known edge of a contract: something that does not work, and why that is acceptable.",
+			guidance: "State the condition that triggers it and the observable symptom, not just the cause, and name the Interface or Module whose promise it bounds. If it is fixable and merely unfixed, say what the fix would take.",
+			fields: { bounds: {
+				description: "The Interface or Module concept whose promise this limitation bounds.",
+				kind: "path"
+			} }
+		},
+		DataModel: {
+			description: "An internal source-of-truth structure that other artifacts are derived from.",
+			guidance: "Document the shape from the maintainer's side: what an entry contains, what is derived from it, and what breaks if an entry is wrong. Distinct from Interface, which documents a promise to consumers.",
+			required: ["resource"],
+			fields: { resource: {
+				description: "A path relative to this concept file, normally escaping the bundle, to the file or directory that holds the structure.",
+				kind: "path"
+			} }
+		},
+		Gotcha: {
+			description: "A state or result that looks like one thing and is the opposite: breakage that is transient, or success that did nothing.",
+			guidance: "Describe what a reader sees, what they will wrongly conclude, and what is actually true, and point resource at the code or command that produces the misleading signal. Give it a staleness window, since a trap fixed upstream turns into misinformation.",
+			fields: { resource: {
+				description: "A path relative to this concept file to the code, script, or config that produces the misleading signal.",
+				kind: "path"
+			} }
 		}
 	},
 	tags: {
@@ -86,7 +131,10 @@ const config = {
 		testing: { description: "Concerns how the system is verified: strategy, fixtures, and coverage policy." },
 		release: { description: "Concerns how changes ship: versioning, changelogs, publishing, and tagging." },
 		security: { description: "Concerns trust boundaries, secrets, permissions, or attack surface." },
-		performance: { description: "Concerns speed, memory, or resource cost and the trade-offs made for them." }
+		performance: { description: "Concerns speed, memory, or resource cost and the trade-offs made for them." },
+		dx: { description: "Concerns the experience of the people and agents who author, build, and debug the code." },
+		ci: { description: "Concerns the unattended path: what runs without a human present, and how it fails." },
+		compat: { description: "Concerns compatibility across versions of the runtime, the package manager, or a dependency." }
 	},
 	extensions: {}
 };
@@ -117,6 +165,26 @@ const layout = {
 		{
 			directory: "references",
 			type: "Reference"
+		},
+		{
+			directory: "runbooks",
+			type: "Runbook"
+		},
+		{
+			directory: "glossary",
+			type: "Glossary"
+		},
+		{
+			directory: "limitations",
+			type: "Limitation"
+		},
+		{
+			directory: "models",
+			type: "DataModel"
+		},
+		{
+			directory: "gotchas",
+			type: "Gotcha"
 		}
 	]
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/profiles",
-	"version": "0.3.0",
+	"version": "0.4.0",
 	"private": false,
 	"description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
 	"keywords": [
@@ -35,10 +35,10 @@
 		"./package.json": "./package.json"
 	},
 	"peerDependencies": {
-		"@effected/git": "^0.12.0",
-		"@effected/markdown": "^0.9.0",
-		"@okfit/core": "^0.3.0",
-		"effect": "4.0.0-rc.112"
+		"@effected/git": "^0.15.0",
+		"@effected/markdown": "^0.10.0",
+		"@okfit/core": "^0.4.0",
+		"effect": "4.0.0-rc.115"
 	},
 	"engines": {
 		"node": ">=24.11.0"

package/tsdoc-metadata.json

@@ -5,7 +5,7 @@
   "toolPackages": [
     {
       "packageName": "@microsoft/api-extractor",
-      "packageVersion": "7.59.0"
+      "packageVersion": "7.59.1"
     }
   ]
 }