@pmelab/gtd 6.8.0 → 6.9.0

package/README.md

@@ -58,13 +58,19 @@ gtd init
 This writes a `.gtdrc.json` for the bundled unified workflow, with each agent
 state's prompt saved as an editable Markdown file under `gtd-prompts/` and
 referenced from the config (review and commit both). Edit a prompt by editing
-its `gtd-prompts/*.md` file — no config edit needed. It also seeds a top-level
-`modes:` block suggesting **Prettier** as the steering-file formatter
-(`npx prettier --write` for the built-in `qa`/`review` modes — format only, so
-gtd still validates); edit or drop it freely (swap in dprint, a script, or
-delete the key). `gtd init` takes no argument. gtd ships **no** default
-workflow: a state command run before `gtd init` fails, pointing you back here.
-See [Configuration](docs/configuration.md#gtd-init) for the template.
+its `gtd-prompts/*.md` file — no config edit needed. File references resolve
+relative to **the `.gtdrc` that declares them**, so a config and its
+`gtd-prompts/` can even live in a parent directory shared across repos while gtd
+runs from each repo root — run `gtd init` from that parent directory (it need
+not be a git repo) to scaffold it there (see
+[Configuration](docs/configuration.md#content-values-inline-or-a-file-reference)).
+It also seeds a top-level `modes:` block suggesting **Prettier** as the
+steering-file formatter (`npx prettier --write` for the built-in `qa`/`review`
+modes — format only, so gtd still validates); edit or drop it freely (swap in
+dprint, a script, or delete the key). `gtd init` takes no argument. gtd ships
+**no** default workflow: a state command run before `gtd init` fails, pointing
+you back here. See [Configuration](docs/configuration.md#gtd-init) for the
+template.
 
 ## How it works
 

package/dist/gtd.bundle.mjs

@@ -189815,6 +189815,49 @@ const resolveContent = (value, configDir, where, errors) => {
 		return;
 	}
 };
+/**
+* Inline every `./`/`../` content file reference in ONE raw `workflow:` value
+* against `configDir` — the directory of the `.gtdrc` that DECLARED it — and
+* return a copy with those references replaced by the referenced file's text.
+*
+* Used by `src/Config.ts`'s `loadMerged` to resolve each config level's
+* references against its OWN file's directory BEFORE the levels are
+* deep-merged. The merge collapses every level into one anonymous object, so it
+* erases which file a given `states.x.prompt` came from; resolving up front,
+* per level, is the only way `./gtd-prompts/x.md` in a parent `.gtdrc` resolves
+* against the parent (not the cwd a child repo runs from). `compileWorkflowConfig`
+* is then invoked with `inlineFileRefs: false` on the merged result.
+*
+* Malformed shapes (a non-object workflow, non-object `states`, a non-object
+* state, a non-string content value) pass through untouched —
+* `compileWorkflowConfig`/`validateDefinition` own those findings; this pass
+* only rewrites the strings it recognizes as file references, collecting a load
+* error (via `resolveContent`) for any that is missing or unreadable.
+*/
+const inlineWorkflowFileRefs = (rawWorkflow, configDir, errors) => {
+	if (!isPlainObject$1(rawWorkflow)) return rawWorkflow;
+	const rawStates = rawWorkflow["states"];
+	if (!isPlainObject$1(rawStates)) return rawWorkflow;
+	const states = {};
+	for (const [name, state] of Object.entries(rawStates)) {
+		if (!isPlainObject$1(state)) {
+			states[name] = state;
+			continue;
+		}
+		const next = { ...state };
+		for (const key of CONTENT_KEYS) {
+			const value = state[key];
+			if (typeof value !== "string" || !isFileReference(value)) continue;
+			const resolved = resolveContent(value, configDir, `state "${name}" (${key})`, errors);
+			if (resolved !== void 0) next[key] = resolved;
+		}
+		states[name] = next;
+	}
+	return {
+		...rawWorkflow,
+		states
+	};
+};
 const KNOWN_EDGE_KEYS = /* @__PURE__ */ new Set(["to", "describe"]);
 /**
 * Compile one `on` row's value into an `OnEdge` (or `undefined`, pushing a
@@ -189883,8 +189926,15 @@ const compileRetry = (raw, name, errors) => {
 		otherwise
 	} : void 0;
 };
-/** Exactly one of script/prompt/message/commit, each a string, file-refs auto-inlined. */
-const compileContent = (raw, name, configDir, errors) => {
+/**
+* Exactly one of script/prompt/message/commit, each a string, file-refs
+* auto-inlined. `inlineFileRefs` is `false` only when the caller
+* (`src/Config.ts`'s `loadMerged`) has ALREADY inlined every reference per
+* declaring file — the content is then taken verbatim, so a `script:` whose
+* inlined text happens to begin with `./` is never mistaken for a second file
+* reference and re-resolved.
+*/
+const compileContent = (raw, name, configDir, errors, inlineFileRefs) => {
 	const content = {};
 	for (const key of CONTENT_KEYS) {
 		const rawValue = raw[key];
@@ -189893,6 +189943,10 @@ const compileContent = (raw, name, configDir, errors) => {
 			errors.push(`state "${name}": "${key}" must be a string`);
 			continue;
 		}
+		if (!inlineFileRefs) {
+			content[key] = rawValue;
+			continue;
+		}
 		const resolved = resolveContent(rawValue, configDir, `state "${name}" (${key})`, errors);
 		if (resolved !== void 0) content[key] = resolved;
 	}
@@ -189991,7 +190045,7 @@ const assembleStateDef = (parts) => ({
 	...assembleContentFields(parts.content)
 });
 /** One state's full shape: actor, content, `on`, `initial`, `retry`. */
-const compileState = (name, raw, configDir, errors) => {
+const compileState = (name, raw, configDir, errors, inlineFileRefs) => {
 	if (!isPlainObject$1(raw)) {
 		errors.push(`state "${name}": must be an object, got ${describeType(raw)}`);
 		return {};
@@ -190000,7 +190054,7 @@ const compileState = (name, raw, configDir, errors) => {
 	if (unknownKeys.length > 0) errors.push(`state "${name}": unknown key(s) ${unknownKeys.join(", ")}`);
 	return assembleStateDef({
 		actor: compileActor(raw, name, errors),
-		content: compileContent(raw, name, configDir, errors),
+		content: compileContent(raw, name, configDir, errors, inlineFileRefs),
 		on: compileOn(raw.on, name, errors),
 		initial: compileInitial(raw, name, errors),
 		retry: compileRetry(raw.retry, name, errors),
@@ -190019,12 +190073,15 @@ const compileState = (name, raw, configDir, errors) => {
 * file's own directory, used to resolve `./`/`../` file references. `rcModes`
 * is the already-compiled top-level `.gtdrc` `modes:` key (`src/Config.ts`),
 * layered over the workflow's own `modes:` per half BEFORE validation — so a
-* state may name a mode either layer declares. Throws a single
-* `Error` (message: `"workflow config:\n  - ..."`, one line per finding) on
-* ANY config-shape problem or `validateDefinition` finding — never partially
-* succeeds.
-*/
-const compileWorkflowConfig = (raw, configDir, rcModes) => {
+* state may name a mode either layer declares. `inlineFileRefs` (default
+* `true`) inlines content file references against `configDir`; the real config
+* path (`src/Config.ts`'s `loadMerged`) passes `false` because it has already
+* inlined every reference per declaring file across the merge chain, so
+* `configDir` is then irrelevant. Throws a single `Error` (message:
+* `"workflow config:\n  - ..."`, one line per finding) on ANY config-shape
+* problem or `validateDefinition` finding — never partially succeeds.
+*/
+const compileWorkflowConfig = (raw, configDir, rcModes, inlineFileRefs = true) => {
 	if (!isPlainObject$1(raw)) throw new Error(`workflow config: must be an object, got ${describeType(raw)}`);
 	const errors = [];
 	const unknownTopKeys = Object.keys(raw).filter((k) => !KNOWN_TOP_KEYS.has(k));
@@ -190037,7 +190094,7 @@ const compileWorkflowConfig = (raw, configDir, rcModes) => {
 		throw new Error(formatErrors(errors));
 	}
 	const states = {};
-	for (const [name, s] of Object.entries(rawStates)) states[name] = compileState(name, s, configDir, errors);
+	for (const [name, s] of Object.entries(rawStates)) states[name] = compileState(name, s, configDir, errors, inlineFileRefs);
 	const definition = modes !== void 0 ? {
 		states,
 		modes
@@ -190327,22 +190384,50 @@ const makeExplorer = () => (0, import_dist.cosmiconfig)("gtd", {
 /**
 * Load and deep-merge every config level from cwd up the directory chain.
 * Innermost (cwd) wins. Returns the merged plain object (undecoded).
-*/
+*
+* A `workflow:` value's `./`/`../` content file references are inlined PER
+* LEVEL against that level's OWN file directory (`dirname(result.filepath)`)
+* BEFORE merging — because the deep-merge collapses every level into one
+* anonymous object and erases which file each `states.x.prompt` came from.
+* Resolving up front is what lets a `.gtdrc` stored in a parent directory
+* reference `./gtd-prompts/x.md` and have it resolve against the parent, even
+* though gtd runs from a child repo (a different cwd). Any missing/unreadable
+* reference is collected and thrown as one aggregated `workflow config:` error,
+* exactly like the compiler's own resolution. The merged, already-inlined
+* `workflow:` is later compiled with `inlineFileRefs: false` (see
+* `toOperations`).
+*/
+/**
+* Normalize one loaded config level: validate it is a plain object, then inline
+* its `workflow:` file references against its OWN file's directory (collecting
+* any missing/unreadable reference into `refErrors`). A level with no
+* `workflow:` key passes through untouched.
+*/
+const inlineLevel = (config, filepath, refErrors) => {
+	if (!isPlainObject(config)) throw new Error(`${filepath}: config must be a plain object, got ${Array.isArray(config) ? "array" : String(config)}`);
+	if (config["workflow"] === void 0) return config;
+	return {
+		...config,
+		workflow: inlineWorkflowFileRefs(config["workflow"], dirname(filepath), refErrors)
+	};
+};
+/** Read every config level from cwd up the chain, outermost→innermost, each with its file references already inlined per declaring file. Throws on a malformed level or an aggregated set of bad references. */
+const readConfigLevels = async (root) => {
+	const chain = walkUp(root, homedir());
+	const explorer = makeExplorer();
+	const levels = [];
+	const refErrors = [];
+	for (let i = chain.length - 1; i >= 0; i--) {
+		const result = await explorer.search(chain[i]);
+		if (!result || result.isEmpty) continue;
+		levels.push(inlineLevel(result.config, result.filepath, refErrors));
+	}
+	if (refErrors.length > 0) throw new Error(`workflow config:\n${refErrors.map((e) => `  - ${e}`).join("\n")}`);
+	return levels;
+};
 const loadMerged = (root) => tryPromise({
 	try: async () => {
-		const home = homedir();
-		const chain = walkUp(root, home);
-		const explorer = makeExplorer();
-		const levels = [];
-		for (let i = chain.length - 1; i >= 0; i--) {
-			const dir = chain[i];
-			const result = await explorer.search(dir);
-			if (result && !result.isEmpty) {
-				if (!isPlainObject(result.config)) throw new Error(`${result.filepath}: config must be a plain object, got ${Array.isArray(result.config) ? "array" : String(result.config)}`);
-				levels.push(result.config);
-			}
-		}
-		return levels.reduce((acc, level) => deepMerge(acc, level), {});
+		return (await readConfigLevels(root)).reduce((acc, level) => deepMerge(acc, level), {});
 	},
 	catch: (e) => e instanceof Error ? e : new Error(String(e))
 });
@@ -190396,18 +190481,19 @@ const compileRcVars = (raw) => {
 const NO_WORKFLOW_MESSAGE = "gtd: no workflow configured — run `gtd init` to create .gtdrc.json";
 /**
 * Compile the decoded config's `workflow:` key plus its top-level
-* `vars:`/`modes:` keys into `ConfigOperations`. `root` is used as the
-* workflow compiler's `configDir` — the directory a custom workflow's
-* `./`-relative content references resolve against. Throws `NO_WORKFLOW_MESSAGE`
-* when no `workflow:` key is present (there is no bundled default to fall back
-* to — see `gtd init`), or (via `compileWorkflowConfig`/`compileRcVars`) on any
-* invalid workflow/vars.
+* `vars:`/`modes:` keys into `ConfigOperations`. Its `./`/`../` content file
+* references were already inlined per declaring file by `loadMerged`, so the
+* compiler is invoked with `inlineFileRefs: false` and `root` is passed only as
+* an (unused) `configDir` placeholder. Throws `NO_WORKFLOW_MESSAGE` when no
+* `workflow:` key is present (there is no bundled default to fall back to — see
+* `gtd init`), or (via `compileWorkflowConfig`/`compileRcVars`) on any invalid
+* workflow/vars.
 */
 const toOperations = (decoded, root) => {
 	const rcVars = compileRcVars(decoded.vars);
 	const rcModes = compileRcModes(decoded.modes);
 	if (decoded.workflow === void 0) throw new Error(NO_WORKFLOW_MESSAGE);
-	const { definition, vars: workflowVars } = compileWorkflowConfig(decoded.workflow, root, rcModes);
+	const { definition, vars: workflowVars } = compileWorkflowConfig(decoded.workflow, root, rcModes, false);
 	return {
 		workflow: definition,
 		workflowVars,
@@ -204404,7 +204490,7 @@ const runInitCommand = (argv, json, write) => gen(function* () {
 	if (args.length > 0) return yield* fail$2(/* @__PURE__ */ new Error(`gtd init: too many arguments — init takes no argument, got: ${args.join(", ")}`));
 	const git = yield* GitService;
 	const fs = yield* FileSystem;
-	yield* assertRunningFromRepoRoot(git, fs);
+	const inRepo = yield* assertInitLocation(git, fs);
 	const { root } = yield* Cwd;
 	if (yield* configPresentAt(root)) return yield* fail$2(/* @__PURE__ */ new Error("gtd init: a gtd config already exists — remove it before re-initializing"));
 	const toError = (e) => e instanceof Error ? e : new Error(String(e));
@@ -204418,11 +204504,12 @@ const runInitCommand = (argv, json, write) => gen(function* () {
 	if (json) write(JSON.stringify({
 		written: ".gtdrc.json",
 		workflow: "unified",
-		prompts: scaffold.prompts.map((p) => p.path)
+		prompts: scaffold.prompts.map((p) => p.path),
+		inRepo
 	}) + "\n");
 	else {
 		const promptCount = scaffold.prompts.length;
-		write(`Wrote .gtdrc.json with the bundled unified workflow, and its ${promptCount} agent prompt${promptCount === 1 ? "" : "s"} as editable Markdown under ${PROMPTS_DIR}/ (referenced from the config).\n\nReview and commit them before starting: an uncommitted .gtdrc.json (or prompt\nfile) counts as a pending change, so the initial state would capture it on the\nfirst step. Once committed, run \`gtd step human\` to begin.\n`);
+		write(`Wrote .gtdrc.json with the bundled unified workflow, and its ${promptCount} agent prompt${promptCount === 1 ? "" : "s"} as editable Markdown under ${PROMPTS_DIR}/ (referenced from the config).\n\n` + (inRepo ? "Review and commit them before starting: an uncommitted .gtdrc.json (or prompt\nfile) counts as a pending change, so the initial state would capture it on the\nfirst step. Once committed, run `gtd step human` to begin.\n" : "This directory is not a git repository, so there is nothing to commit here. The\nconfig applies to any gtd repository nested below it — gtd discovers it by\nwalking up from the repository root. Run `gtd step human` from such a repo to\nbegin.\n"));
 	}
 });
 /**
@@ -204812,6 +204899,24 @@ const assertRunningFromRepoRoot = (git, fs) => gen(function* () {
 	const topLevel = yield* git.topLevel();
 	if ((yield* fs.realPath(topLevel)) !== (yield* fs.realPath(process.cwd()))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd must be run from the repository root (${topLevel}); the current directory is ${process.cwd()}`));
 });
+/**
+* `gtd init` writes only a `.gtdrc.json` (+ prompt files) — it derives no state,
+* so unlike the state commands it need not sit in a git repository at all. It
+* may run EITHER at a repository root OR in a directory outside any repository —
+* the latter scaffolds a shared config a nested repo picks up by walking up the
+* cwd→home chain (see the parent-dir layout in docs/configuration.md). The one
+* placement it must refuse is a repository SUBDIRECTORY: gtd runs from the repo
+* root and discovers config by walking UP, so a config written below the root
+* would silently never be found. Returns whether cwd is inside a repository (at
+* its root), so the caller can tailor the "commit before starting" guidance —
+* there is nothing to commit outside a repo.
+*/
+const assertInitLocation = (git, fs) => gen(function* () {
+	const topLevel = yield* either(git.topLevel());
+	if (topLevel._tag === "Left") return false;
+	if ((yield* fs.realPath(topLevel.right)) !== (yield* fs.realPath(process.cwd()))) return yield* fail$2(/* @__PURE__ */ new Error(`gtd init must be run from the repository root (${topLevel.right}) or from a directory outside any git repository; the current directory is a repository subdirectory: ${process.cwd()}`));
+	return true;
+});
 /** Dispatches to the named `run*Command` handler for every known subcommand. */
 const dispatchKnownSubcommand = (sub, argv, json, write, cost, model) => {
 	switch (sub) {

package/docs/configuration.md

@@ -92,11 +92,23 @@ engine, and [§3](../STATES.md#3-pattern-grammar) for the pattern grammar.
 ### Content values: inline or a file reference
 
 A `script`/`prompt`/`message`/`commit` value starting with `./` or `../` is a
-**file reference** — resolved relative to the config file's own directory and
-read at load time. A missing or unreadable file reference is a **load error**,
-collected and thrown with every other config problem — never silently treated as
-inline text. Any other string (including one that merely contains a `/`, or an
-absolute path) is inline Eta template source, used verbatim.
+**file reference** — resolved relative to **the directory of the `.gtdrc` that
+declared it** (not the directory `gtd` runs from) and read at load time. A
+missing or unreadable file reference is a **load error**, collected and thrown
+with every other config problem — never silently treated as inline text. Any
+other string (including one that merely contains a `/`, or an absolute path) is
+inline Eta template source, used verbatim.
+
+Because references anchor to the declaring file, a `.gtdrc` and its
+`gtd-prompts/` (or `prompts/`) directory can live **outside** the repo — e.g. in
+a parent directory shared across several repos. gtd still runs from the repo
+root, discovers the parent `.gtdrc` by walking up the directory chain (see
+["Lookup and precedence"](#lookup-and-precedence) — cwd→home), and inlines each
+level's `./`-relative references against that level's own directory. When
+workflows are layered across levels, every reference resolves against the file
+that wrote it, so a parent's `./gtd-prompts/x.md` and a child's never collide.
+You can scaffold such a shared config by running [`gtd init`](#gtd-init) from
+that parent directory — it need not be a git repository.
 
 ```yaml
 workflow:
@@ -677,6 +689,16 @@ load time, so a prompt is editable Markdown and editing it changes the workflow
 with no config edit. Human `message:` blocks and check `script:` bodies stay
 inline in the config (they are workflow mechanics, not prompts).
 
+`gtd init` writes only config — it derives no git state — so it need not run in
+a git repository. It runs at a **repository root** or in a directory **outside
+any repository** (scaffolding a shared config a nested repo picks up by walking
+up — see the parent-dir note under
+[file references](#content-values-inline-or-a-file-reference)); its guidance
+adjusts to say there is nothing to commit when it is not in a repo. It refuses
+only to write into a repository **subdirectory**, where the upward config walk
+would never find the file. Either way, it will not overwrite an existing config
+at that directory (remove it first to re-scaffold).
+
 It also seeds a top-level [`modes:`](#modes--pluggable-steering-file-modes)
 block as a ready-to-edit suggestion — a Prettier `format:` for each built-in
 steering-file mode the template uses:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pmelab/gtd",
-  "version": "6.8.0",
+  "version": "6.9.0",
   "private": false,
   "description": "Git-aware CLI that emits the next prompt for an autonomous coding agent based on the current repository state",
   "bin": {