@theholocron/astromech 5.0.0-alpha.147 → 5.0.0-alpha.149

package/dist/config/index.d.mts

@@ -1,4 +1,5 @@
-import { i as normalizeTaskEntry, n as TaskEntry, r as TasksConfig, t as TaskConfigItem } from "../schema-BDld3xq1.mjs";
+import { n as TaskEntry, r as TasksConfig, t as TaskConfigItem } from "../schema.type-BUiSrwS5.mjs";
+import { Loaded } from "@theholocron/datapad";
 //#region src/config/define.d.ts
 /**
  * Typed identity helper for `astromech.config.ts`:
@@ -13,7 +14,7 @@ import { i as normalizeTaskEntry, n as TaskEntry, r as TasksConfig, t as TaskCon
  */
 declare const defineConfig: <C extends TasksConfig>(config: C) => C;
 //#endregion
-//#region src/config/load.d.ts
+//#region src/config/load.type.d.ts
 /**
  * The `tasks` value in each source. A dedicated `astromech.config.*`
  * default-exports the full {@link TasksConfig} object; the `tasks` key of
@@ -21,6 +22,16 @@ declare const defineConfig: <C extends TasksConfig>(config: C) => C;
  * `workflows` key). Either form is accepted from either source.
  */
 type TasksInput = TasksConfig | TaskConfigItem[];
+interface LoadTasksConfigOptions {
+  /**
+   * The `holocron.config.*` the caller has already loaded (`null`: it looked and
+   * there is none), so it isn't found and loaded a second time. Leave it unset
+   * to have `loadTasksConfig` find it itself.
+   */
+  holocron?: Loaded<object> | null;
+}
+//#endregion
+//#region src/config/load.d.ts
 /**
  * Resolve the task manifest for a repo: the `tasks` key of
  * `holocron.config.*`, then a dedicated `astromech.config.*` merged on
@@ -30,10 +41,15 @@ type TasksInput = TasksConfig | TaskConfigItem[];
  * `walkUp: true` — `holocron run`/`ci` are usable from any subdirectory of
  * a repo, not only its exact root (datapad walks up to the nearest `.git`
  * boundary; see `@theholocron/datapad`'s own doc comment).
+ *
+ * A caller that has already loaded `holocron.config.*` passes it as
+ * `options.holocron` so it is not found and loaded again.
  */
-declare function loadTasksConfig(cwd: string): Promise<TasksConfig>;
+declare function loadTasksConfig(cwd: string, options?: LoadTasksConfigOptions): Promise<TasksConfig>;
+//#endregion
+//#region src/config/merge-tasks-layers.d.ts
 /**
- * The merge step of {@link loadTasksConfig}, for callers that load the two
+ * The same layering as {@link loadTasksConfig}, for callers that load the two
  * sources some other way (Sentinel reads them from the GitHub API, not
  * from disk, holocron#916): `holocron.config.*`'s `tasks` value first,
  * then a dedicated `astromech.config.*`'s default export merged on top.
@@ -41,4 +57,16 @@ declare function loadTasksConfig(cwd: string): Promise<TasksConfig>;
  */
 declare function mergeTasksLayers(parentTasks: TasksInput | undefined, dedicated: TasksInput | undefined): TasksConfig;
 //#endregion
+//#region src/config/schema.d.ts
+/**
+ * The `tasks` config shape — the single manifest of what a repo runs.
+ * Read from a dedicated `astromech.config.*` file or the `tasks` key of
+ * `holocron.config.*` (see {@link loadTasksConfig}).
+ *
+ * Runtime validation is the loader's job, not this type's — the type only
+ * describes what an author writes.
+ */
+/** Normalise a `TaskConfigItem` to a full {@link TaskEntry} with defaults applied. */
+declare function normalizeTaskEntry(item: TaskConfigItem): Required<Pick<TaskEntry, "name" | "ci" | "local">> & TaskEntry;
+//#endregion
 export { type TaskConfigItem, type TaskEntry, type TasksConfig, defineConfig, loadTasksConfig, mergeTasksLayers, normalizeTaskEntry };

package/dist/config/index.mjs

@@ -1,5 +1,5 @@
-import { n as mergeTasksLayers, r as normalizeTaskEntry, t as loadTasksConfig } from "../load-ytspboBj.mjs";
-import { createDefineConfig } from "@theholocron/datapad";
+import { n as coerceTasks, r as normalizeTaskEntry, t as loadTasksConfig } from "../load-ToVjaKPr.mjs";
+import { createDefineConfig, mergeLayers } from "@theholocron/datapad";
 //#region src/config/define.ts
 /**
 * Typed identity helper for `astromech.config.ts`:
@@ -14,4 +14,16 @@ import { createDefineConfig } from "@theholocron/datapad";
 */
 const defineConfig = createDefineConfig();
 //#endregion
+//#region src/config/merge-tasks-layers.ts
+/**
+* The same layering as {@link loadTasksConfig}, for callers that load the two
+* sources some other way (Sentinel reads them from the GitHub API, not
+* from disk, holocron#916): `holocron.config.*`'s `tasks` value first,
+* then a dedicated `astromech.config.*`'s default export merged on top.
+* Either may be `undefined` (source absent); returns `{}` when both are.
+*/
+function mergeTasksLayers(parentTasks, dedicated) {
+	return mergeLayers([coerceTasks(parentTasks), coerceTasks(dedicated)]) ?? {};
+}
+//#endregion
 export { defineConfig, loadTasksConfig, mergeTasksLayers, normalizeTaskEntry };

package/dist/index.d.mts

@@ -1,55 +1,5 @@
-import { r as TasksConfig } from "./schema-BDld3xq1.mjs";
-//#region src/generators/github-action-thin-callers.d.ts
-/**
- * Workflow templates + thin-caller generation.
- *
- * `WORKFLOW_TEMPLATES` holds each reusable `.github/workflows/<name>.yml`
- * (synced to `theholocron/.github`); `generateThinCallerContent` wraps one
- * into the thin caller `holocron repo setup` / `holocron repo sync` write locally.
- */
-declare const WORKFLOW_TEMPLATES: Record<string, string>;
-declare const KNOWN_WORKFLOWS: Set<string>;
-/**
- * The GitHub status-check context a `required` task contributes to branch
- * protection. Format: `"{workflow name} / {job name}"`.
- *
- * Most of these are single-job workflows now (D3's decomposition split what
- * used to be multi-job `lint`/`audit` into one task per concern) — the
- * context names that job directly, no `Conclusion` aggregator needed; a
- * single job's own conclusion already *is* the workflow's conclusion.
- * `Conclusion` fan-in jobs are kept only where a task genuinely has several
- * conditionally-run jobs feeding one required check:
- * `verification.unitTests` (unit / Storybook / Chromatic / interaction /
- * user-flow, each gated by its own `run-*` input) and
- * `platform.repoValidation` (its three script jobs all must pass). Only
- * merge-gating workflows are listed. `astromech.requiredChecks()` reads this
- * for every `required` task.
- */
-declare const WORKFLOW_CHECK_CONTEXTS: Partial<Record<string, string>>;
-/**
- * Generate the thin caller content for a workflow, optionally injecting or
- * merging `with:` overrides into the jobs block.
- *
- * Two strategies are used depending on the template:
- * - Templates that already have a `with:` block (e.g. lint):
- *   the override entries are merged in, replacing existing keys and appending
- *   new ones.
- * - Templates that end with `    secrets: inherit`: a new `with:` block is
- *   injected immediately before `secrets: inherit`.
- * If neither pattern matches the template, a warning is emitted and the
- * base template is returned unchanged.
- */
-declare function generateThinCallerContent(name: string, withOverrides?: Record<string, unknown>, additionalPaths?: string[],
-/** Optional sink for the "could not inject `with:`" warning. */
-logger?: {
-  warn(obj: Record<string, unknown>, msg: string): void;
-},
-/**
- * `with:` key → a `# comment` line rendered immediately above that entry.
- * Only honored when injecting a fresh `with:` block (no template today
- * ships one), which is the path `lint` takes.
- */
-comments?: Record<string, string>): string;
+import { r as TasksConfig } from "./schema.type-BUiSrwS5.mjs";
+//#region src/generators/github-action-thin-callers.type.d.ts
 interface PreviewConfig {
   /** Cloudflare Pages project name shared across all repos for previews. */
   project: string;
@@ -72,46 +22,8 @@ interface OrgContext {
   /** Project name — injected as the `name` input to the deploy reusable when `docs: true`. */
   repoName?: string;
 }
-/**
- * Extract the Cloudflare Pages preview config from a deploy workflow's `with:` object.
- *
- * Accepts three forms:
- * - `preview: true` — derive both project and domain from org context
- * - `preview: { project: "..." }` — explicit project; domain derived from context if omitted
- * - `preview: { project: "...", domain: "..." }` — fully explicit
- *
- * Returns null when `preview:` is absent, false, or can't be resolved.
- */
-declare function extractPreviewConfig(raw: Record<string, unknown>, ctx?: OrgContext): PreviewConfig | null;
-/**
- * Generate the full thin-caller YAML for a `deploy.yml` that handles both
- * production (push to main → GitHub Pages) and preview (pull_request →
- * Cloudflare Pages) in a single file.
- *
- * Both jobs receive the same docs/storybook `with:` inputs. If the per-repo
- * config supplies `cloudflare-project` it is forwarded; otherwise the reusable
- * falls back to the `CLOUDFLARE_PAGES_PROJECT` org variable — set that once and
- * all repos with a `deploy` workflow get previews without per-repo config.
- */
-declare function generateCombinedDeployContent(deployWith: Record<string, unknown>, paths: string[], preview: Pick<PreviewConfig, "project">): string;
-/**
- * Expand structured with-values to flat GitHub Actions inputs before
- * generating the thin caller. Handles:
- *   - deploy shorthand: docs/storybook → type + storybook-projects
- *   - preview: stripped (handled separately via extractPreviewConfig)
- *   - run-chromatic object → run-chromatic: true + chromatic-projects
- *   - plain arrays → JSON-stringified for YAML scalar quoting
- *
- * Used by both `holocron repo setup` and `sync-workflow-templates`.
- */
-declare function normalizeWorkflowWith(raw: Record<string, unknown>): Record<string, unknown>;
-/**
- * Derive on.push.paths entries from the deploy with: shorthand.
- * Used by both `holocron repo setup` and `sync-workflow-templates`.
- */
-declare function deriveDeployPaths(raw: Record<string, unknown>): string[];
 //#endregion
-//#region src/generators/turbo.d.ts
+//#region src/generators/turbo.type.d.ts
 interface EnsureRootWorkspaceMemberResult {
   content: string;
   changed: boolean;
@@ -121,36 +33,7 @@ interface EnsureTurboDependencyResult {
   changed: boolean;
 }
 //#endregion
-//#region src/tasks/run/run.d.ts
-/**
- * `holocron run <task> [job] [-- <passthrough>]` — run a registry task (or one
- * of its sub-jobs) locally.
- *
- * A `job` argument only applies to tasks that declare `jobs`; for any other
- * task it is folded back into the passthrough (`holocron run delivery.build
- * src/`).
- *
- * Resolution:
- *
- *   J. job given                              → TASKS[task].jobs[job].local (unknown job → exit 1)
- *   1. turbo.json defines the task            → `turbo run <task>`
- *   2. package.json has a `<task>` script     → `<pm> run <task>`
- *      (unless it's the `holocron run …` thin caller — that recurses)
- *   3. TASKS[task].local resolves             → `<tool> <args> <org-flags> <passthrough>`
- *   3b. TASKS[task].linterGroup               → run each resolved linter natively (see below)
- *   4. TASKS[task].jobs has entries           → run each job in declared order
- *   5. TASKS[task].local === null             → "enforced in CI" (skip, even with --required)
- *   5b. known task, nothing resolved          → "no <task> task" (exit 0, or 1 with --required)
- *   6. unknown task                           → "unknown task" (exit 1)
- *
- * A `linterGroup` task (`sourceQuality.staticAnalysis`, etc.) runs its fixed
- * set of `linters.ts` entries, each still gated by that linter's own
- * `detect`/`always` rule — every entry runs its `localBin` natively when
- * found on PATH. Missing tools are flagged; the exit code is the worst of
- * the lot. Unlike the old single `lint` task, this check runs *after*
- * turbo/`package.json` resolution (step 3b, not step 0) — a `linterGroup`
- * task is a normal turbo-delegatable task like any other.
- */
+//#region src/tasks/run/run.type.d.ts
 /** Minimal structural logger — `@theholocron/observability`'s `Logger` satisfies it. */
 interface RunLogger {
   debug(obj: Record<string, unknown>, msg?: string): void;
@@ -202,9 +85,8 @@ interface RunTaskReport {
   command?: string;
   message?: string;
 }
-declare function runTask(input: RunTaskInput): RunTaskReport;
 //#endregion
-//#region src/tasks/ci.d.ts
+//#region src/tasks/ci.type.d.ts
 interface CiOptions {
   /** Print the plan without running anything. */
   dryRun?: boolean;
@@ -229,9 +111,8 @@ interface CiInput extends RunDeps, CiOptions {
   cwd: string;
   config: TasksConfig;
 }
-declare function runCi(input: CiInput): CiReport;
 //#endregion
-//#region src/tasks/group.d.ts
+//#region src/tasks/group.type.d.ts
 interface GroupOptions {
   /** Print the resolved commands without running anything. */
   dryRun?: boolean;
@@ -255,11 +136,8 @@ interface GroupInput extends RunDeps, GroupOptions {
   /** The bare namespace, e.g. `"sourceQuality"` — matched against `"sourceQuality."`-prefixed task names. */
   namespace: string;
 }
-/** Every configured task whose name starts with `"<namespace>."`, in manifest declaration order. */
-declare function matchNamespace(config: TasksConfig, namespace: string): string[];
-declare function runGroup(input: GroupInput): GroupReport;
 //#endregion
-//#region src/astromech.d.ts
+//#region src/astromech.type.d.ts
 interface AstromechOptions {
   /** Repo root. */
   cwd: string;
@@ -395,23 +273,19 @@ interface Astromech {
    */
   ensureTurboDependency(packageJson: string, workspaceYaml: string): EnsureTurboDependencyResult;
 }
+//#endregion
+//#region src/astromech.d.ts
 declare function createAstromech(options: AstromechOptions): Astromech;
 //#endregion
-//#region src/generators/codecov.d.ts
-/**
- * `codecov.yml` generation — a manifest-derived artifact (component `paths`
- * come from workspace packages; the status targets track the `test` task's
- * coverage setup), the same category as the reusable `test.yml` this package
- * also generates. Moved out of `@theholocron/cli` (theholocron/holocron#650)
- * — `holocron repo setup`'s codecov step now calls {@link codecovConfig} instead
- * of importing this logic directly.
- */
+//#region src/generators/codecov.type.d.ts
 interface WorkspacePackage {
   slug: string;
   name: string;
   /** Which workspace root the package was discovered under. Defaults to `"packages"`. */
   dir?: "packages" | "apps" | "plugins";
 }
+//#endregion
+//#region src/generators/codecov.d.ts
 declare function codecovComponentBlock(packages: WorkspacePackage[]): string;
 /**
  * Ensure every codecov status default carries `if_not_found: success`, so an
@@ -470,52 +344,94 @@ declare const WORKFLOW_TEMPLATE_PROPERTIES: Record<string, string>;
  */
 declare function reusableTemplates(): Map<string, string>;
 //#endregion
-//#region src/generators/required-checks.d.ts
-/** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
-declare function requiredChecks(config: TasksConfig): string[];
-//#endregion
-//#region src/generators/tsconfig.d.ts
+//#region src/generators/github-action-thin-callers.d.ts
+declare const WORKFLOW_TEMPLATES: Record<string, string>;
+declare const KNOWN_WORKFLOWS: Set<string>;
 /**
- * `tsconfig.json` generation — Bucket B (config-resolution workstream, #676):
- * the file must stay committed (the TypeScript language server discovers it
- * directly from disk, no `--config` override mechanism to hand it a path
- * instead), but its content is fully derivable, so it's generated rather
- * than hand-authored — the same category as `.editorconfig`
- * ({@link "./templates/configs/editorconfig/create-config.js" createConfig})
- * and {@link codecovConfig}.
+ * The GitHub status-check context a `required` task contributes to branch
+ * protection. Format: `"{workflow name} / {job name}"`.
  *
- * Surveyed every package-level `tsconfig.json` across the org (`holocron`,
- * `clients`, `utils` — 20+ packages). `extends: "@theholocron/tsconfig/
- * node-lts"`, `compilerOptions.baseUrl: "./"`, `compilerOptions.outDir:
- * "./dist"`, `include: ["src/**\/*.ts"]`, and `exclude: ["node_modules",
- * "dist"]` are uniform in every one — safe defaults here. `paths` (a `@/*`
- * → `./src/*` import alias) is a real per-package choice, present in
- * roughly 40% of packages checked — an opt-in parameter, not a default.
+ * Most of these are single-job workflows now (D3's decomposition split what
+ * used to be multi-job `lint`/`audit` into one task per concern) — the
+ * context names that job directly, no `Conclusion` aggregator needed; a
+ * single job's own conclusion already *is* the workflow's conclusion.
+ * `Conclusion` fan-in jobs are kept only where a task genuinely has several
+ * conditionally-run jobs feeding one required check:
+ * `verification.unitTests` (unit / Storybook / Chromatic / interaction /
+ * user-flow, each gated by its own `run-*` input) and
+ * `platform.repoValidation` (its three script jobs all must pass). Only
+ * merge-gating workflows are listed. `astromech.requiredChecks()` reads this
+ * for every `required` task.
+ */
+declare const WORKFLOW_CHECK_CONTEXTS: Partial<Record<string, string>>;
+/**
+ * Generate the thin caller content for a workflow, optionally injecting or
+ * merging `with:` overrides into the jobs block.
+ *
+ * Two strategies are used depending on the template:
+ * - Templates that already have a `with:` block (e.g. lint):
+ *   the override entries are merged in, replacing existing keys and appending
+ *   new ones.
+ * - Templates that end with `    secrets: inherit`: a new `with:` block is
+ *   injected immediately before `secrets: inherit`.
+ * If neither pattern matches the template, a warning is emitted and the
+ * base template is returned unchanged.
+ */
+declare function generateThinCallerContent(name: string, withOverrides?: Record<string, unknown>, additionalPaths?: string[],
+/** Optional sink for the "could not inject `with:`" warning. */
+logger?: {
+  warn(obj: Record<string, unknown>, msg: string): void;
+},
+/**
+ * `with:` key → a `# comment` line rendered immediately above that entry.
+ * Only honored when injecting a fresh `with:` block (no template today
+ * ships one), which is the path `lint` takes.
+ */
+comments?: Record<string, string>): string;
+/**
+ * Extract the Cloudflare Pages preview config from a deploy workflow's `with:` object.
+ *
+ * Accepts three forms:
+ * - `preview: true` — derive both project and domain from org context
+ * - `preview: { project: "..." }` — explicit project; domain derived from context if omitted
+ * - `preview: { project: "...", domain: "..." }` — fully explicit
  *
- * Two fields checked and deliberately *not* absorbed as defaults, unlike
- * `eslint-config`'s `tsconfigRootDir`/`settings.node` (which turned out
- * redundant with the shared package's own behavior, `configs`#461):
- * `compilerOptions.module`/`moduleResolution` (only `@theholocron/cli`
- * overrides these, to `esnext`/`bundler` — a genuine deviation from the
- * shared `node-lts` preset's `nodenext`/`nodenext`, needed for its bundler
- * tooling, not something every package should inherit) and
- * `compilerOptions.rootDir` (present in exactly two packages, always the
- * same value `./src` that `include` already implies — an unnecessary
- * override wherever it appears, not a pattern worth generalizing).
+ * Returns null when `preview:` is absent, false, or can't be resolved.
+ */
+declare function extractPreviewConfig(raw: Record<string, unknown>, ctx?: OrgContext): PreviewConfig | null;
+/**
+ * Generate the full thin-caller YAML for a `deploy.yml` that handles both
+ * production (push to main → GitHub Pages) and preview (pull_request →
+ * Cloudflare Pages) in a single file.
  *
- * Monorepo *root* `tsconfig.json` (a TS project-references "solution
- * file" — `holocron`'s own root is `{ files: [], references: [...] }`,
- * listing which packages to build) is a structurally different, genuinely
- * per-repo document — out of scope here, same as Bucket C content.
+ * Both jobs receive the same docs/storybook `with:` inputs. If the per-repo
+ * config supplies `cloudflare-project` it is forwarded; otherwise the reusable
+ * falls back to the `CLOUDFLARE_PAGES_PROJECT` org variable — set that once and
+ * all repos with a `deploy` workflow get previews without per-repo config.
+ */
+declare function generateCombinedDeployContent(deployWith: Record<string, unknown>, paths: string[], preview: Pick<PreviewConfig, "project">): string;
+/**
+ * Expand structured with-values to flat GitHub Actions inputs before
+ * generating the thin caller. Handles:
+ *   - deploy shorthand: docs/storybook → type + storybook-projects
+ *   - preview: stripped (handled separately via extractPreviewConfig)
+ *   - run-chromatic object → run-chromatic: true + chromatic-projects
+ *   - plain arrays → JSON-stringified for YAML scalar quoting
  *
- * Not yet wired into `holocron repo setup`'s per-package write loop (every
- * other Bucket B file there is a single repo-root file, safely
- * overwritten every run — `tsconfig.json` is per-package, and most
- * packages' files still carry real hand-authored content today, not yet
- * migrated to a fully-generated state). That per-package iteration +
- * safe-migration design is `#680`'s job, not duplicated here — this is
- * the generator itself, ready for it to call.
+ * Used by both `holocron repo setup` and `sync-workflow-templates`.
+ */
+declare function normalizeWorkflowWith(raw: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Derive on.push.paths entries from the deploy with: shorthand.
+ * Used by both `holocron repo setup` and `sync-workflow-templates`.
  */
+declare function deriveDeployPaths(raw: Record<string, unknown>): string[];
+//#endregion
+//#region src/generators/required-checks.d.ts
+/** Ordered (task contexts in {@link CI_ORDER}, then extras), de-duplicated. */
+declare function requiredChecks(config: TasksConfig): string[];
+//#endregion
+//#region src/generators/tsconfig.type.d.ts
 interface TsconfigOptions {
   /** Human-readable name for the `display` field — the package's own name is the usual choice. */
   display: string;
@@ -532,6 +448,8 @@ interface TsconfigOptions {
    */
   paths?: boolean;
 }
+//#endregion
+//#region src/generators/tsconfig.d.ts
 /**
  * A package-level `tsconfig.json` — the uniform shape confirmed across
  * every package checked, parameterized only by the two fields that
@@ -543,28 +461,7 @@ interface TsconfigOptions {
  */
 declare function createTsconfig(options: TsconfigOptions): string;
 //#endregion
-//#region src/registry.d.ts
-/**
- * The task registry — how each task runs *locally*, without GitHub
- * Actions. `holocron run <task>` and `holocron run ci` resolve against this;
- * adding a task here gives every repo that task.
- *
- * Keyed identically to the workflow templates — a task IS a workflow. This
- * is the canonical vocabulary table (epic #672, D11): every other artifact
- * (`KNOWN_TASKS`, `thin-callers.ts`'s `KNOWN_WORKFLOWS`/`WORKFLOW_CHECK_CONTEXTS`,
- * `CI_ORDER`) derives from these keys rather than hand-duplicating them —
- * including the future GitHub App (#679), which imports this same table for
- * config-schema validation instead of reimplementing its own copy.
- *
- * Task names are an intent-facing vocabulary (`verification.*`,
- * `sourceQuality.*`, `security.*`, `delivery.*`, `platform.*`,
- * `knowledge.*`), not tool names — `eslint`/`vitest`/`tsdown`/… stay
- * internal to this file and `theholocron/configs`. See
- * `docs/wiki/specifications/tech-vocabulary-rename.spec.md` (#675) for the full mapping and
- * the reasoning behind each namespace and decomposition.
- *
- * Spec: `docs/wiki/specifications/tech-astromech-task-runner.spec.md` (epic #581).
- */
+//#region src/registry.type.d.ts
 /** How to run one task (or job) locally. */
 interface LocalRunner {
   /** Binary to invoke — resolved from `node_modules/.bin` then PATH. */
@@ -640,6 +537,29 @@ interface TaskDef {
   /** Turborepo fan-out config for this task — see {@link TurboTaskConfig}. Omitted for whole-repo, non-fan-out tasks. */
   turbo?: TurboTaskConfig;
 }
+//#endregion
+//#region src/registry.d.ts
+/**
+ * The task registry — how each task runs *locally*, without GitHub
+ * Actions. `holocron run <task>` and `holocron run ci` resolve against this;
+ * adding a task here gives every repo that task.
+ *
+ * Keyed identically to the workflow templates — a task IS a workflow. This
+ * is the canonical vocabulary table (epic #672, D11): every other artifact
+ * (`KNOWN_TASKS`, `thin-callers.ts`'s `KNOWN_WORKFLOWS`/`WORKFLOW_CHECK_CONTEXTS`,
+ * `CI_ORDER`) derives from these keys rather than hand-duplicating them —
+ * including the future GitHub App (#679), which imports this same table for
+ * config-schema validation instead of reimplementing its own copy.
+ *
+ * Task names are an intent-facing vocabulary (`verification.*`,
+ * `sourceQuality.*`, `security.*`, `delivery.*`, `platform.*`,
+ * `knowledge.*`), not tool names — `eslint`/`vitest`/`tsdown`/… stay
+ * internal to this file and `theholocron/configs`. See
+ * `docs/wiki/specifications/tech-vocabulary-rename.spec.md` (#675) for the full mapping and
+ * the reasoning behind each namespace and decomposition.
+ *
+ * Spec: `docs/wiki/specifications/tech-astromech-task-runner.spec.md` (epic #581).
+ */
 declare const TASKS: Record<string, TaskDef>;
 /** Every task name the registry knows. */
 declare const KNOWN_TASKS: Set<string>;
@@ -651,17 +571,24 @@ declare const KNOWN_TASKS: Set<string>;
  */
 declare const CI_ORDER: string[];
 //#endregion
-//#region src/tasks/deploy-on-release.d.ts
+//#region src/tasks/ci.d.ts
+declare function runCi(input: CiInput): CiReport;
+//#endregion
+//#region src/utils/default-run.type.d.ts
 interface SpawnResult {
   status: number | null;
   stdout: string;
   stderr: string;
 }
 type Run = (command: string, args: string[], options: Record<string, unknown>) => SpawnResult;
+//#endregion
+//#region src/tasks/deploy-on-release/workspace-packages.type.d.ts
 interface Tree {
   readJson: (path: string) => unknown;
   listDirs: (path: string) => string[];
 }
+//#endregion
+//#region src/tasks/deploy-on-release/deploy-on-release.type.d.ts
 interface DeployOnReleaseOptions {
   cwd: string;
   /** The release's channel: its prerelease identifier (`alpha`); empty or `main` for a stable release. */
@@ -691,6 +618,8 @@ interface DeployOnReleaseReport {
   status: "ok" | "fail" | "skip";
   results: DeployOnReleaseResult[];
 }
+//#endregion
+//#region src/tasks/deploy-on-release/deploy-on-release.d.ts
 /**
  * Deploys every package whose manifest declares a release-time deploy that
  * applies to this release. Never throws for a deploy problem: each package's
@@ -698,4 +627,14 @@ interface DeployOnReleaseReport {
  */
 declare function deployOnRelease(options: DeployOnReleaseOptions, { run, readJson, listDirs, sleep, now, loadTasks }?: DeployOnReleaseDeps): Promise<DeployOnReleaseReport>;
 //#endregion
+//#region src/tasks/group.d.ts
+declare function runGroup(input: GroupInput): GroupReport;
+//#endregion
+//#region src/tasks/match-namespace.d.ts
+/** Every configured task whose name starts with `"<namespace>."`, in manifest declaration order. */
+declare function matchNamespace(config: TasksConfig, namespace: string): string[];
+//#endregion
+//#region src/tasks/run/run.d.ts
+declare function runTask(input: RunTaskInput): RunTaskReport;
+//#endregion
 export { type Astromech, type AstromechOptions, CI_ORDER, type CiJobReport, type CiOptions, type CiReport, type DeployOnReleaseOptions, type DeployOnReleaseReport, type DeployOnReleaseResult, type ExecFn, type GroupJobReport, type GroupOptions, type GroupReport, type JobDef, KNOWN_TASKS, KNOWN_WORKFLOWS, type LocalRunner, type OrgContext, type PreviewConfig, REUSABLE_ACTIONS, REUSABLE_WORKFLOWS, type RunLogger, type RunOptions, type RunTaskInput, type RunTaskReport, TASKS, type TaskDef, type TsconfigOptions, WORKFLOW_CHECK_CONTEXTS, WORKFLOW_TEMPLATES, WORKFLOW_TEMPLATE_PROPERTIES, type WorkspacePackage, codecovComponentBlock, codecovConfig, createAstromech, createCodecovConfig, createTsconfig, deployOnRelease, deriveDeployPaths, ensureIfNotFound, extractPreviewConfig, generateCombinedDeployContent, generateThinCallerContent, matchNamespace, mergeCodecovComponents, normalizeWorkflowWith, readWorkspacePackages, requiredChecks, reusableTemplates, runCi, runGroup, runTask };