@okfit/profiles 0.5.0 → 0.7.0

package/README.md

@@ -6,20 +6,23 @@ Named configuration profiles for [okfit](https://github.com/spencerbeggs/okfit).
 
 ## The `software-project` profile
 
-`Profiles.softwareProject.config` is a hand-authored `OkfitConfig` (P-25) that sets only `concepts`, `types`, `tags`, and `extensions: {}`; `okf_version`, `bundle`, `lifecycle`, `actors`, and `lint` are inherited from `OkfitConfig.DEFAULTS` by whoever merges it (the CLI applies `DEFAULTS < profile < file` with `OkfitConfig.merge`). `Profiles.get(name)` resolves a profile by its exact name and answers `Option.none` for `"none"` and unknown names. The TOML below decodes to the exact same value and is checked against the literal by `__test__/SoftwareProject.test.ts`:
+`Profiles.softwareProject.config` is a hand-authored `OkfitConfig` (P-25) that sets only `concepts`, `types`, `tags`, `extensions: {}`, and one `lint` opinion (`status_missing = "warn"`, so a concept with neither `status` nor `verified` is reported instead of silently reading as stable); `okf_version`, `bundle`, `lifecycle`, `actors`, and every other `lint` severity are inherited from `OkfitConfig.DEFAULTS` by whoever merges it (the CLI applies `DEFAULTS < profile < file` with `OkfitConfig.merge`). `Profiles.get(name)` resolves a profile by its exact name and answers `Option.none` for `"none"` and unknown names. The TOML below decodes to the exact same value and is checked against the literal by `__test__/SoftwareProject.test.ts`:
 
 ```toml
 [concepts]
 required = ["title", "description"]
 tags.required = []
 
+[lint]
+status_missing = "warn"
+
 [types.Project]
 description = "The repository's root concept: its purpose, boundaries, and non-goals."
 guidance = "Exactly one Project exists and it lives at the bundle root as the project file. State the purpose in one paragraph and list what is deliberately out of scope so a reader never infers boundaries from silence."
 
 [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 +32,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,7 +114,7 @@ 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."
@@ -126,7 +130,7 @@ description = "Where the consumer lives, as a URL or an owner/name pair, since i
 
 [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."
+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."
@@ -139,6 +143,26 @@ guidance = "Record the inputs, the method, and the numbers so a reader can judge
 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."
 
@@ -171,6 +195,12 @@ description = "Concerns how the system reports on itself: events, metrics, logs,
 
 [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).

package/SoftwareProject.js

@@ -1,8 +1,11 @@
 //#region src/SoftwareProject.ts
 /**
 * Hand-authored, typed `OkfitConfig` (P-25). Sets ONLY `concepts`, `types`,
-* `tags` and `extensions: {}`; `okf_version`, `bundle`, `lifecycle`, `actors`
-* and `lint` are inherited from `OkfitConfig.DEFAULTS` by whoever merges.
+* `tags`, `extensions: {}` and one `lint` opinion (`status_missing = "warn"`,
+* issue #110: a software project wants every concept's status written down
+* rather than read from silence); `okf_version`, `bundle`, `lifecycle`,
+* `actors` and the rest of `lint` are inherited from `OkfitConfig.DEFAULTS`
+* by whoever merges.
 * `actors.agent` is deliberately unset (P-17): which agent writes is a fact
 * about the repository, not about the software-project shape. Every string
 * obeys P-42 (one-sentence descriptions, at most two-sentence guidance, plain
@@ -15,6 +18,7 @@ const config = {
 		required: ["title", "description"],
 		tags: { required: [] }
 	},
+	lint: { status_missing: "warn" },
 	types: {
 		Project: {
 			description: "The repository's root concept: its purpose, boundaries, and non-goals.",
@@ -22,7 +26,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 +37,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,7 +124,7 @@ 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"
@@ -133,7 +138,7 @@ const config = {
 		},
 		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.",
+			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: {
@@ -143,6 +148,26 @@ const config = {
 				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: {
@@ -156,7 +181,9 @@ const config = {
 		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." }
+		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: {}
 };
@@ -219,6 +246,14 @@ const layout = {
 		{
 			directory: "measurements",
 			type: "Measurement"
+		},
+		{
+			directory: "invariants",
+			type: "Invariant"
+		},
+		{
+			directory: "incidents",
+			type: "Incident"
 		}
 	]
 };

package/package.json

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