@okfit/profiles 0.3.1 → 0.5.0

package/Derivation.js

@@ -50,10 +50,23 @@ const localPartOf = (email) => {
 	const local = at === -1 ? email : email.slice(0, at);
 	return local.length > 0 && !/\s/.test(local) ? local : void 0;
 };
+/**
+* `value` without leading and trailing `-`. An index walk rather than
+* `/^-+|-+$/`: the `-+$` alternative backtracks from every position of a
+* long dash run (CodeQL js/polynomial-redos, okfit alert #1), and the input
+* here is a git author name nobody vetted.
+*/
+const trimDashes = (value) => {
+	let start = 0;
+	let end = value.length;
+	while (start < end && value.charCodeAt(start) === 45) start++;
+	while (end > start && value.charCodeAt(end - 1) === 45) end--;
+	return value.slice(start, end);
+};
 /** P-13 step 3: lower-case, runs outside `[a-z0-9._-]` to `-`, leading and trailing `-` trimmed. */
 const slugOf = (name) => {
 	if (name === void 0) return void 0;
-	const slug = name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "");
+	const slug = trimDashes(name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-"));
 	return slug.length > 0 ? slug : void 0;
 };
 const humanActorId = (identity, humans) => {

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,66 @@ 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"
+
+[types.Consumer]
+description = "An external application that consumes this repository and thereby scopes it."
+guidance = "Name the surfaces it exercises, where the edge between the two repositories sits, and the open questions it raises, so the boundary of this repository is read from its consumers rather than inferred. Deprecate it when the consumer stops consuming."
+required = ["repository"]
+
+[types.Consumer.fields.repository]
+description = "Where the consumer lives, as a URL or an owner/name pair, since it is outside this repository."
+
+[types.Roadmap]
+description = "A gate and the forward-looking work behind it, held as intent rather than as a Decision."
+guidance = "List the phases and what remains in each, and give it a staleness window so queued work is re-examined instead of read as settled. Deprecate it when the gate holds and write the Decisions the work produced."
+
+[types.Roadmap.fields.gate]
+description = "The observable condition that closes this roadmap, for example a release shipped or a benchmark met."
+
+[types.Measurement]
+description = "A dated empirical result: what was measured, how, and what the numbers ruled in or out."
+guidance = "Record the inputs, the method, and the numbers so a reader can judge whether they still hold, and give it a staleness window because numbers rot. A Decision links to the Measurement that justified it instead of embedding the result in its body."
+
+[types.Measurement.fields.justifies]
+description = "Paths to the Decisions this measurement supports, one entry per Decision."
+kind = "path"
+
 [tags.architecture]
 description = "Concerns the shape of the system rather than one module."
 
@@ -83,6 +153,24 @@ 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."
+
+[tags.bundle]
+description = "Concerns install weight and reachability: tree-shaking, subpath entrypoints, and dependency edges declined for their cost."
+
+[tags.observability]
+description = "Concerns how the system reports on itself: events, metrics, logs, sinks, and artifacts."
+
+[tags.deps]
+description = "Concerns how third-party dependencies are declared, pinned, and distributed."
 ```
 
 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 +193,14 @@ directories:
   conventions/   -> Convention
   interfaces/    -> Interface
   references/    -> Reference
+  runbooks/      -> Runbook
+  glossary/      -> Glossary
+  limitations/   -> Limitation
+  models/        -> DataModel
+  gotchas/       -> Gotcha
+  consumers/     -> Consumer
+  roadmaps/      -> Roadmap
+  measurements/  -> Measurement
 ```
 
 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,62 @@ 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"
+			} }
+		},
+		Consumer: {
+			description: "An external application that consumes this repository and thereby scopes it.",
+			guidance: "Name the surfaces it exercises, where the edge between the two repositories sits, and the open questions it raises, so the boundary of this repository is read from its consumers rather than inferred. Deprecate it when the consumer stops consuming.",
+			required: ["repository"],
+			fields: { repository: { description: "Where the consumer lives, as a URL or an owner/name pair, since it is outside this repository." } }
+		},
+		Roadmap: {
+			description: "A gate and the forward-looking work behind it, held as intent rather than as a Decision.",
+			guidance: "List the phases and what remains in each, and give it a staleness window so queued work is re-examined instead of read as settled. Deprecate it when the gate holds and write the Decisions the work produced.",
+			fields: { gate: { description: "The observable condition that closes this roadmap, for example a release shipped or a benchmark met." } }
+		},
+		Measurement: {
+			description: "A dated empirical result: what was measured, how, and what the numbers ruled in or out.",
+			guidance: "Record the inputs, the method, and the numbers so a reader can judge whether they still hold, and give it a staleness window because numbers rot. A Decision links to the Measurement that justified it instead of embedding the result in its body.",
+			fields: { justifies: {
+				description: "Paths to the Decisions this measurement supports, one entry per Decision.",
+				kind: "path"
+			} }
 		}
 	},
 	tags: {
@@ -86,7 +150,13 @@ 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." },
+		bundle: { description: "Concerns install weight and reachability: tree-shaking, subpath entrypoints, and dependency edges declined for their cost." },
+		observability: { description: "Concerns how the system reports on itself: events, metrics, logs, sinks, and artifacts." },
+		deps: { description: "Concerns how third-party dependencies are declared, pinned, and distributed." }
 	},
 	extensions: {}
 };
@@ -117,6 +187,38 @@ 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"
+		},
+		{
+			directory: "consumers",
+			type: "Consumer"
+		},
+		{
+			directory: "roadmaps",
+			type: "Roadmap"
+		},
+		{
+			directory: "measurements",
+			type: "Measurement"
 		}
 	]
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/profiles",
-	"version": "0.3.1",
+	"version": "0.5.0",
 	"private": false,
 	"description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
 	"keywords": [
@@ -37,7 +37,7 @@
 	"peerDependencies": {
 		"@effected/git": "^0.15.0",
 		"@effected/markdown": "^0.10.0",
-		"@okfit/core": "^0.3.1",
+		"@okfit/core": "^0.4.1",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {