@okfit/profiles 0.1.0 → 0.2.0

package/BodyProvenance.js

@@ -0,0 +1,44 @@
+import { Timestamp } from "@okfit/core";
+import { Schema } from "effect";
+
+//#region src/BodyProvenance.ts
+/**
+* The body is at HEAD and last changed in the commit described here (P-9).
+* `at` is that commit's author date (P-4); `committedAt` and the author
+* identity are carried for callers that want a history-based policy later (P-40).
+* `creating` is true exactly when the winning entry is also the oldest entry
+* of the path's history — the commit that created the path (S-9).
+*
+* @public
+*/
+const BodyCommitted = Schema.TaggedStruct("committed", {
+	at: Timestamp,
+	sha: Schema.String,
+	committedAt: Timestamp,
+	authorName: Schema.String,
+	authorEmail: Schema.String,
+	creating: Schema.Boolean
+});
+/**
+* The body has no usable commit (P-9): `untracked` means HEAD does not contain
+* the path, `dirty` means the on-disk body differs from HEAD's blob, `unborn`
+* means HEAD has no commits (P-11).
+*
+* @public
+*/
+const BodyUncommitted = Schema.TaggedStruct("uncommitted", { reason: Schema.Literals([
+	"untracked",
+	"dirty",
+	"unborn"
+]) });
+/**
+* What {@link Derivation.generatedAt} reports. A schema so the value also
+* serialises for MCP later without adaptation. Derivation never substitutes
+* `now`; the uncommitted policy is the caller's (P-10).
+*
+* @public
+*/
+const BodyProvenance = Schema.Union([BodyCommitted, BodyUncommitted]);
+
+//#endregion
+export { BodyCommitted, BodyProvenance, BodyUncommitted };

package/Derivation.js

@@ -0,0 +1,190 @@
+import { GitHistory } from "./GitHistory.js";
+import { Actor, OkfitConfig } from "@okfit/core";
+import { DateTime, Duration, Effect, FileSystem, Option, Path, Schema } from "effect";
+import { Git } from "@effected/git";
+import { FrontmatterSource } from "@effected/markdown";
+
+//#region src/Derivation.ts
+/**
+* git has no identity to derive a `human:` actor from (P-13 step 4).
+* `userName` and `userEmail` are the trimmed `configGet` answers when git had
+* them and absent keys otherwise (decision 53: not `name`/`email`, since every
+* Effect error class carries the class name on its own prototype and a field
+* literally named `name` would shadow `error.name` when present); test for
+* git's answer with `Object.hasOwn(error, "userName")`.
+*
+* @public
+*/
+var HumanActorUnresolvedError = class extends Schema.TaggedError()("HumanActorUnresolvedError", {
+	userName: Schema.optionalKey(Schema.String),
+	userEmail: Schema.optionalKey(Schema.String)
+}) {
+	get message() {
+		return "git has no user.name or user.email to derive a human actor from; set one or add actors.humans";
+	}
+};
+/**
+* The writer is an agent but `actors.agent` is not configured (P-17); the
+* profile never sets it.
+*
+* @public
+*/
+var AgentActorUnconfiguredError = class extends Schema.TaggedError()("AgentActorUnconfiguredError", {}) {
+	get message() {
+		return "writer is agent but actors.agent is not configured";
+	}
+};
+const HUMAN_PREFIX = "human:";
+const FALLBACK_STALE_AFTER = Duration.days(90);
+const decodeActor = Schema.decodeSync(Actor);
+const normalise = (text) => text.replace(/\r\n?/g, "\n").trimEnd();
+const body = (text) => normalise(FrontmatterSource.split(text).body);
+/** The text before the first `@` (the whole value when there is none), or undefined when empty or containing whitespace. */
+const localPartOf = (email) => {
+	if (email === void 0) return void 0;
+	const at = email.indexOf("@");
+	const local = at === -1 ? email : email.slice(0, at);
+	return local.length > 0 && !/\s/.test(local) ? local : void 0;
+};
+/** 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, "");
+	return slug.length > 0 ? slug : void 0;
+};
+const humanActorId = (identity, humans) => {
+	const local = localPartOf(identity.email);
+	const slug = slugOf(identity.name);
+	const candidates = [local, slug].filter((candidate) => candidate !== void 0).map((candidate) => candidate.toLowerCase());
+	for (const entry of humans) {
+		if (!entry.startsWith(HUMAN_PREFIX)) continue;
+		if (candidates.includes(entry.slice(6).toLowerCase())) return Option.some(entry);
+	}
+	if (local !== void 0) return Option.some(decodeActor(`${HUMAN_PREFIX}${local}`));
+	if (slug !== void 0) return Option.some(decodeActor(`${HUMAN_PREFIX}${slug}`));
+	return Option.none();
+};
+const staleAfter = (from, config) => DateTime.addDuration(from, config.lifecycle?.default_stale_after ?? OkfitConfig.DEFAULTS.lifecycle?.default_stale_after ?? FALLBACK_STALE_AFTER);
+const committed = (entry, entries) => ({
+	_tag: "committed",
+	at: entry.authoredAt,
+	sha: entry.sha,
+	committedAt: entry.committedAt,
+	authorName: entry.authorName,
+	authorEmail: entry.authorEmail,
+	creating: entry === entries[entries.length - 1]
+});
+const uncommitted = (reason) => ({
+	_tag: "uncommitted",
+	reason
+});
+/**
+* Spec 5.4 derivation rules for the `software-project` profile, package-global
+* (P-38). Pure members take every input as an argument; effectful members
+* require `Git`, `GitHistory` and, for the worktree read, `FileSystem` and
+* `Path` (P-30). Never writes, never reads `generated.by` (P-40).
+*
+* @public
+*/
+var Derivation = class {
+	constructor() {}
+	/**
+	* `FrontmatterSource.split(text).body`, then CRLF and lone CR to LF, then trailing whitespace at end of
+	* text removed (P-6). Pure. Applied to both sides of every comparison so `core.autocrlf` worktrees compare clean.
+	*/
+	static body = body;
+	/**
+	* Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
+	*  1. `root = Git.repoRoot(dirname(file))`: a file outside any repository surfaces `NotARepositoryError`;
+	*     submodules and worktrees work because the question is asked from the file's directory (P-39).
+	*  2. `realPath` both (rev-parse is symlink-resolved), then the repo-relative posix path via `Path` (P-39).
+	*  3. `worktree = body(readFileString(file))`.
+	*  4. `Git.show(realRoot, "HEAD", rel)`: `UnknownRefError` is `uncommitted { unborn }` (P-11), `Option.none`
+	*     is `uncommitted { untracked }` (P-47), a body differing from `worktree` is `uncommitted { dirty }` (P-9).
+	*     The comparison is against HEAD's blob, never the newest log entry (P-46).
+	*  5. `entries = GitHistory.pathLog(realRoot, rel)` newest first (P-5, P-46); `[]` is `uncommitted { unborn }`.
+	*  6. One `Git.show` per older blob (P-8), newest first: the first entry whose body differs from the next
+	*     older entry's body wins, else the oldest entry (the creating commit). "Previous" is the previous entry
+	*     of the simplified `--follow` history, not the true parent (P-7). The newest entry's body is never
+	*     re-fetched: `head.blob`, already confirmed equal to `worktree` by step 4, is reused (decision 56).
+	*     `Option.none` for an older entry counts as "differs", never a defect (decision 56).
+	* `config` is reserved and ignored (P-48). Never writes, never reads `by` (P-40).
+	*/
+	static generatedAt = Effect.fn("Derivation.generatedAt")(function* (options) {
+		const git = yield* Git;
+		const history = yield* GitHistory;
+		const fs = yield* FileSystem.FileSystem;
+		const path = yield* Path.Path;
+		const root = yield* git.repoRoot(path.dirname(options.file));
+		const realRoot = yield* fs.realPath(root);
+		const realFile = yield* fs.realPath(options.file);
+		const rel = path.relative(realRoot, realFile).split(path.sep).join("/");
+		const worktree = body(yield* fs.readFileString(options.file));
+		const head = yield* git.show(realRoot, "HEAD", rel).pipe(Effect.map((blob) => ({
+			unborn: false,
+			blob
+		})), Effect.catchTag("UnknownRefError", () => Effect.succeed({
+			unborn: true,
+			blob: Option.none()
+		})));
+		if (head.unborn) return uncommitted("unborn");
+		if (Option.isNone(head.blob)) return uncommitted("untracked");
+		if (body(head.blob.value) !== worktree) return uncommitted("dirty");
+		const entries = yield* history.pathLog(realRoot, rel);
+		const newest = entries[0];
+		if (newest === void 0) return uncommitted("unborn");
+		let current = worktree;
+		for (let index = 0; index < entries.length - 1; index += 1) {
+			const entry = entries[index];
+			const older = entries[index + 1];
+			if (entry === void 0 || older === void 0) break;
+			const olderBlob = yield* git.show(realRoot, older.sha, older.path);
+			if (Option.isNone(olderBlob)) return committed(entry, entries);
+			const olderBody = body(olderBlob.value);
+			if (olderBody !== current) return committed(entry, entries);
+			current = olderBody;
+		}
+		return committed(entries[entries.length - 1] ?? newest, entries);
+	});
+	/**
+	* P-13 / P-14, pure. Candidates: the email local part (returned as written, lower-cased only for matching)
+	* and the `user.name` slug. Order, first hit wins: (1) a `human:` entry of `humans` whose id equals a
+	* candidate case-insensitively, returned verbatim; (2) `human:<local>`; (3) `human:<slug>`; (4) none.
+	* The result is branded through core's `Actor` codec and always passes it.
+	*/
+	static humanActorId = humanActorId;
+	/**
+	* Spec 5.4 rule 1 (P-16, P-45). `"agent"`: `config.actors.agent`, else {@link AgentActorUnconfiguredError}
+	* (P-17). `"human"`: `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` in merged
+	* scope (P-15) through {@link Derivation.humanActorId}; none is {@link HumanActorUnresolvedError}.
+	* Answers only "who is writing now" (P-40).
+	*/
+	static generatedBy = Effect.fn("Derivation.generatedBy")(function* (options) {
+		if (options.writer === "agent") {
+			const agent = options.config.actors?.agent;
+			if (agent === void 0) return yield* new AgentActorUnconfiguredError({});
+			return agent;
+		}
+		const git = yield* Git;
+		const name = Option.getOrUndefined(yield* git.configGet(options.cwd, "user.name"));
+		const email = Option.getOrUndefined(yield* git.configGet(options.cwd, "user.email"));
+		const identity = {
+			...name === void 0 ? {} : { name },
+			...email === void 0 ? {} : { email }
+		};
+		const resolved = humanActorId(identity, options.config.actors?.humans ?? []);
+		if (Option.isNone(resolved)) return yield* new HumanActorUnresolvedError({
+			...identity.name === void 0 ? {} : { userName: identity.name },
+			...identity.email === void 0 ? {} : { userEmail: identity.email }
+		});
+		return resolved.value;
+	});
+	/**
+	* P-19, pure: `from` plus `config.lifecycle.default_stale_after`, falling back to `OkfitConfig.DEFAULTS`'
+	* 90 days. `from` is the caller's: `generated.at` when committed, else its own `now`.
+	*/
+	static staleAfter = staleAfter;
+};
+
+//#endregion
+export { AgentActorUnconfiguredError, Derivation, HumanActorUnresolvedError };

package/GitHistory.js

@@ -0,0 +1,107 @@
+import { Timestamp } from "@okfit/core";
+import { Context, Effect, Layer, Schema } from "effect";
+import { Git } from "@effected/git";
+
+//#region src/GitHistory.ts
+/**
+* One record of the path log, newest first (P-3, P-5): the commit, both dates decoded through core's
+* `Timestamp` (`%aI` / `%cI`, strict ISO with an offset; the `Type` is `DateTime.Utc`, P-4), the author
+* identity, and the repository-relative posix path the blob had at that commit (the `--name-only` line).
+* @public
+*/
+var PathHistoryEntry = class extends Schema.Class("PathHistoryEntry")({
+	sha: Schema.String,
+	authoredAt: Timestamp,
+	committedAt: Timestamp,
+	authorName: Schema.String,
+	authorEmail: Schema.String,
+	path: Schema.String
+}) {};
+/**
+* Profiles' own spawn failure, shaped like `@effected/git`'s `GitCommandError` (P-12). Raised by
+* `GitHistory.layer` for any `GitCommandError` `Git.log` produces, including the one `Git.log`
+* itself synthesizes when its own spawn timeout expires.
+* @public
+*/
+var GitHistoryError = class extends Schema.TaggedError()("GitHistoryError", {
+	/** The argv without the leading `git`. */
+	args: Schema.Array(Schema.String),
+	/** The working directory the command ran in. */
+	cwd: Schema.String,
+	/** git's exit code; absent when git never produced one. */
+	exitCode: Schema.optionalKey(Schema.Number),
+	/** git's stderr, captured under `LC_ALL=C`. */
+	stderr: Schema.String,
+	/** Spawn failure text, `timed out after 30s`, or `Git.log`'s own absorbed-failure detail. */
+	detail: Schema.optionalKey(Schema.String)
+}) {
+	get message() {
+		const exit = this.exitCode === void 0 ? "" : ` (exit ${this.exitCode})`;
+		return `git ${this.args.join(" ")}${exit} in ${this.cwd}: ${this.detail ?? this.stderr}`;
+	}
+};
+const toGitHistoryError = (cwd, error) => new GitHistoryError({
+	args: error.args,
+	cwd,
+	...error.exitCode === void 0 ? {} : { exitCode: error.exitCode },
+	stderr: error.stderr,
+	...error.detail === void 0 ? {} : { detail: error.detail }
+});
+const make = (git) => ({ pathLog: (cwd, path, options) => Effect.gen(function* () {
+	return (yield* git.log(cwd, {
+		paths: [path],
+		follow: true,
+		firstParentDiffMerges: true,
+		...options?.limit === void 0 ? {} : { limit: options.limit }
+	}).pipe(Effect.catchTag("GitCommandError", (error) => Effect.fail(toGitHistoryError(cwd, error))))).filter((entry) => entry.paths.length > 0).map((entry) => {
+		const [path] = entry.paths;
+		return PathHistoryEntry.make({
+			sha: entry.sha,
+			authoredAt: entry.authoredAt,
+			committedAt: entry.committedAt,
+			authorName: entry.authorName,
+			authorEmail: entry.authorEmail,
+			path: path ?? ""
+		});
+	});
+}) });
+const notScripted = (path) => Effect.die(/* @__PURE__ */ new Error(`GitHistory.makeTest: pathLog(${path}) was called but not scripted`));
+/**
+* A path-scoped, date-bearing log: `Git.log` reads the whole repository history, and this adapter scopes
+* it to one path (`--follow`, `--diff-merges=first-parent`) and decodes it into `PathHistoryEntry`.
+* Delegates to `Git.log` as of `@effected/git` 0.12.0 (P-1, spec deviation retired).
+* @public
+*/
+var GitHistory = class GitHistory extends Context.Service()("@okfit/profiles/GitHistory") {
+	/**
+	* Live layer (P-1, P-5, P-11): one `Git.log` call per `pathLog`, resolved once at construction like
+	* `Git.layer` itself, so every member's `R` is `never`. `Git.log` already degrades an unborn `HEAD` and
+	* an unmatched pathspec to the empty array and classifies `not a git repository` as `NotARepositoryError`
+	* (both pass through unchanged); every other failure becomes `GitHistoryError`, including the one
+	* `Git.log` itself produces when its own 30 s spawn timeout expires (`@effected/git`'s `GIT_TIMEOUT`
+	* ceiling, not this adapter's) — `Git.log` never lets a bare `Cause.TimeoutError` escape. The CLI
+	* provides `ChildProcessSpawner` through `NodeServices.layer` (P-30).
+	*/
+	static layer = Layer.effect(GitHistory, Effect.gen(function* () {
+		const git = yield* Git;
+		return make(git);
+	})).pipe(Layer.provide(Git.layer));
+	/**
+	* Scripted double (P-32): responses keyed by the `path` argument exactly as passed to `pathLog`. A call
+	* whose path has no entry DIES with `GitHistory.makeTest: pathLog(<path>) was called but not scripted`,
+	* mirroring `Git.makeTest`; `limit` is honoured by slicing. Models none of the live semantics.
+	*/
+	static makeTest = (script) => ({ pathLog: (_cwd, path, options) => {
+		if (!Object.hasOwn(script, path)) return notScripted(path);
+		const entries = script[path] ?? [];
+		return Effect.succeed(options?.limit === void 0 ? entries : entries.slice(0, options.limit));
+	} });
+	/**
+	* `Layer.succeed(GitHistory, GitHistory.makeTest(script))`. Mints a fresh layer per call: bind it to a
+	* `const`, since layers memoize by reference.
+	*/
+	static layerTest = (script) => Layer.succeed(GitHistory, GitHistory.makeTest(script));
+};
+
+//#endregion
+export { GitHistory, GitHistoryError, PathHistoryEntry, make };

package/Profile.js

@@ -0,0 +1,38 @@
+import { DiagnosticRange, DiagnosticSeverity } from "@okfit/core";
+import { Schema } from "effect";
+
+//#region src/Profile.ts
+/**
+* Names of the profiles this package ships (P-38).
+*
+* @public
+*/
+const PROFILE_NAMES = ["software-project"];
+/**
+* Profile-owned diagnostic codes (P-21). Core's `LintCode` is untouched; all
+* three are severity `error` and are not configurable.
+*
+* @public
+*/
+const ProfileDiagnosticCode = Schema.Literals([
+	"project-missing",
+	"project-multiple",
+	"project-not-at-root"
+]);
+/**
+* Same fields as core's `Diagnostic` with a profile code; a `Schema.Struct`
+* per P-21/P-51. `file` is the bundle-relative posix path, `""` for the
+* bundle-level `project-missing`. `range` is never set in phase 1.
+*
+* @public
+*/
+const ProfileDiagnostic = Schema.Struct({
+	file: Schema.String,
+	range: Schema.optionalKey(DiagnosticRange),
+	code: ProfileDiagnosticCode,
+	severity: DiagnosticSeverity,
+	message: Schema.String
+});
+
+//#endregion
+export { PROFILE_NAMES, ProfileDiagnostic, ProfileDiagnosticCode };

package/Profiles.js

@@ -0,0 +1,27 @@
+import { softwareProject } from "./SoftwareProject.js";
+import { Option } from "effect";
+
+//#region src/Profiles.ts
+const REGISTRY = /* @__PURE__ */ new Map([[softwareProject.name, softwareProject]]);
+/**
+* The profile registry (P-38). No third-party registration in phase 1; the
+* `DEFAULTS < profile < file` merge is the CLI's (D-28).
+*
+* @public
+*/
+var Profiles = class {
+	constructor() {}
+	/** The `software-project` profile (spec 5). */
+	static softwareProject = softwareProject;
+	/**
+	* `Option.none` for `"none"`, unknown names and anything not in
+	* `PROFILE_NAMES`; the CLI decides what that means (P-38). Exact match only.
+	*/
+	static get = (name) => {
+		const found = REGISTRY.get(name);
+		return found === void 0 ? Option.none() : Option.some(found);
+	};
+};
+
+//#endregion
+export { Profiles };

package/Provenance.js

@@ -0,0 +1,59 @@
+import { Derivation } from "./Derivation.js";
+import { Diagnostic, OkfitConfig, Timestamp } from "@okfit/core";
+import { DateTime, Effect, Path, Schema } from "effect";
+
+//#region src/Provenance.ts
+const encodeAt = Schema.encodeSync(Timestamp);
+/**
+* A profiles-owned lint over committed provenance (S-8). NOT a `Profile`
+* member and NOT a `ProfileDiagnostic` -- it returns core `Diagnostic`s with
+* code `"generated-at-drift"`, a real `LintCode` member, so `severityFor`,
+* the `[lint]` table, the renderers, the hook, and the MCP tool treat it
+* like every other lint (S-7). `Profile.check` and `ProfileDiagnosticCode`
+* are unchanged.
+*
+* Runs `Derivation.generatedAt` per concept, skips uncommitted bodies and
+* concepts without a `generated` block, and returns `[]` the moment a
+* `NotARepositoryError` surfaces: a bundle outside git has nothing to
+* derive for any concept, so the first occurrence short-circuits the whole
+* walk, not just the concept that triggered it (S-8). Emits no `range`
+* (S-12, Judge note 7): `Diagnostic.range` is `Schema.optionalKey` and is
+* simply omitted.
+*
+* `Provenance.lint` is total over severity (S-28, amending Judge note 3):
+* when `OkfitConfig.severityFor(config, "generated-at-drift")` resolves to
+* `"off"`, it returns `[]` before any per-concept work and before any git
+* call, so it is safe to call at any severity and never needs to cast
+* `"off"` away. `validate/run.ts` (the CLI) still gates on `"off"` before
+* calling at all; the two agree by construction (both skip the walk).
+*
+* @public
+*/
+var Provenance = class {
+	constructor() {}
+	static lint = Effect.fn("Provenance.lint")(function* (bundle, config) {
+		const severity = OkfitConfig.severityFor(config, "generated-at-drift");
+		if (severity === "off") return [];
+		const path = yield* Path.Path;
+		const diagnostics = [];
+		for (const [, concept] of bundle.concepts) {
+			if (concept.frontmatter.generated === void 0) continue;
+			const file = path.join(bundle.root, concept.path);
+			const derived = yield* Derivation.generatedAt({ file }).pipe(Effect.catchTag("NotARepositoryError", () => Effect.succeed(void 0)));
+			if (derived === void 0) return [];
+			if (derived._tag === "uncommitted") continue;
+			const recorded = concept.frontmatter.generated.at;
+			if (recorded !== void 0 && DateTime.Equivalence(recorded, derived.at)) continue;
+			diagnostics.push(Diagnostic.make({
+				file: concept.path,
+				code: "generated-at-drift",
+				severity,
+				message: `generated.at is ${recorded === void 0 ? "missing" : encodeAt(recorded)}; the last body change was ${encodeAt(derived.at)} (${derived.sha.slice(0, 7)})`
+			}));
+		}
+		return diagnostics;
+	});
+};
+
+//#endregion
+export { Provenance };

package/README.md

@@ -1,12 +1,157 @@
 # @okfit/profiles
 
-Named configuration profiles for [okfit](https://github.com/spencerbeggs/okfit). A profile is a complete okfit config plus derivation rules. The first profile, `software-project`, describes a software repository's knowledge bundle.
+Named configuration profiles for [okfit](https://github.com/spencerbeggs/okfit). A profile is a complete `OkfitConfig` value plus derivation rules for `generated.at` and `generated.by`. The first profile, `software-project`, describes a software repository's knowledge bundle.
 
 > **Pre-release.** Part of the `@okfit/*` kit, in early development.
 
-## Status
+## The `software-project` profile
 
-Skeleton. The public surface is `PROFILE_NAMES` only.
+`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`:
+
+```toml
+[concepts]
+required = ["title", "description"]
+tags.required = []
+
+[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, or action. Link to the Decisions that shaped it and the Conventions it is bound by."
+required = ["resource", "kind"]
+
+[types.Module.fields.kind]
+description = "What sort of unit this is; drives which conventions apply."
+values.workspace = "The monorepo root: tooling, CI, release, shared config."
+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."
+
+[types.Module.fields.resource]
+description = "A path relative to this concept file, normally escaping the bundle, for example ../../packages/core."
+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."
+require_verified = true
+
+[types.Decision.fields.supersedes]
+description = "The Decision this one replaces."
+kind = "path"
+
+[types.Convention]
+description = "A rule contributors and agents must follow."
+guidance = "State the rule as an instruction rather than a description of current behaviour. Give it a staleness window so it is re-examined on a cadence instead of rotting silently."
+
+[types.Interface]
+description = "A contract others depend on."
+guidance = "Document the contract from the consumer's side: what stays stable, not how it is built. Point resource at the file, endpoint, or schema the promise lives in."
+required = ["kind"]
+
+[types.Interface.fields.kind]
+description = "What kind of contract this is."
+values.api = "A programmatic library surface: exported functions, classes, and types."
+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."
+
+[types.Interface.fields.resource]
+description = "A path relative to this concept file, normally escaping the bundle, for example ../../packages/core/src/index.ts."
+kind = "path"
+
+[types.Reference]
+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"]
+
+[tags.architecture]
+description = "Concerns the shape of the system rather than one module."
+
+[tags.testing]
+description = "Concerns how the system is verified: strategy, fixtures, and coverage policy."
+
+[tags.release]
+description = "Concerns how changes ship: versioning, changelogs, publishing, and tagging."
+
+[tags.security]
+description = "Concerns trust boundaries, secrets, permissions, or attack surface."
+
+[tags.performance]
+description = "Concerns speed, memory, or resource cost and the trade-offs made for them."
+```
+
+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).
+
+`Profiles.softwareProject.check(bundle)` additionally enforces, outside `OkfitConfig` entirely, that exactly one `Project` concept exists and lives at the bundle root (P-21): zero `Project`s is `project-missing`, more than one is `project-multiple` (one diagnostic per `Project` concept), and a `Project` whose path contains `/` is `project-not-at-root`. All three are severity `error` and are not configurable.
+
+## Layout
+
+`Profiles.softwareProject.layout` is scaffolding data for `okfit init`, never part of `OkfitConfig` (P-26):
+
+```text
+root:
+  index.md      -- bundle index
+  log.md        -- bundle log
+  project.md    -- the one Project concept, at the bundle root
+
+directories:
+  modules/       -> Module
+  decisions/     -> Decision
+  conventions/   -> Convention
+  interfaces/    -> Interface
+  references/    -> Reference
+```
+
+Each directory carries its own `index.md`. What `okfit init` writes into these files is the CLI plan's concern, not this package's.
+
+## Derivation
+
+`Derivation` is package-global, not per profile:
+
+- **`generated.at` is the author date, not the stamp date (P-4).** Walking a path's git history newest-first, the commit that changed the body is the one whose blob first differs from its predecessor's; that commit's *author* date (`%aI`) is `generated.at`. Its committer date, author name, and author email are carried on the result for callers that want a history-based policy later, but `generated.at` itself is never the date of a later frontmatter-only stamp.
+- **The path log is `@effected/git`'s `Git.log(cwd, { paths: [path], follow: true, firstParentDiffMerges: true })` (P-5, amended P-46, decision 56).** `firstParentDiffMerges` surfaces a conflict-resolving merge whose blob differs from both parents (probed on git 2.54.0), which plain `--follow` can omit and which would otherwise attribute that body change to the wrong commit. `Git.log`'s unconditional `-z` makes `--name-only` emit paths raw — no C-style quoting — so no `core.quotePath` override is needed and a path containing a space, a quote, or a newline round-trips verbatim. The dirty check compares the worktree body against `Git.show(root, "HEAD", path)`, never against the newest log entry. `--follow`'s rename detection can itself stop at a commit that renames a file and rewrites its content enough that git no longer treats it as a continuation of the same history; when that happens, `generated.at` answers that rename commit rather than an older one.
+- **Uncommitted is the caller's to interpret (P-10).** `Derivation.generatedAt` reports `{ _tag: "uncommitted", reason: "untracked" | "dirty" | "unborn" }` and never substitutes `now`. The recommended policy, followed by the snippet below: omit `generated.at` entirely until the body is committed.
+- **Human actor resolution (P-13).** Given git identity `{ name?, email? }` and `config.actors.humans`, the first hit wins: (1) a `human:<id>` entry whose id matches the email's local part or the name's slug, case-insensitively (config spelling returned); (2) `human:<local part>`; (3) `human:<slug of name>`; (4) unresolved. The slug lowercases `name`, replaces runs of whitespace and characters outside `[A-Za-z0-9._-]` with `-`, and trims leading and trailing `-`.
+- **Identity is read at merged config scope (P-15).** `Derivation.generatedBy` calls `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` with no `scope` option. Environment overrides (`GIT_AUTHOR_NAME`, `GIT_AUTHOR_EMAIL`, `EMAIL`, `user.useConfigOnly`) are out of scope for phase 1.
+- **`stale_after` is pure addition (P-19).** `Derivation.staleAfter(from, config)` is `from + (config.lifecycle?.default_stale_after ?? OkfitConfig.DEFAULTS.lifecycle.default_stale_after)`, falling back to 90 days. `from` should be `generated.at` when the provenance is `committed`, otherwise the caller's own `now`; re-stamp whenever `generated.at` changes.
+
+Recommended stamping policy, followed end to end:
+
+```ts
+const by = yield* Derivation.generatedBy({ writer, cwd: path.dirname(file), config }); // P-16; agent needs actors.agent (P-17)
+const provenance = yield* Derivation.generatedAt({ file, config });                    // P-2, P-9, P-39
+const at = provenance._tag === "committed" ? Option.some(provenance.at) : Option.none(); // omit `at` until committed (P-10)
+const staleAfter = Derivation.staleAfter(Option.getOrElse(at, () => now), config);       // P-19; `now` is the caller's
+// serialisation is the CLI's: Schema.encodeSync(Timestamp) writes "...T08:00:00Z" after the P-18 core patch (P-41)
+```
+
+Frontmatter serialisation, the uncommitted policy's enforcement, `now`, layer composition (`Layer.mergeAll(Git.layer, GitHistory.layer).pipe(Layer.provideMerge(NodeServices.layer))`), exit codes, and everything `okfit init` writes belong to the CLI plan, not this package (P-30, P-41, P-44).
+
+## Provenance
+
+`Provenance.lint(bundle, config)` is the `generated-at-drift` lint
+(`lint.generated_at_drift`, config default `"info"`): it walks
+`Derivation.generatedAt` once per concept with a `generated` block, and
+reports a core `Diagnostic` when a committed body's `generated.at` is
+missing or does not match the derived instant (compared as decoded
+`DateTime.Utc` values, never encoded strings). It is silent for an
+uncommitted body, for a concept with no `generated` block, and returns `[]`
+the moment it discovers the bundle is outside a git repository at all. It
+emits no `range` — the message carries both instants and a 7-character
+sha, which is what a reader acts on. It is a plain facade over
+`Derivation`, not a `Profile` member: `severityFor`, the `[lint]` table,
+the renderers, the PostToolUse hook, and the MCP `validate_bundle` tool all
+treat its `Diagnostic`s like every other lint. It is total over severity
+(S-28): when the resolved `generated-at-drift` severity is `"off"` it
+returns `[]` before any per-concept work and before any git call, so it is
+safe to call at any severity. The CLI (`okfit validate`, `okfit sync`'s own
+reporting) also gates on `"off"` before calling at all; the two agree by
+construction.
 
 ## License
 

package/SoftwareProject.js

@@ -0,0 +1,170 @@
+//#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.
+* `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
+* text). No explicit `required = []` anywhere (P-20). The literal type-checks
+* as `OkfitConfig` without a decode step because no branded `Actor` is set
+* (`CORE/OkfitConfig.ts:172`; `OkfitConfig.test.ts:102-107` precedent).
+*/
+const config = {
+	concepts: {
+		required: ["title", "description"],
+		tags: { required: [] }
+	},
+	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."
+		},
+		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.",
+			required: ["resource", "kind"],
+			fields: {
+				kind: {
+					description: "What sort of unit this is; drives which conventions apply.",
+					values: {
+						workspace: "The monorepo root: tooling, CI, release, shared 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."
+					}
+				},
+				resource: {
+					description: "A path relative to this concept file, normally escaping the bundle, for example ../../packages/core.",
+					kind: "path"
+				}
+			}
+		},
+		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.",
+			require_verified: true,
+			fields: { supersedes: {
+				description: "The Decision this one replaces.",
+				kind: "path"
+			} }
+		},
+		Convention: {
+			description: "A rule contributors and agents must follow.",
+			guidance: "State the rule as an instruction rather than a description of current behaviour. Give it a staleness window so it is re-examined on a cadence instead of rotting silently."
+		},
+		Interface: {
+			description: "A contract others depend on.",
+			guidance: "Document the contract from the consumer's side: what stays stable, not how it is built. Point resource at the file, endpoint, or schema the promise lives in.",
+			required: ["kind"],
+			fields: {
+				kind: {
+					description: "What kind of contract this is.",
+					values: {
+						api: "A programmatic library surface: exported functions, classes, and types.",
+						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."
+					}
+				},
+				resource: {
+					description: "A path relative to this concept file, normally escaping the bundle, for example ../../packages/core/src/index.ts.",
+					kind: "path"
+				}
+			}
+		},
+		Reference: {
+			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"]
+		}
+	},
+	tags: {
+		architecture: { description: "Concerns the shape of the system rather than one module." },
+		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." }
+	},
+	extensions: {}
+};
+/** Spec 5.2 as data (P-26); consumed by `okfit init`, never by validation. */
+const layout = {
+	root: {
+		index: "index.md",
+		log: "log.md",
+		project: "project.md"
+	},
+	directories: [
+		{
+			directory: "modules",
+			type: "Module"
+		},
+		{
+			directory: "decisions",
+			type: "Decision"
+		},
+		{
+			directory: "conventions",
+			type: "Convention"
+		},
+		{
+			directory: "interfaces",
+			type: "Interface"
+		},
+		{
+			directory: "references",
+			type: "Reference"
+		}
+	]
+};
+const PROJECT_TYPE = "Project";
+const diagnostic = (file, code, message) => ({
+	file,
+	code,
+	severity: "error",
+	message
+});
+/** Plain code-unit order on `file` then `code` (decision 6); never locale-dependent. */
+const compare = (a, b) => {
+	if (a.file < b.file) return -1;
+	if (a.file > b.file) return 1;
+	if (a.code < b.code) return -1;
+	if (a.code > b.code) return 1;
+	return 0;
+};
+/**
+* Exactly one `Project`, at the bundle root (P-21). Pure over `bundle.concepts`
+* (`CORE/Bundle.ts:98`; `Concept.type` `CORE/Concept.ts:27`). The rules are
+* independent: two Projects with one nested yield three diagnostics. The file
+* name `project.md` is layout guidance, not checked. Severity is always
+* `error`; no `range`. Output is sorted by `file` then `code`.
+*/
+const check = (bundle) => {
+	const projects = [...bundle.concepts.values()].filter((concept) => concept.frontmatter.type === PROJECT_TYPE);
+	const out = [];
+	if (projects.length === 0) out.push(diagnostic("", "project-missing", `No Project concept in the bundle; software-project expects exactly one at the bundle root (${layout.root.project})`));
+	if (projects.length > 1) for (const project of projects) {
+		const others = projects.filter((other) => other !== project).map((other) => other.path).sort();
+		out.push(diagnostic(project.path, "project-multiple", `Project concept "${project.path}" is one of ${projects.length}; software-project expects exactly one (others: ${others.join(", ")})`));
+	}
+	for (const project of projects) if (project.path.includes("/")) out.push(diagnostic(project.path, "project-not-at-root", `Project concept "${project.path}" is below the bundle root; software-project expects it beside ${layout.root.index}`));
+	return out.sort(compare);
+};
+/**
+* The `software-project` profile (spec 5; P-20 to P-26, P-42). Reachable
+* publicly only as `Profiles.softwareProject` (P-38).
+*
+* @public
+*/
+const softwareProject = {
+	name: "software-project",
+	config,
+	layout,
+	check
+};
+
+//#endregion
+export { softwareProject };

package/index.d.ts

@@ -1,21 +1,415 @@
-//#region src/index.d.ts
+import { Context, DateTime, Effect, FileSystem, Layer, Option, Path, PlatformError, Schema } from "effect";
+import { Git, GitCommandError, NotARepositoryError, UnknownRefError } from "@effected/git";
+import { Actor, Diagnostic, DiagnosticRange, LoadedBundle, OkfitConfig } from "@okfit/core";
+import { ChildProcessSpawner } from "effect/unstable/process";
+//#region src/BodyProvenance.d.ts
 /**
- * Named okfit configuration profiles.
+ * The body is at HEAD and last changed in the commit described here (P-9).
+ * `at` is that commit's author date (P-4); `committedAt` and the author
+ * identity are carried for callers that want a history-based policy later (P-40).
+ * `creating` is true exactly when the winning entry is also the oldest entry
+ * of the path's history — the commit that created the path (S-9).
  *
- * @packageDocumentation
+ * @public
+ */
+export declare const BodyCommitted: Schema.TaggedStruct<"committed", {
+  readonly at: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly sha: Schema.String;
+  readonly committedAt: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly authorName: Schema.String;
+  readonly authorEmail: Schema.String;
+  readonly creating: Schema.Boolean;
+}>;
+/**
+ * The body has no usable commit (P-9): `untracked` means HEAD does not contain
+ * the path, `dirty` means the on-disk body differs from HEAD's blob, `unborn`
+ * means HEAD has no commits (P-11).
+ *
+ * @public
+ */
+export declare const BodyUncommitted: Schema.TaggedStruct<"uncommitted", {
+  readonly reason: Schema.Literals<readonly ["untracked", "dirty", "unborn"]>;
+}>;
+/**
+ * What {@link Derivation.generatedAt} reports. A schema so the value also
+ * serialises for MCP later without adaptation. Derivation never substitutes
+ * `now`; the uncommitted policy is the caller's (P-10).
+ *
+ * @public
+ */
+export declare const BodyProvenance: Schema.Union<readonly [Schema.TaggedStruct<"committed", {
+  readonly at: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly sha: Schema.String;
+  readonly committedAt: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly authorName: Schema.String;
+  readonly authorEmail: Schema.String;
+  readonly creating: Schema.Boolean;
+}>, Schema.TaggedStruct<"uncommitted", {
+  readonly reason: Schema.Literals<readonly ["untracked", "dirty", "unborn"]>;
+}>]>;
+/**
+ * The type of {@link (BodyProvenance:variable)}.
+ *
+ * @public
+ */
+export type BodyProvenance = typeof BodyProvenance.Type;
+/**
+ * Why a body is uncommitted (P-9).
+ *
+ * @public
+ */
+type UncommittedReason = typeof BodyUncommitted.fields.reason.Type;
+//#endregion
+//#region src/GitHistory.d.ts
+declare const PathHistoryEntry_base: Schema.Class<PathHistoryEntry, Schema.Struct<{
+  readonly sha: Schema.String;
+  readonly authoredAt: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly committedAt: Schema.Codec<import("effect/DateTime").Utc, string, never, never>;
+  readonly authorName: Schema.String;
+  readonly authorEmail: Schema.String;
+  readonly path: Schema.String;
+}>, {}>;
+/**
+ * One record of the path log, newest first (P-3, P-5): the commit, both dates decoded through core's
+ * `Timestamp` (`%aI` / `%cI`, strict ISO with an offset; the `Type` is `DateTime.Utc`, P-4), the author
+ * identity, and the repository-relative posix path the blob had at that commit (the `--name-only` line).
+ * @public
+ */
+export declare class PathHistoryEntry extends PathHistoryEntry_base {}
+declare const GitHistoryError_base: Schema.Class<GitHistoryError, Schema.TaggedStruct<"GitHistoryError", {
+  /** The argv without the leading `git`. */
+  readonly args: Schema.$Array<Schema.String>;
+  /** The working directory the command ran in. */
+  readonly cwd: Schema.String;
+  /** git's exit code; absent when git never produced one. */
+  readonly exitCode: Schema.optionalKey<Schema.Number>;
+  /** git's stderr, captured under `LC_ALL=C`. */
+  readonly stderr: Schema.String;
+  /** Spawn failure text, `timed out after 30s`, or `Git.log`'s own absorbed-failure detail. */
+  readonly detail: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * Profiles' own spawn failure, shaped like `@effected/git`'s `GitCommandError` (P-12). Raised by
+ * `GitHistory.layer` for any `GitCommandError` `Git.log` produces, including the one `Git.log`
+ * itself synthesizes when its own spawn timeout expires.
+ * @public
+ */
+export declare class GitHistoryError extends GitHistoryError_base {
+  get message(): string;
+}
+/**
+ * Options for `pathLog`; `limit` becomes `Git.log`'s `--max-count=<n>` (P-3, P-8).
+ * @public
+ */
+interface PathLogOptions {
+  readonly limit?: number;
+}
+/**
+ * The service shape. `cwd` is any directory inside the repository; `path` is relative to `cwd` (git
+ * pathspec semantics). The result is newest first, and empty when no commit contains the path or HEAD is
+ * unborn (P-11).
+ * @public
+ */
+interface GitHistoryShape {
+  readonly pathLog: (cwd: string, path: string, options?: PathLogOptions) => Effect.Effect<ReadonlyArray<PathHistoryEntry>, GitHistoryError | NotARepositoryError>;
+}
+declare const GitHistory_base: Context.ServiceClass<GitHistory, "@okfit/profiles/GitHistory", GitHistoryShape>;
+/**
+ * A path-scoped, date-bearing log: `Git.log` reads the whole repository history, and this adapter scopes
+ * it to one path (`--follow`, `--diff-merges=first-parent`) and decodes it into `PathHistoryEntry`.
+ * Delegates to `Git.log` as of `@effected/git` 0.12.0 (P-1, spec deviation retired).
+ * @public
+ */
+export declare class GitHistory extends GitHistory_base {
+  /**
+   * Live layer (P-1, P-5, P-11): one `Git.log` call per `pathLog`, resolved once at construction like
+   * `Git.layer` itself, so every member's `R` is `never`. `Git.log` already degrades an unborn `HEAD` and
+   * an unmatched pathspec to the empty array and classifies `not a git repository` as `NotARepositoryError`
+   * (both pass through unchanged); every other failure becomes `GitHistoryError`, including the one
+   * `Git.log` itself produces when its own 30 s spawn timeout expires (`@effected/git`'s `GIT_TIMEOUT`
+   * ceiling, not this adapter's) — `Git.log` never lets a bare `Cause.TimeoutError` escape. The CLI
+   * provides `ChildProcessSpawner` through `NodeServices.layer` (P-30).
+   */
+  static readonly layer: Layer.Layer<GitHistory, never, ChildProcessSpawner.ChildProcessSpawner>;
+  /**
+   * Scripted double (P-32): responses keyed by the `path` argument exactly as passed to `pathLog`. A call
+   * whose path has no entry DIES with `GitHistory.makeTest: pathLog(<path>) was called but not scripted`,
+   * mirroring `Git.makeTest`; `limit` is honoured by slicing. Models none of the live semantics.
+   */
+  static readonly makeTest: (script: Readonly<Record<string, ReadonlyArray<PathHistoryEntry>>>) => GitHistoryShape;
+  /**
+   * `Layer.succeed(GitHistory, GitHistory.makeTest(script))`. Mints a fresh layer per call: bind it to a
+   * `const`, since layers memoize by reference.
+   */
+  static readonly layerTest: (script: Readonly<Record<string, ReadonlyArray<PathHistoryEntry>>>) => Layer.Layer<GitHistory>;
+}
+//#endregion
+//#region src/Derivation.d.ts
+/**
+ * Who is writing now. Explicit, never read from the environment (P-16).
+ *
+ * @public
+ */
+type Writer = "agent" | "human";
+declare const HumanActorUnresolvedError_base: Schema.Class<HumanActorUnresolvedError, Schema.TaggedStruct<"HumanActorUnresolvedError", {
+  readonly userName: Schema.optionalKey<Schema.String>;
+  readonly userEmail: Schema.optionalKey<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+/**
+ * git has no identity to derive a `human:` actor from (P-13 step 4).
+ * `userName` and `userEmail` are the trimmed `configGet` answers when git had
+ * them and absent keys otherwise (decision 53: not `name`/`email`, since every
+ * Effect error class carries the class name on its own prototype and a field
+ * literally named `name` would shadow `error.name` when present); test for
+ * git's answer with `Object.hasOwn(error, "userName")`.
+ *
+ * @public
  */
+export declare class HumanActorUnresolvedError extends HumanActorUnresolvedError_base {
+  get message(): string;
+}
+declare const AgentActorUnconfiguredError_base: Schema.Class<AgentActorUnconfiguredError, Schema.TaggedStruct<"AgentActorUnconfiguredError", {}>, import("effect/Cause").YieldableError>;
 /**
- * Names of the profiles this package ships.
+ * The writer is an agent but `actors.agent` is not configured (P-17); the
+ * profile never sets it.
  *
  * @public
  */
-declare const PROFILE_NAMES: readonly ["software-project"];
+export declare class AgentActorUnconfiguredError extends AgentActorUnconfiguredError_base {
+  get message(): string;
+}
+/**
+ * Options for {@link Derivation.generatedAt} (P-39).
+ *
+ * @public
+ */
+interface GeneratedAtOptions {
+  /** ABSOLUTE path to the concept file on disk. */
+  readonly file: string;
+  /** Reserved (P-48): accepted and ignored in phase 1; no key affects the walk. */
+  readonly config?: OkfitConfig;
+}
+/**
+ * Everything {@link Derivation.generatedAt} can fail with: profiles' own
+ * `GitHistoryError`, the `@effected/git` peer's errors (P-12), and the
+ * `PlatformError` of `realPath`/`readFileString` on `file`.
+ *
+ * @public
+ */
+type GeneratedAtError = GitHistoryError | GitCommandError | NotARepositoryError | UnknownRefError | PlatformError.PlatformError;
+/**
+ * Options for {@link Derivation.generatedBy} (P-16, P-45).
+ *
+ * @public
+ */
+interface GeneratedByOptions {
+  readonly writer: Writer;
+  /** Any directory inside the repository; every `Git` member takes a cwd and profiles never reads `process.cwd()`. */
+  readonly cwd: string;
+  /** Merged or raw; only `actors` is read. */
+  readonly config: OkfitConfig;
+}
+/**
+ * Everything {@link Derivation.generatedBy} can fail with.
+ *
+ * @public
+ */
+type GeneratedByError = AgentActorUnconfiguredError | HumanActorUnresolvedError | GitCommandError | NotARepositoryError | UnknownRefError;
+/**
+ * Trimmed `user.name` / `user.email` as `Git.configGet` answers them; a key is absent when git has no value.
+ *
+ * @public
+ */
+interface GitIdentity {
+  readonly name?: string;
+  readonly email?: string;
+}
+/**
+ * Spec 5.4 derivation rules for the `software-project` profile, package-global
+ * (P-38). Pure members take every input as an argument; effectful members
+ * require `Git`, `GitHistory` and, for the worktree read, `FileSystem` and
+ * `Path` (P-30). Never writes, never reads `generated.by` (P-40).
+ *
+ * @public
+ */
+export declare class Derivation {
+  private constructor();
+  /**
+   * `FrontmatterSource.split(text).body`, then CRLF and lone CR to LF, then trailing whitespace at end of
+   * text removed (P-6). Pure. Applied to both sides of every comparison so `core.autocrlf` worktrees compare clean.
+   */
+  static readonly body: (text: string) => string;
+  /**
+   * Spec 5.4 rule 2 as P-2 (DERIVE option C). Steps:
+   *  1. `root = Git.repoRoot(dirname(file))`: a file outside any repository surfaces `NotARepositoryError`;
+   *     submodules and worktrees work because the question is asked from the file's directory (P-39).
+   *  2. `realPath` both (rev-parse is symlink-resolved), then the repo-relative posix path via `Path` (P-39).
+   *  3. `worktree = body(readFileString(file))`.
+   *  4. `Git.show(realRoot, "HEAD", rel)`: `UnknownRefError` is `uncommitted { unborn }` (P-11), `Option.none`
+   *     is `uncommitted { untracked }` (P-47), a body differing from `worktree` is `uncommitted { dirty }` (P-9).
+   *     The comparison is against HEAD's blob, never the newest log entry (P-46).
+   *  5. `entries = GitHistory.pathLog(realRoot, rel)` newest first (P-5, P-46); `[]` is `uncommitted { unborn }`.
+   *  6. One `Git.show` per older blob (P-8), newest first: the first entry whose body differs from the next
+   *     older entry's body wins, else the oldest entry (the creating commit). "Previous" is the previous entry
+   *     of the simplified `--follow` history, not the true parent (P-7). The newest entry's body is never
+   *     re-fetched: `head.blob`, already confirmed equal to `worktree` by step 4, is reused (decision 56).
+   *     `Option.none` for an older entry counts as "differs", never a defect (decision 56).
+   * `config` is reserved and ignored (P-48). Never writes, never reads `by` (P-40).
+   */
+  static readonly generatedAt: (options: GeneratedAtOptions) => Effect.Effect<BodyProvenance, GeneratedAtError, Git | GitHistory | FileSystem.FileSystem | Path.Path>;
+  /**
+   * P-13 / P-14, pure. Candidates: the email local part (returned as written, lower-cased only for matching)
+   * and the `user.name` slug. Order, first hit wins: (1) a `human:` entry of `humans` whose id equals a
+   * candidate case-insensitively, returned verbatim; (2) `human:<local>`; (3) `human:<slug>`; (4) none.
+   * The result is branded through core's `Actor` codec and always passes it.
+   */
+  static readonly humanActorId: (identity: GitIdentity, humans: ReadonlyArray<Actor>) => Option.Option<Actor>;
+  /**
+   * Spec 5.4 rule 1 (P-16, P-45). `"agent"`: `config.actors.agent`, else {@link AgentActorUnconfiguredError}
+   * (P-17). `"human"`: `Git.configGet(cwd, "user.name")` and `Git.configGet(cwd, "user.email")` in merged
+   * scope (P-15) through {@link Derivation.humanActorId}; none is {@link HumanActorUnresolvedError}.
+   * Answers only "who is writing now" (P-40).
+   */
+  static readonly generatedBy: (options: GeneratedByOptions) => Effect.Effect<Actor, GeneratedByError, Git>;
+  /**
+   * P-19, pure: `from` plus `config.lifecycle.default_stale_after`, falling back to `OkfitConfig.DEFAULTS`'
+   * 90 days. `from` is the caller's: `generated.at` when committed, else its own `now`.
+   */
+  static readonly staleAfter: (from: DateTime.Utc, config: OkfitConfig) => DateTime.Utc;
+}
+//#endregion
+//#region src/Profile.d.ts
+/**
+ * Names of the profiles this package ships (P-38).
+ *
+ * @public
+ */
+export declare const PROFILE_NAMES: readonly ["software-project"];
 /**
  * A profile name shipped by this package.
  *
  * @public
  */
 type ProfileName = (typeof PROFILE_NAMES)[number];
+/**
+ * One concept directory of a profile's bundle layout (P-26). Each directory
+ * carries its own `index.md`; `type` is the `types.<Name>` key held there.
+ *
+ * @public
+ */
+interface LayoutDirectory {
+  readonly directory: string;
+  readonly type: string;
+}
+/**
+ * Scaffolding data for `okfit init` (spec 5.2); never part of `OkfitConfig`
+ * (P-26). What the CLI writes into these files is the CLI plan's concern.
+ *
+ * @public
+ */
+interface Layout {
+  readonly root: {
+    readonly index: "index.md";
+    readonly log: "log.md";
+    readonly project: "project.md";
+  };
+  readonly directories: ReadonlyArray<LayoutDirectory>;
+}
+/**
+ * Profile-owned diagnostic codes (P-21). Core's `LintCode` is untouched; all
+ * three are severity `error` and are not configurable.
+ *
+ * @public
+ */
+export declare const ProfileDiagnosticCode: Schema.Literals<readonly ["project-missing", "project-multiple", "project-not-at-root"]>;
+/**
+ * The type of `ProfileDiagnosticCode`.
+ *
+ * @public
+ */
+export type ProfileDiagnosticCode = typeof ProfileDiagnosticCode.Type;
+/**
+ * Same fields as core's `Diagnostic` with a profile code; a `Schema.Struct`
+ * per P-21/P-51. `file` is the bundle-relative posix path, `""` for the
+ * bundle-level `project-missing`. `range` is never set in phase 1.
+ *
+ * @public
+ */
+export declare const ProfileDiagnostic: Schema.Struct<{
+  readonly file: Schema.String;
+  readonly range: Schema.optionalKey<typeof DiagnosticRange>;
+  readonly code: Schema.Literals<readonly ["project-missing", "project-multiple", "project-not-at-root"]>;
+  readonly severity: Schema.Literals<readonly ["error", "warning", "info"]>;
+  readonly message: Schema.String;
+}>;
+/**
+ * The type of `ProfileDiagnostic`.
+ *
+ * @public
+ */
+export type ProfileDiagnostic = typeof ProfileDiagnostic.Type;
+/**
+ * A named profile (P-38): a partial `OkfitConfig` the CLI merges as
+ * `DEFAULTS < profile < file`, a scaffolding `Layout`, and a pure `check`
+ * over a loaded bundle run after `Validate.all`.
+ *
+ * @public
+ */
+interface Profile {
+  readonly name: ProfileName;
+  readonly config: OkfitConfig;
+  readonly layout: Layout;
+  readonly check: (bundle: LoadedBundle) => ReadonlyArray<ProfileDiagnostic>;
+}
+//#endregion
+//#region src/Profiles.d.ts
+/**
+ * The profile registry (P-38). No third-party registration in phase 1; the
+ * `DEFAULTS < profile < file` merge is the CLI's (D-28).
+ *
+ * @public
+ */
+export declare class Profiles {
+  private constructor();
+  /** The `software-project` profile (spec 5). */
+  static readonly softwareProject: Profile;
+  /**
+   * `Option.none` for `"none"`, unknown names and anything not in
+   * `PROFILE_NAMES`; the CLI decides what that means (P-38). Exact match only.
+   */
+  static readonly get: (name: string) => Option.Option<Profile>;
+}
+//#endregion
+//#region src/Provenance.d.ts
+/**
+ * A profiles-owned lint over committed provenance (S-8). NOT a `Profile`
+ * member and NOT a `ProfileDiagnostic` -- it returns core `Diagnostic`s with
+ * code `"generated-at-drift"`, a real `LintCode` member, so `severityFor`,
+ * the `[lint]` table, the renderers, the hook, and the MCP tool treat it
+ * like every other lint (S-7). `Profile.check` and `ProfileDiagnosticCode`
+ * are unchanged.
+ *
+ * Runs `Derivation.generatedAt` per concept, skips uncommitted bodies and
+ * concepts without a `generated` block, and returns `[]` the moment a
+ * `NotARepositoryError` surfaces: a bundle outside git has nothing to
+ * derive for any concept, so the first occurrence short-circuits the whole
+ * walk, not just the concept that triggered it (S-8). Emits no `range`
+ * (S-12, Judge note 7): `Diagnostic.range` is `Schema.optionalKey` and is
+ * simply omitted.
+ *
+ * `Provenance.lint` is total over severity (S-28, amending Judge note 3):
+ * when `OkfitConfig.severityFor(config, "generated-at-drift")` resolves to
+ * `"off"`, it returns `[]` before any per-concept work and before any git
+ * call, so it is safe to call at any severity and never needs to cast
+ * `"off"` away. `validate/run.ts` (the CLI) still gates on `"off"` before
+ * calling at all; the two agree by construction (both skip the walk).
+ *
+ * @public
+ */
+export declare class Provenance {
+  private constructor();
+  static readonly lint: (bundle: LoadedBundle, config: OkfitConfig) => Effect.Effect<ReadonlyArray<Diagnostic>, GitHistoryError | GitCommandError | UnknownRefError | PlatformError.PlatformError, Git | GitHistory | FileSystem.FileSystem | Path.Path>;
+}
 //#endregion
-export { PROFILE_NAMES, ProfileName };
+export type { GeneratedAtError, GeneratedAtOptions, GeneratedByError, GeneratedByOptions, GitHistoryShape, GitIdentity, Layout, LayoutDirectory, PathLogOptions, Profile, ProfileName, UncommittedReason, Writer };
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,15 +1,8 @@
-//#region src/index.ts
-/**
-* Named okfit configuration profiles.
-*
-* @packageDocumentation
-*/
-/**
-* Names of the profiles this package ships.
-*
-* @public
-*/
-const PROFILE_NAMES = ["software-project"];
+import { BodyCommitted, BodyProvenance, BodyUncommitted } from "./BodyProvenance.js";
+import { GitHistory, GitHistoryError, PathHistoryEntry } from "./GitHistory.js";
+import { AgentActorUnconfiguredError, Derivation, HumanActorUnresolvedError } from "./Derivation.js";
+import { PROFILE_NAMES, ProfileDiagnostic, ProfileDiagnosticCode } from "./Profile.js";
+import { Profiles } from "./Profiles.js";
+import { Provenance } from "./Provenance.js";
 
-//#endregion
-export { PROFILE_NAMES };
+export { AgentActorUnconfiguredError, BodyCommitted, BodyProvenance, BodyUncommitted, Derivation, GitHistory, GitHistoryError, HumanActorUnresolvedError, PROFILE_NAMES, PathHistoryEntry, ProfileDiagnostic, ProfileDiagnosticCode, Profiles, Provenance };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@okfit/profiles",
-	"version": "0.1.0",
+	"version": "0.2.0",
 	"private": false,
 	"description": "Named OKF configuration profiles for okfit, starting with the software-project profile.",
 	"keywords": [
@@ -34,9 +34,11 @@
 		},
 		"./package.json": "./package.json"
 	},
-	"dependencies": {
-		"@okfit/core": "0.1.0",
-		"effect": "4.0.0-rc.109"
+	"peerDependencies": {
+		"@effected/git": "^0.12.0",
+		"@effected/markdown": "^0.9.0",
+		"@okfit/core": "^0.2.0",
+		"effect": "4.0.0-rc.112"
 	},
 	"engines": {
 		"node": ">=24.11.0"