@okfit/profiles 0.4.0 → 0.6.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, action, test harness, or config dependency. Link to the Decisions that shaped it and the Conventions it is bound by."
+guidance = "One per workspace package, plugin, website, action, worker, 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,6 +29,7 @@ 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.worker = "A detached runtime unit, such as a sidecar or worker bundle, spawned by another module with its own lifecycle and not itself a package or 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."
 
@@ -110,12 +111,55 @@ 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."
+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, or omit resource and name the outside system when nothing in this repository produces it. Give it a staleness window, since a trap fixed upstream turns into misinformation; a known bug nobody is scheduled to fix is a Gotcha, and becomes a Roadmap once the fix is planned."
 
 [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; a known bug with nobody queued to fix it is a Gotcha, not a Roadmap."
+
+[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"
+
+[types.Invariant]
+description = "A property the code holds by construction: enforced by the type system or pinned by a test, not followed by people."
+guidance = "State the property, name the mechanism that enforces it, and say what a refactor would have to break for it to stop holding. Distinct from Convention, which a contributor can choose to ignore."
+
+[types.Invariant.fields.resource]
+description = "A path relative to this concept file to the type, function, or test that enforces the property."
+kind = "path"
+
+[types.Incident]
+description = "A dated production failure: what shipped broken, what it looked like to the consumer, the root cause, and the guard that now stops it."
+guidance = "Keep the whole narrative in one record rather than splitting the misleading signal into a Gotcha and the guard into a Decision, and link both where they exist. Set occurred to the date it happened so a reader can weigh how far the code has moved since."
+required = ["occurred"]
+
+[types.Incident.fields.occurred]
+description = "The ISO 8601 date the failure happened or was first observed."
+
+[types.Incident.fields.guard]
+description = "A path relative to this concept file to the test, check, or config that now stops the failure recurring."
+kind = "path"
+
 [tags.architecture]
 description = "Concerns the shape of the system rather than one module."
 
@@ -139,6 +183,21 @@ description = "Concerns the unattended path: what runs without a human present,
 
 [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."
+
+[tags.github]
+description = "Concerns the GitHub platform surface: the REST and GraphQL APIs, Apps and installation tokens, Actions, Packages, check runs, and pull request conventions."
+
+[tags.docs]
+description = "Concerns the documentation itself: provenance, rot, re-derivation, and what a claim would take to falsify."
 ```
 
 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).
@@ -166,6 +225,9 @@ directories:
   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, action, test harness, or config dependency. Link to the Decisions that shaped it and the Conventions it is bound by.",
+			guidance: "One per workspace package, plugin, website, action, worker, test harness, or config dependency. Link to the Decisions that shaped it and the Conventions it is bound by.",
 			required: ["resource", "kind"],
 			fields: {
 				kind: {
@@ -33,6 +33,7 @@ const config = {
 						website: "A docs or marketing site, usually RSPress.",
 						plugin: "A Claude Code or editor plugin distributed outside npm.",
 						action: "A GitHub Action.",
+						worker: "A detached runtime unit, such as a sidecar or worker bundle, spawned by another module with its own lifecycle and not itself a package or 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."
 					}
@@ -119,11 +120,50 @@ const config = {
 		},
 		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.",
+			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, or omit resource and name the outside system when nothing in this repository produces it. Give it a staleness window, since a trap fixed upstream turns into misinformation; a known bug nobody is scheduled to fix is a Gotcha, and becomes a Roadmap once the fix is planned.",
 			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; a known bug with nobody queued to fix it is a Gotcha, not a Roadmap.",
+			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"
+			} }
+		},
+		Invariant: {
+			description: "A property the code holds by construction: enforced by the type system or pinned by a test, not followed by people.",
+			guidance: "State the property, name the mechanism that enforces it, and say what a refactor would have to break for it to stop holding. Distinct from Convention, which a contributor can choose to ignore.",
+			fields: { resource: {
+				description: "A path relative to this concept file to the type, function, or test that enforces the property.",
+				kind: "path"
+			} }
+		},
+		Incident: {
+			description: "A dated production failure: what shipped broken, what it looked like to the consumer, the root cause, and the guard that now stops it.",
+			guidance: "Keep the whole narrative in one record rather than splitting the misleading signal into a Gotcha and the guard into a Decision, and link both where they exist. Set occurred to the date it happened so a reader can weigh how far the code has moved since.",
+			required: ["occurred"],
+			fields: {
+				occurred: { description: "The ISO 8601 date the failure happened or was first observed." },
+				guard: {
+					description: "A path relative to this concept file to the test, check, or config that now stops the failure recurring.",
+					kind: "path"
+				}
+			}
 		}
 	},
 	tags: {
@@ -134,7 +174,12 @@ const config = {
 		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." }
+		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." },
+		github: { description: "Concerns the GitHub platform surface: the REST and GraphQL APIs, Apps and installation tokens, Actions, Packages, check runs, and pull request conventions." },
+		docs: { description: "Concerns the documentation itself: provenance, rot, re-derivation, and what a claim would take to falsify." }
 	},
 	extensions: {}
 };
@@ -185,6 +230,26 @@ const layout = {
 		{
 			directory: "gotchas",
 			type: "Gotcha"
+		},
+		{
+			directory: "consumers",
+			type: "Consumer"
+		},
+		{
+			directory: "roadmaps",
+			type: "Roadmap"
+		},
+		{
+			directory: "measurements",
+			type: "Measurement"
+		},
+		{
+			directory: "invariants",
+			type: "Invariant"
+		},
+		{
+			directory: "incidents",
+			type: "Incident"
 		}
 	]
 };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/profiles",
-	"version": "0.4.0",
+	"version": "0.6.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.4.0",
+		"@okfit/core": "^0.4.1",
 		"effect": "4.0.0-rc.115"
 	},
 	"engines": {