@zhuk/spego 0.21.1 → 0.22.1

package/dist/workspace/config.d.ts

@@ -1,4 +1,141 @@
 import { z } from 'zod';
+/** Hours per Size Tier for one Flow profile or the shared human table. */
+declare const tierHoursSchema: z.ZodObject<{
+    xs: z.ZodNumber;
+    s: z.ZodNumber;
+    m: z.ZodNumber;
+    l: z.ZodNumber;
+    xl: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    xs: number;
+    s: number;
+    m: number;
+    l: number;
+    xl: number;
+}, {
+    xs: number;
+    s: number;
+    m: number;
+    l: number;
+    xl: number;
+}>;
+export type TierHours = z.infer<typeof tierHoursSchema>;
+/** Pricing configuration: per-Flow seed tables plus one shared human table. */
+export declare const flowsSchema: z.ZodEffects<z.ZodObject<{
+    /** Flow profile that prices a change whose epic declares no `flow`. */
+    default: z.ZodString;
+    /** Per-Flow seed tables mapping Size Tier to Flow Hours. */
+    profiles: z.ZodRecord<z.ZodString, z.ZodObject<{
+        xs: z.ZodNumber;
+        s: z.ZodNumber;
+        m: z.ZodNumber;
+        l: z.ZodNumber;
+        xl: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    }, {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    }>>;
+    /** Human Hours table, shared across Flows. */
+    human: z.ZodObject<{
+        xs: z.ZodNumber;
+        s: z.ZodNumber;
+        m: z.ZodNumber;
+        l: z.ZodNumber;
+        xl: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    }, {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    }>;
+    /** Opt-in to the cross-project pricing rung; off keeps pricing reproducible from the repo alone. */
+    crossProject: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    default: string;
+    profiles: Record<string, {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    }>;
+    human: {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    };
+    crossProject: boolean;
+}, {
+    default: string;
+    profiles: Record<string, {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    }>;
+    human: {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    };
+    crossProject?: boolean | undefined;
+}>, {
+    default: string;
+    profiles: Record<string, {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    }>;
+    human: {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    };
+    crossProject: boolean;
+}, {
+    default: string;
+    profiles: Record<string, {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    }>;
+    human: {
+        xs: number;
+        s: number;
+        m: number;
+        l: number;
+        xl: number;
+    };
+    crossProject?: boolean | undefined;
+}>;
+export type FlowsConfig = z.infer<typeof flowsSchema>;
 export declare const workspaceConfigSchema: z.ZodObject<{
     /** Schema version. Bump when config layout changes. */
     version: z.ZodDefault<z.ZodLiteral<1>>;
@@ -18,6 +155,121 @@ export declare const workspaceConfigSchema: z.ZodObject<{
         options?: Record<string, unknown> | undefined;
         name?: string | undefined;
     }>>;
+    /** Change pricing tables; absent means the workspace renders unpriced. */
+    flows: z.ZodOptional<z.ZodEffects<z.ZodObject<{
+        /** Flow profile that prices a change whose epic declares no `flow`. */
+        default: z.ZodString;
+        /** Per-Flow seed tables mapping Size Tier to Flow Hours. */
+        profiles: z.ZodRecord<z.ZodString, z.ZodObject<{
+            xs: z.ZodNumber;
+            s: z.ZodNumber;
+            m: z.ZodNumber;
+            l: z.ZodNumber;
+            xl: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }>>;
+        /** Human Hours table, shared across Flows. */
+        human: z.ZodObject<{
+            xs: z.ZodNumber;
+            s: z.ZodNumber;
+            m: z.ZodNumber;
+            l: z.ZodNumber;
+            xl: z.ZodNumber;
+        }, "strict", z.ZodTypeAny, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }>;
+        /** Opt-in to the cross-project pricing rung; off keeps pricing reproducible from the repo alone. */
+        crossProject: z.ZodDefault<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        default: string;
+        profiles: Record<string, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }>;
+        human: {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        };
+        crossProject: boolean;
+    }, {
+        default: string;
+        profiles: Record<string, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }>;
+        human: {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        };
+        crossProject?: boolean | undefined;
+    }>, {
+        default: string;
+        profiles: Record<string, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }>;
+        human: {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        };
+        crossProject: boolean;
+    }, {
+        default: string;
+        profiles: Record<string, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }>;
+        human: {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        };
+        crossProject?: boolean | undefined;
+    }>>;
 }, "strict", z.ZodTypeAny, {
     agents: string[];
     demo: boolean;
@@ -27,6 +279,24 @@ export declare const workspaceConfigSchema: z.ZodObject<{
         options: Record<string, unknown>;
         name: string;
     };
+    flows?: {
+        default: string;
+        profiles: Record<string, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }>;
+        human: {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        };
+        crossProject: boolean;
+    } | undefined;
 }, {
     agents?: string[] | undefined;
     demo?: boolean | undefined;
@@ -36,6 +306,24 @@ export declare const workspaceConfigSchema: z.ZodObject<{
         options?: Record<string, unknown> | undefined;
         name?: string | undefined;
     } | undefined;
+    flows?: {
+        default: string;
+        profiles: Record<string, {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        }>;
+        human: {
+            xs: number;
+            s: number;
+            m: number;
+            l: number;
+            xl: number;
+        };
+        crossProject?: boolean | undefined;
+    } | undefined;
 }>;
 export type WorkspaceConfig = z.infer<typeof workspaceConfigSchema>;
 export declare function defaultConfig(overrides?: Partial<WorkspaceConfig>): WorkspaceConfig;
@@ -43,3 +331,4 @@ export declare function readConfig(configPath: string): Promise<WorkspaceConfig>
 export declare function writeConfig(configPath: string, config: WorkspaceConfig): Promise<void>;
 /** Returns the union of built-in and user-extended artifact types. */
 export declare function knownArtifactTypes(config: WorkspaceConfig): Set<string>;
+export {};

package/dist/workspace/config.js

@@ -3,6 +3,34 @@ import YAML from 'yaml';
 import { z } from 'zod';
 import { SpegoError } from '../errors.js';
 import { BUILTIN_ARTIFACT_TYPES } from '../artifacts/types.js';
+const hours = z.number().finite().nonnegative();
+/** Hours per Size Tier for one Flow profile or the shared human table. */
+const tierHoursSchema = z
+    .object({
+    xs: hours,
+    s: hours,
+    m: hours,
+    l: hours,
+    xl: hours,
+})
+    .strict();
+/** Pricing configuration: per-Flow seed tables plus one shared human table. */
+export const flowsSchema = z
+    .object({
+    /** Flow profile that prices a change whose epic declares no `flow`. */
+    default: z.string().min(1),
+    /** Per-Flow seed tables mapping Size Tier to Flow Hours. */
+    profiles: z.record(z.string().min(1), tierHoursSchema),
+    /** Human Hours table, shared across Flows. */
+    human: tierHoursSchema,
+    /** Opt-in to the cross-project pricing rung; off keeps pricing reproducible from the repo alone. */
+    crossProject: z.boolean().default(false),
+})
+    .strict()
+    .refine((flows) => Object.hasOwn(flows.profiles, flows.default), {
+    path: ['default'],
+    message: 'flows.default must name a declared profile',
+});
 export const workspaceConfigSchema = z
     .object({
     /** Schema version. Bump when config layout changes. */
@@ -19,6 +47,8 @@ export const workspaceConfigSchema = z
         name: z.string().default('openspec'),
         options: z.record(z.string(), z.unknown()).default({}),
     }).default({ name: 'openspec', options: {} }),
+    /** Change pricing tables; absent means the workspace renders unpriced. */
+    flows: flowsSchema.optional(),
 })
     .strict();
 export function defaultConfig(overrides = {}) {

package/dist/workspace/config.js.map

@@ -1 +1 @@
-{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/workspace/config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../src/workspace/config.ts"],"names":[],"mappings":"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"}

package/dist/workspace/paths.d.ts

@@ -26,6 +26,16 @@ export interface WorkspacePaths {
 }
 export declare function resolveWorkspacePaths(projectRoot: string): WorkspacePaths;
 export declare function artifactTypeDir(paths: WorkspacePaths, type: string): string;
+/** Environment variable naming the cross-project store root; overrides the platform configuration directory. */
+export declare const STORE_ROOT_ENV_VAR = "SPEGO_STORE_ROOT";
+export declare const STORE_RUNS_FILE_NAME = "runs.jsonl";
+/**
+ * Root of the cross-project run store: the environment override when set,
+ * else the platform configuration directory. The variable names the root, not
+ * the runs file, so the store's layout can change without a flag change.
+ */
+export declare function resolveStoreRoot(env?: NodeJS.ProcessEnv): string;
+export declare function storeRunsPath(storeRoot: string): string;
 export declare function artifactFilePath(paths: WorkspacePaths, type: string, slug: string): string;
 export declare function revisionFilePath(paths: WorkspacePaths, type: string, slug: string, revision: number): string;
 /** Lstat-guard .spego then resolve realpath for containment root. */

package/dist/workspace/paths.js

@@ -1,4 +1,5 @@
 import fs from 'node:fs/promises';
+import os from 'node:os';
 import { SpegoError } from '../errors.js';
 import path from 'node:path';
 /**
@@ -27,6 +28,30 @@ export function resolveWorkspacePaths(projectRoot) {
 export function artifactTypeDir(paths, type) {
     return path.join(paths.artifactsRoot, type);
 }
+/** Environment variable naming the cross-project store root; overrides the platform configuration directory. */
+export const STORE_ROOT_ENV_VAR = 'SPEGO_STORE_ROOT';
+export const STORE_RUNS_FILE_NAME = 'runs.jsonl';
+/**
+ * Root of the cross-project run store: the environment override when set,
+ * else the platform configuration directory. The variable names the root, not
+ * the runs file, so the store's layout can change without a flag change.
+ */
+export function resolveStoreRoot(env = process.env) {
+    const override = env[STORE_ROOT_ENV_VAR];
+    if (override !== undefined && override.trim().length > 0)
+        return path.resolve(override);
+    const home = os.homedir();
+    if (process.platform === 'win32') {
+        return path.join(env.APPDATA ?? path.join(home, '.config'), 'spego');
+    }
+    if (process.platform === 'darwin') {
+        return path.join(home, 'Library', 'Application Support', 'spego');
+    }
+    return path.join(env.XDG_CONFIG_HOME ?? path.join(home, '.config'), 'spego');
+}
+export function storeRunsPath(storeRoot) {
+    return path.join(storeRoot, STORE_RUNS_FILE_NAME);
+}
 export function artifactFilePath(paths, type, slug) {
     return path.join(paths.artifactsRoot, type, `${slug}.md`);
 }

package/dist/workspace/paths.js.map

@@ -1 +1 @@
-{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/workspace/paths.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/workspace/paths.ts"],"names":[],"mappings":"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"}

package/docs/agent-targets.md

@@ -0,0 +1,32 @@
+# Agent targets and generated files
+
+`spego init` generates agent-facing files for every target listed under `agents` in `.spego/config.yaml`. Run `spego skills` to regenerate them without reinitializing the workspace.
+
+## Claude
+
+- `.claude/skills/spego-<command>/SKILL.md` — skill definitions following Claude Code conventions
+- `.claude/commands/spego/` — slash command wrappers
+
+Workflow skills land at `.claude/skills/spego-<workflow>/SKILL.md`; the agent picks them up from the skill description.
+
+## OpenCode
+
+- `.opencode/commands/spego-apply.md` — implements pending tasks from an OpenSpec change in the active OpenCode instance
+- `.opencode/commands/spego-verify.md` — checks completeness, correctness, coherence, and tests before archive
+- `.opencode/commands/spego-explore.md` — a read-only exploration stance for ideas, problems, or OpenSpec changes
+
+`/spego-apply` runs as a phased current-session workflow: select the change, load context, plan tasks, execute work, verify results, update task checkboxes, summarize status. It may use OpenCode-native subagents only inside the active OpenCode instance, for independent investigation, implementation review, or verification.
+
+### Scope
+
+spego does not start or control OpenCode through `opencode serve`, does not call the OpenCode REST API, does not create external OpenCode sessions, and does not own model selection. Configure models, variants, agents, and permissions in OpenCode itself.
+
+There are no `spego apply`, `spego verify`, `spego explore`, or `spego orchestrate` CLI commands. Apply, verify, and explore are generated OpenCode workflows; spego remains the local artifact engine and read-only OpenSpec delivery view.
+
+## Regeneration and stale files
+
+During regeneration spego removes stale generated OpenCode compatibility files — old `opsx-*` commands, `openspec-*` skills, retired orchestration assets — only when they carry the `spego_generated: true` marker. User-owned files without that marker are preserved and reported as skipped.
+
+## Related
+
+- [Workflows](workflows.md) — what the generated workflow skills do

package/docs/cli.md

@@ -0,0 +1,49 @@
+# CLI reference
+
+Every command accepts `--cwd <dir>` to set the project root, and the global `--json` flag to switch output modes.
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `spego init` | Initialize a `.spego/` workspace |
+| `spego status` | Report workspace status |
+| `spego create --type prd --title "My PRD"` | Create an artifact |
+| `spego read --id <uuid>` | Read by id, type+slug, or path |
+| `spego update --id <uuid> --body "new content"` | Update with revision control |
+| `spego delete --id <uuid>` | Soft-delete, preserving history |
+| `spego list` | List artifacts |
+| `spego view` | Overview of artifacts as a table; `--detail` exports the full markdown bundle, `--json` exports full JSON |
+| `spego commands` | List command metadata |
+| `spego workflows` | List workflow skill metadata |
+| `spego skills` | Regenerate agent skill files |
+| `spego epics [name]` | List delivery epics, or get one by change name |
+| `spego tasks <change> [task]` | List tasks for a change, or get one task |
+| `spego sprints` | List sprint plans in board order |
+| `spego board` | Show the delivery board — sprints, change signals, drift; `--sync` reconciles first |
+| `spego sync` | Reconcile the delivery mirror: create missing epics, close finished sprints, retire epics of archived changes |
+| `spego record <change>` | Record one measured run (`--flow`, `--hours`) against a change's epic `actuals`; appends, never overwrites |
+| `spego index rebuild` | Rebuild the SQLite index from files |
+
+## Output modes
+
+Every command speaks two modes.
+
+**Human (default)** — scannable terminal output. Each command renders a section: a single emoji header (`📦 📄 🛠️ 🧭 📚 ✅ ✨ 🗑 📋 🏃 🕸️ 🧩`), a blank line, then content. Summaries render as bordered boxes (`╭─ … ─╮`), lists as aligned tables. Errors print as `⚠️  [CODE] message` on stderr.
+
+**JSON (opt-in)** — pass `--json` for deterministic, decoration-free JSON on stdout. Errors come back on stderr as `{ "error": { "code", "message", "details" } }`, where `details` is always an object.
+
+Agents calling spego MUST pass `--json`. Humans normally do not.
+
+`view` defaults to an overview — a totals box plus one table per artifact type, with `epic` rows carrying delivery-derived status. `view --detail` renders the full markdown bundle instead, separating artifacts with `────` dividers.
+
+## Artifact payloads
+
+`read --json` and `update --json` both return artifact records with `frontmatter`, `body`, and `path`; `update` also keeps the compatibility fields `id` and `revision`.
+
+`create` and `update` accept body content through `--body`, `--body-file <path>`, or stdin via `--body-file -`.
+
+## Related
+
+- [Delivery board](delivery-board.md) — what `board`, `sync`, and `epics` derive
+- [Estimation](estimation.md) — what `record` feeds and how prices resolve

package/docs/delivery-board.md

@@ -0,0 +1,63 @@
+# Delivery board
+
+`spego board` derives the delivery mirror on demand. It never writes artifacts or OpenSpec state.
+
+The board combines active and archived OpenSpec changes with `epic` and `sprint-plan` artifacts into a sprint board: sprints in date order (undated last), each sprint's changes in dependency order, then per-change status, blockers, gaps, and missing artifacts (`requires` minus resolvable `links`).
+
+A change is blocked when a dependency is not `done` or `completed` and is not scheduled in the same or an earlier sprint. Archived changes are discovered from `openspec/changes/archive/<date>-<slug>/`, with the date prefix stripped to derive the slug, and always resolve to `completed` — so a dependency that resolved through the archive no longer trips `dangling-dep`.
+
+## Status
+
+A change's status is one of `backlog`, `in-progress`, `done`, `completed`, `blocked`, `paused`, or `unknown`.
+
+`done` and `completed` both satisfy a dependent's blocker check but mean different things: `done` is all tasks checked and not yet archived; `completed` is archived — a filesystem fact that always wins, even over a manual override. Human output (`board`, `epics`, and `view`'s epic rows) prints `completed` as `archived`, since that is the fact that explains why the change is finished. `--json` keeps `completed` unchanged, so agents see no contract change.
+
+`blocked` and `paused` have no signal in OpenSpec's plain-text files, so they are set by hand on the `epic` artifact's `status` meta. That override applies only to a change with a real backing OpenSpec change, never forces `done`/`completed`/`in-progress`/`backlog`, and is dropped once the change is archived. An orphan epic — no backing change at all — has no other source of truth, so its `status` meta accepts any of the seven values.
+
+## Identity and conflict tracks
+
+Every change carries a stable `id`: `c` plus a 4+ hex-char slice of the slug's sha1 hash (`c4f2a`), longer only for the rare slug that collides with another on the same board. The id depends only on the slug, so adding, removing, or archiving other changes never shifts an existing id. Blockers are reported by `id`, not slug.
+
+`group` names the change's conflict track — the epic's `track` meta, set during grooming from file and subsystem overlap. Two changes sharing a track are expected to conflict and must run sequentially; changes in different tracks are parallel-safe. A pending change whose epic has no track shows `?` — grooming debt to clear with `spego groom`. A `done` or `completed` change shows `—`. Unlike `id`, `group` is a live value expected to shift as tracks are assigned and work completes.
+
+## Modes and filters
+
+The default output is the human board.
+
+- `--graph` shows dependency edges.
+- `--gaps` focuses on gap flags and missing artifacts.
+- `--sync` applies the mechanical reconciliation plan before rendering.
+- `--archived` restores archived changes to the `Ungrouped` list, which excludes them by default. They still resolve dependencies and blockers either way, and a sprint's own change list is never filtered — an archived change still scheduled in a sprint keeps showing there, struck through as satisfied.
+- `--closed` renders a sprint whose changes are all `done`/`completed`, which is otherwise hidden behind a trailing `N closed sprints hidden (--closed to show).` note and rendered muted when shown. This is purely a display filter: `--json` always lists every sprint, and hiding never writes `status: closed` to the sprint-plan artifact — that persistence belongs to the groom workflow, after your confirmation.
+
+`--graph` and `--gaps` also carry the `id` column. The global `--json` flag emits a deterministic `{ sprints, ungrouped, warnings, next }` document in all modes; `next` names the first pending, unblocked change, or is `null` with a hint to groom.
+
+## Rendering
+
+Each sprint — and the `Ungrouped` list and the trailing `Warnings` table — renders as a bordered panel: a left rail closed on the right with `│`, corners `╮`/`╯`, and its title embedded in the top rail as `<title> · <status> · <slug>`, bolded.
+
+Every panel on a board renders at the same width: whichever is wider between the shared table grid and the longest panel title, capped at the terminal width. A title too long for that width truncates with `…` rather than widening its panel past its siblings.
+
+The default change table carries `id`, `change`, `status`, `group`, and `signals` — plus `hours` between `group` and `signals` when the workspace declares a `flows` block — on one shared grid across every panel. Columns shrink together, widest first, to fit the terminal width, or 120 columns when not a TTY. The `change` column is protected: it never truncates, so every slug shows in full no matter how narrow the terminal gets, and the other columns absorb the deficit.
+
+The `signals` column summarizes drift as nonzero counts joined by `·` — `N blk` (blockers), `N gap` (gap flags), `N mis` (missing artifacts) — or `—` when the change is clean. The full text lives in `spego board --gaps`.
+
+The footer adds a dim `spego board --gaps` hint when any rendered change carries a signal, and a dim `N mechanical fixes — run spego sync` line when the reconciliation plan is non-empty.
+
+## Drift warnings
+
+Every rendering attaches drift warnings: `dangling-dep`, `dep-cycle`, `out-of-order-dep`, `ungroomed-change`, `orphan-epic`, `closable-sprint`, and `stale-profile`. `out-of-order-dep` flags a scheduled change blocked by a dependency scheduled into a later sprint.
+
+The mechanical subset is repaired by `spego sync`:
+
+- `ungroomed-change` — create the epic
+- `closable-sprint` — close the sprint
+- `orphan-epic` whose change is archived — retire the epic
+
+The judgment-only warnings — `orphan-epic` whose change is missing, `dangling-dep`, `dep-cycle`, `out-of-order-dep`, and [`stale-profile`](estimation.md#bias) — belong to the groom workflow. The board only reports; pass `--sync` to apply the mechanical plan and re-render in one step.
+
+## Related
+
+- [Estimation](estimation.md) — the `hours` column and sprint totals
+- [OpenSpec adapter](openspec-adapter.md) — where change state comes from
+- [Workflows](workflows.md#groom) — the groom workflow that clears judgment debt