@gr8ful/spf 0.3.0 → 0.5.0

package/dist/core/data_types.d.ts

@@ -150,6 +150,45 @@ export declare const DocumentOutput: EnvelopeType<{
     commit_message: string;
 }>;
 export type DocumentOutputT = v.InferOutput<typeof DocumentOutput.schema>;
+/**
+ * One node in a decomposed product spec — a feature/epic container, or a
+ * story/bug/task leaf. Flat with a `parent` key, not nested JSON: a model
+ * emits a flat list far more reliably than a recursive tree, and a flat
+ * shape is what lets `blocked_by` reference ANY other node, container or
+ * leaf, not just siblings under the same parent.
+ *
+ * `key` is the refiner's own local id for this run (e.g. "F1", "S1.1") —
+ * scoped to one `RefineOutput`, never a tracker id; `core/refine.ts`
+ * resolves `key`s to real issue numbers as it creates them, in dependency
+ * order. See `gates.refinementWellFormed` for the shape rules enforced on
+ * this list before publish ever runs (unique keys, resolvable references,
+ * no cycles, container/leaf kind agreement, at least one leaf).
+ */
+export declare const RefinedIssueSchema: v.ObjectSchema<{
+    readonly key: v.StringSchema<undefined>;
+    readonly kind: v.PicklistSchema<["epic", "feature", "story", "bug", "task"], undefined>;
+    readonly title: v.StringSchema<undefined>;
+    readonly body: v.StringSchema<undefined>;
+    readonly parent: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly blocked_by: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
+}, undefined>;
+export type RefinedIssue = v.InferOutput<typeof RefinedIssueSchema>;
+/** A product spec decomposed into a feature/story tree — see `steps.refine()` and `core/refine.ts`. */
+export declare const RefineOutput: EnvelopeType<{
+    status: "fail" | "success";
+    summary: string;
+    artifacts: string[];
+    notes_for_next_agent: string;
+    issues: {
+        key: string;
+        kind: "bug" | "epic" | "feature" | "story" | "task";
+        title: string;
+        body: string;
+        parent: string;
+        blocked_by: string[];
+    }[];
+}>;
+export type RefineOutputT = v.InferOutput<typeof RefineOutput.schema>;
 export declare const QualityAreaSchema: v.PicklistSchema<["frontend", "backend"], undefined>;
 export type QualityArea = v.InferOutput<typeof QualityAreaSchema>;
 export declare const QualityOperationSchema: v.PicklistSchema<["lint", "typecheck", "build"], undefined>;
@@ -337,6 +376,7 @@ export declare const AgentConfigSchema: v.ObjectSchema<{
     readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
     readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+    readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
 }, undefined>;
 export type AgentConfig = v.InferOutput<typeof AgentConfigSchema>;
 export declare const ConfigDefaultsSchema: v.ObjectSchema<{
@@ -350,9 +390,35 @@ export declare const ConfigDefaultsSchema: v.ObjectSchema<{
     readonly data_dir: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data">;
 }, undefined>;
 export type ConfigDefaults = v.InferOutput<typeof ConfigDefaultsSchema>;
+/**
+ * OpenTelemetry span export — OFF unless this block exists, and `endpoint` is
+ * required BY THIS SCHEMA rather than defaulted, because presence of the block
+ * IS the activation switch. No ambient environment variable can turn export on
+ * (notably NOT `OTEL_EXPORTER_OTLP_ENDPOINT`): an unrelated shell variable must
+ * never become a data-egress switch. See `core/otel.ts`'s header for the full
+ * set of constraints, including the attribute allowlist that keeps repo source
+ * code (tool args, prompts, envelopes, the request text) off the wire.
+ *
+ * `endpoint` is URL-validated so a typo fails at config load rather than as a
+ * silent per-run export failure. Either the full OTLP traces path
+ * (`https://collector:4318/v1/traces`) or a bare origin (`/v1/traces` is
+ * appended — see `resolveTracesUrl`). `headers` is where a collector's auth
+ * token goes; its VALUES are treated as secrets and never logged.
+ */
+export declare const OTelConfigSchema: v.ObjectSchema<{
+    readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
+    readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+    readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+}, undefined>;
+export type OTelConfig = v.InferOutput<typeof OTelConfigSchema>;
 export declare const ObservabilityConfigSchema: v.ObjectSchema<{
     readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
     readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 500>;
+    readonly otel: v.OptionalSchema<v.ObjectSchema<{
+        readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
+        readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+        readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+    }, undefined>, undefined>;
 }, undefined>;
 export type ObservabilityConfig = v.InferOutput<typeof ObservabilityConfigSchema>;
 /**
@@ -370,8 +436,25 @@ export type ObservabilityConfig = v.InferOutput<typeof ObservabilityConfigSchema
  * watch` startup, not here — an empty string parses fine (this schema has
  * no opinion on whether watch is even configured), matching the same
  * "fails loudly before anything spawns, not eagerly at parse time" pattern
- * `quality:` already uses. Its shape depends on `code_host`: "owner/name"
- * for github, "workspace/repo_slug" for bitbucket.
+ * `quality:` already uses. `repo` always names `code_host`'s own repo —
+ * its shape depends on `code_host`: "owner/name" for github,
+ * "workspace/repo_slug" for bitbucket. `resolveCodeHostProvider`
+ * (`cli/commands/watch.ts`) always reads it.
+ *
+ * `issue_repo` exists for exactly one combination where that single field
+ * stops being enough: `issue_provider: github` with `code_host: bitbucket`
+ * — GitHub-issues-against-a-Bitbucket-repo, a real setup this project
+ * explicitly supports, where the issue tracker and the code host are
+ * genuinely different repos in different systems, not the same repo worn
+ * two ways. Every other combination stays a single field: `issue_provider:
+ * github` + `code_host: github` is one repo by construction; `issue_provider:
+ * jira` never reads `repo` at all (it uses `jira.base_url`/`project_key`),
+ * so `repo` unambiguously belongs to whichever code host is configured.
+ * `resolveIssueProvider`'s github branch and `core/refine.ts`'s
+ * `resolveAuthoringProvider` (issue authoring always targets the issue
+ * tracker, never the code host) both read `issue_repo || repo` — leaving
+ * `issue_repo` unset is a complete no-op, so no existing config needs to
+ * change.
  */
 export declare const WatchIssueProviderSchema: v.PicklistSchema<["github", "jira"], undefined>;
 export type WatchIssueProviderKind = v.InferOutput<typeof WatchIssueProviderSchema>;
@@ -383,10 +466,27 @@ export declare const WatchJiraConfigSchema: v.ObjectSchema<{
     readonly project_key: v.OptionalSchema<v.StringSchema<undefined>, "">;
 }, undefined>;
 export type WatchJiraConfig = v.InferOutput<typeof WatchJiraConfigSchema>;
+/**
+ * The second `spf watch` lane: decompose a `<prefix>:spec-ready` product
+ * spec into a feature/story tree of real issues, instead of running
+ * `watch.chain` against it directly (a spec is not individually workable —
+ * see `core/refine.ts`). Off by default so an existing `watch:` config's
+ * behavior is unchanged by upgrading; turning it on with
+ * `issue_provider: jira` fails loudly at `spf watch` startup, since
+ * `JiraProvider` doesn't implement `IssueAuthoringProvider` (create/link)
+ * yet — see its module comment.
+ */
+export declare const WatchRefineConfigSchema: v.ObjectSchema<{
+    readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+    readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "refine">;
+    readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
+}, undefined>;
+export type WatchRefineConfig = v.InferOutput<typeof WatchRefineConfigSchema>;
 export declare const WatchConfigSchema: v.ObjectSchema<{
     readonly issue_provider: v.OptionalSchema<v.PicklistSchema<["github", "jira"], undefined>, "github">;
     readonly code_host: v.OptionalSchema<v.PicklistSchema<["github", "bitbucket"], undefined>, "github">;
     readonly repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
+    readonly issue_repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
     readonly label_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
     readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "plan-build-test">;
     readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
@@ -399,6 +499,15 @@ export declare const WatchConfigSchema: v.ObjectSchema<{
         base_url: string;
         project_key: string;
     }>;
+    readonly refine: v.OptionalSchema<v.ObjectSchema<{
+        readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "refine">;
+        readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
+    }, undefined>, () => {
+        enabled: boolean;
+        chain: string;
+        concurrency: number;
+    }>;
 }, undefined>;
 export type WatchConfig = v.InferOutput<typeof WatchConfigSchema>;
 /**
@@ -437,6 +546,34 @@ export declare const NotificationsConfigSchema: v.ObjectSchema<{
     }, undefined>, undefined>, () => never[]>;
 }, undefined>;
 export type NotificationsConfig = v.InferOutput<typeof NotificationsConfigSchema>;
+/**
+ * `simple_sdlc`'s human-signoff gate — see the ACCEPTED ADVERSARIAL
+ * AMENDMENTS on the review-accountability thread. `simple_sdlc.ts`'s
+ * `commit_build` predicate is the ONLY place in this codebase where an AI
+ * reviewer's `approved` flag gates a commit; `decideSignoff` (same file)
+ * turns that PROPOSAL into a human's DISPOSAL wherever a human is at the
+ * keyboard, and reads these two knobs when there isn't one.
+ *
+ * `require_human_signoff` defaults to FALSE for this release, deliberately:
+ * flipping it to fail-closed-by-default would break every unattended
+ * `simple-sdlc` run (`spf watch`, CI) the day this shipped, before `spf
+ * watch` itself is signoff-aware (its own human gate today is the PR merge,
+ * now informed by the reviewer digest — see `cli/commands/watch.ts`). An
+ * unattended run instead proceeds on the AI verdict alone with a LOUD
+ * one-time warning (`decideSignoff`'s `AI_ONLY_SIGNOFF_WARNING`) until that
+ * changes. Set `true` and an unattended run fails the phase CLOSED instead —
+ * see `decideSignoff`'s fail-closed branch — rather than silently
+ * auto-approving because nobody typed at a prompt that was never shown.
+ *
+ * `signoff_timeout_seconds` bounds the interactive prompt itself: expiry
+ * means NOT accepted (the confirm's own default), never an unbounded stdin
+ * read inside `run.phase()` — see `cli/ask.ts`'s `confirm(..., {timeoutMs})`.
+ */
+export declare const ReviewConfigSchema: v.ObjectSchema<{
+    readonly require_human_signoff: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+    readonly signoff_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 300>;
+}, undefined>;
+export type ReviewConfig = v.InferOutput<typeof ReviewConfigSchema>;
 export declare const SFConfigSchema: v.ObjectSchema<{
     readonly defaults: v.OptionalSchema<v.ObjectSchema<{
         readonly coding_agent: v.OptionalSchema<v.PicklistSchema<["flue", "claude_code"], undefined>, "flue">;
@@ -460,9 +597,21 @@ export declare const SFConfigSchema: v.ObjectSchema<{
     readonly observability: v.OptionalSchema<v.ObjectSchema<{
         readonly db: v.OptionalSchema<v.StringSchema<undefined>, ".spf/data/spf.db">;
         readonly poll_ms: v.OptionalSchema<v.NumberSchema<undefined>, 500>;
+        readonly otel: v.OptionalSchema<v.ObjectSchema<{
+            readonly endpoint: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.UrlAction<string, undefined>]>;
+            readonly headers: v.OptionalSchema<v.RecordSchema<v.StringSchema<undefined>, v.StringSchema<undefined>, undefined>, undefined>;
+            readonly service_name: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
+        }, undefined>, undefined>;
     }, undefined>, () => {
         db: string;
         poll_ms: number;
+        otel?: {
+            endpoint: string;
+            headers?: {
+                [x: string]: string;
+            } | undefined;
+            service_name: string;
+        } | undefined;
     }>;
     readonly agents: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
         readonly name: v.StringSchema<undefined>;
@@ -478,6 +627,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly harness_engineering: v.OptionalSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, () => never[]>;
         readonly tools: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
         readonly writes: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
+        readonly env_allowlist: v.OptionalSchema<v.NullableSchema<v.ArraySchema<v.StringSchema<undefined>, undefined>, undefined>, undefined>;
     }, undefined>, undefined>, () => never[]>;
     readonly quality: v.OptionalSchema<v.ObjectSchema<{
         readonly checks: v.OptionalSchema<v.ArraySchema<v.ObjectSchema<{
@@ -504,6 +654,7 @@ export declare const SFConfigSchema: v.ObjectSchema<{
         readonly issue_provider: v.OptionalSchema<v.PicklistSchema<["github", "jira"], undefined>, "github">;
         readonly code_host: v.OptionalSchema<v.PicklistSchema<["github", "bitbucket"], undefined>, "github">;
         readonly repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
+        readonly issue_repo: v.OptionalSchema<v.StringSchema<undefined>, "">;
         readonly label_prefix: v.OptionalSchema<v.StringSchema<undefined>, "spf">;
         readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "plan-build-test">;
         readonly base_branch: v.OptionalSchema<v.StringSchema<undefined>, "main">;
@@ -516,10 +667,20 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             base_url: string;
             project_key: string;
         }>;
+        readonly refine: v.OptionalSchema<v.ObjectSchema<{
+            readonly enabled: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+            readonly chain: v.OptionalSchema<v.StringSchema<undefined>, "refine">;
+            readonly concurrency: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>, v.MinValueAction<number, 1, undefined>]>, 1>;
+        }, undefined>, () => {
+            enabled: boolean;
+            chain: string;
+            concurrency: number;
+        }>;
     }, undefined>, () => {
         issue_provider: "github" | "jira";
         code_host: "bitbucket" | "github";
         repo: string;
+        issue_repo: string;
         label_prefix: string;
         chain: string;
         base_branch: string;
@@ -529,6 +690,11 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             base_url: string;
             project_key: string;
         };
+        refine: {
+            enabled: boolean;
+            chain: string;
+            concurrency: number;
+        };
     }>;
     readonly notifications: v.OptionalSchema<v.ObjectSchema<{
         readonly events: v.OptionalSchema<v.PicklistSchema<["off", "errors", "all"], undefined>, "off">;
@@ -549,13 +715,24 @@ export declare const SFConfigSchema: v.ObjectSchema<{
             name: string;
         }[];
     }>;
+    readonly review: v.OptionalSchema<v.ObjectSchema<{
+        readonly require_human_signoff: v.OptionalSchema<v.BooleanSchema<undefined>, false>;
+        readonly signoff_timeout_seconds: v.OptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.MinValueAction<number, 1, undefined>]>, 300>;
+    }, undefined>, () => {
+        require_human_signoff: boolean;
+        signoff_timeout_seconds: number;
+    }>;
 }, undefined>;
 export type SFConfig = v.InferOutput<typeof SFConfigSchema>;
+/** The full set of event kinds any tracer.event()/makeEventRecord() call site emits — kept in sync with src/ui/shared/types.ts's EventType. */
+export declare const EVENT_RECORD_TYPES: readonly ["phase_start", "agent_start", "tool_call", "handoff", "gate_pass", "gate_fail", "log", "agent_end", "phase_end", "error"];
+export declare const EventRecordTypeSchema: v.PicklistSchema<readonly ["phase_start", "agent_start", "tool_call", "handoff", "gate_pass", "gate_fail", "log", "agent_end", "phase_end", "error"], undefined>;
+export type EventRecordType = v.InferOutput<typeof EventRecordTypeSchema>;
 /** One traced event, always logged against adw_id + phase. */
 export interface EventRecord {
     adw_id: string;
     phase_id: string;
-    type: string;
+    type: EventRecordType;
     name: string;
     payload: Record<string, unknown>;
     parent_id: string;
@@ -565,7 +742,7 @@ export interface EventRecord {
 }
 export declare function makeEventRecord(input: Partial<EventRecord> & {
     adw_id: string;
-    type: string;
+    type: EventRecordType;
 }): EventRecord;
 /**
  * Everything one coding-agent dispatch+read turn needs, whichever backend
@@ -597,6 +774,7 @@ export interface AgentRequest {
     output_type_name: string;
     cwd: string;
     flue_db_path: string;
+    env?: Record<string, string>;
 }
 /**
  * Tokens and the dollars they cost, per component, summed over a call.

package/dist/core/data_types.js

@@ -103,6 +103,32 @@ export const DocumentOutput = envelopeType("DocumentOutput", {
     documented_files: v.optional(v.array(v.string()), () => []),
     commit_message: v.optional(v.string(), ""),
 });
+/**
+ * One node in a decomposed product spec — a feature/epic container, or a
+ * story/bug/task leaf. Flat with a `parent` key, not nested JSON: a model
+ * emits a flat list far more reliably than a recursive tree, and a flat
+ * shape is what lets `blocked_by` reference ANY other node, container or
+ * leaf, not just siblings under the same parent.
+ *
+ * `key` is the refiner's own local id for this run (e.g. "F1", "S1.1") —
+ * scoped to one `RefineOutput`, never a tracker id; `core/refine.ts`
+ * resolves `key`s to real issue numbers as it creates them, in dependency
+ * order. See `gates.refinementWellFormed` for the shape rules enforced on
+ * this list before publish ever runs (unique keys, resolvable references,
+ * no cycles, container/leaf kind agreement, at least one leaf).
+ */
+export const RefinedIssueSchema = v.object({
+    key: v.string(),
+    kind: v.picklist(["epic", "feature", "story", "bug", "task"]),
+    title: v.string(),
+    body: v.string(), // "## What to build" / "## Acceptance criteria" — see assets/prompts/refiner/user.md
+    parent: v.optional(v.string(), ""), // another node's `key`; "" = top level
+    blocked_by: v.optional(v.array(v.string()), () => []), // other nodes' `key`s that must land first
+});
+/** A product spec decomposed into a feature/story tree — see `steps.refine()` and `core/refine.ts`. */
+export const RefineOutput = envelopeType("RefineOutput", {
+    issues: v.optional(v.array(RefinedIssueSchema), () => []),
+});
 // ── Deterministic quality blocks ─────────────────────────────────────────────
 export const QualityAreaSchema = v.picklist(["frontend", "backend"]);
 export const QualityOperationSchema = v.picklist(["lint", "typecheck", "build"]);
@@ -255,6 +281,15 @@ export const AgentConfigSchema = v.object({
     //   [...]     -> only these. A trailing "/" means a directory prefix; a "*"
     //                makes it a glob; anything else is an exact path.
     writes: v.optional(v.nullable(v.array(v.string()))),
+    // Opt-in env allowlist for this agent's subprocess/sandbox environment.
+    // undefined/null (the default) -> unrestricted: the full operator
+    // environment is passed through, byte-identical to before this field
+    // existed — same three-state shape as `writes` above, so `null` (the
+    // spelling config.md teaches for "unrestricted") parses instead of
+    // rejecting. Set -> only these keys, plus the baseline
+    // (PATH/HOME/USER/LANG/TERM/TMPDIR) that agent_flue.ts's local() sandbox
+    // would keep anyway.
+    env_allowlist: v.optional(v.nullable(v.array(v.string()))),
 });
 export const ConfigDefaultsSchema = v.object({
     coding_agent: v.optional(v.picklist(["flue", "claude_code"]), "flue"),
@@ -270,9 +305,36 @@ export const ConfigDefaultsSchema = v.object({
     protected_files: v.optional(v.array(v.string()), () => [".spf/", "spf.config.yaml"]),
     data_dir: v.optional(v.string(), ".spf/data"),
 });
+/**
+ * OpenTelemetry span export — OFF unless this block exists, and `endpoint` is
+ * required BY THIS SCHEMA rather than defaulted, because presence of the block
+ * IS the activation switch. No ambient environment variable can turn export on
+ * (notably NOT `OTEL_EXPORTER_OTLP_ENDPOINT`): an unrelated shell variable must
+ * never become a data-egress switch. See `core/otel.ts`'s header for the full
+ * set of constraints, including the attribute allowlist that keeps repo source
+ * code (tool args, prompts, envelopes, the request text) off the wire.
+ *
+ * `endpoint` is URL-validated so a typo fails at config load rather than as a
+ * silent per-run export failure. Either the full OTLP traces path
+ * (`https://collector:4318/v1/traces`) or a bare origin (`/v1/traces` is
+ * appended — see `resolveTracesUrl`). `headers` is where a collector's auth
+ * token goes; its VALUES are treated as secrets and never logged.
+ */
+export const OTelConfigSchema = v.object({
+    endpoint: v.pipe(v.string(), v.url()),
+    headers: v.optional(v.record(v.string(), v.string()), undefined),
+    service_name: v.optional(v.string(), "spf"),
+});
 export const ObservabilityConfigSchema = v.object({
     db: v.optional(v.string(), ".spf/data/spf.db"),
     poll_ms: v.optional(v.number(), 500),
+    // Absent by default. `agents.ts`'s mergeRawConfig spreads `observability`
+    // field-by-field, so this nested object merges as a WHOLE-OBJECT replace on
+    // override — an override that sets `otel:` replaces the base's entirely,
+    // which is the semantics you want for an endpoint + its headers (a
+    // half-merged pair of the two would send tokens to the wrong collector).
+    // Pinned by a merge-survival test in src/test/data_types.test.ts.
+    otel: v.optional(OTelConfigSchema),
 });
 /**
  * `spf watch`'s configuration. `issue_provider` (the tracker) and
@@ -289,8 +351,25 @@ export const ObservabilityConfigSchema = v.object({
  * watch` startup, not here — an empty string parses fine (this schema has
  * no opinion on whether watch is even configured), matching the same
  * "fails loudly before anything spawns, not eagerly at parse time" pattern
- * `quality:` already uses. Its shape depends on `code_host`: "owner/name"
- * for github, "workspace/repo_slug" for bitbucket.
+ * `quality:` already uses. `repo` always names `code_host`'s own repo —
+ * its shape depends on `code_host`: "owner/name" for github,
+ * "workspace/repo_slug" for bitbucket. `resolveCodeHostProvider`
+ * (`cli/commands/watch.ts`) always reads it.
+ *
+ * `issue_repo` exists for exactly one combination where that single field
+ * stops being enough: `issue_provider: github` with `code_host: bitbucket`
+ * — GitHub-issues-against-a-Bitbucket-repo, a real setup this project
+ * explicitly supports, where the issue tracker and the code host are
+ * genuinely different repos in different systems, not the same repo worn
+ * two ways. Every other combination stays a single field: `issue_provider:
+ * github` + `code_host: github` is one repo by construction; `issue_provider:
+ * jira` never reads `repo` at all (it uses `jira.base_url`/`project_key`),
+ * so `repo` unambiguously belongs to whichever code host is configured.
+ * `resolveIssueProvider`'s github branch and `core/refine.ts`'s
+ * `resolveAuthoringProvider` (issue authoring always targets the issue
+ * tracker, never the code host) both read `issue_repo || repo` — leaving
+ * `issue_repo` unset is a complete no-op, so no existing config needs to
+ * change.
  */
 export const WatchIssueProviderSchema = v.picklist(["github", "jira"]);
 export const WatchCodeHostSchema = v.picklist(["github", "bitbucket"]);
@@ -299,16 +378,33 @@ export const WatchJiraConfigSchema = v.object({
     base_url: v.optional(v.string(), ""), // e.g. "https://your-domain.atlassian.net"
     project_key: v.optional(v.string(), ""), // e.g. "PROJ"
 });
+/**
+ * The second `spf watch` lane: decompose a `<prefix>:spec-ready` product
+ * spec into a feature/story tree of real issues, instead of running
+ * `watch.chain` against it directly (a spec is not individually workable —
+ * see `core/refine.ts`). Off by default so an existing `watch:` config's
+ * behavior is unchanged by upgrading; turning it on with
+ * `issue_provider: jira` fails loudly at `spf watch` startup, since
+ * `JiraProvider` doesn't implement `IssueAuthoringProvider` (create/link)
+ * yet — see its module comment.
+ */
+export const WatchRefineConfigSchema = v.object({
+    enabled: v.optional(v.boolean(), false),
+    chain: v.optional(v.string(), "refine"),
+    concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 1),
+});
 export const WatchConfigSchema = v.object({
     issue_provider: v.optional(WatchIssueProviderSchema, "github"),
     code_host: v.optional(WatchCodeHostSchema, "github"),
     repo: v.optional(v.string(), ""),
+    issue_repo: v.optional(v.string(), ""),
     label_prefix: v.optional(v.string(), "spf"),
     chain: v.optional(v.string(), "plan-build-test"),
     base_branch: v.optional(v.string(), "main"),
     poll_ms: v.optional(v.number(), 60_000),
     concurrency: v.optional(v.pipe(v.number(), v.integer(), v.minValue(1)), 2),
     jira: v.optional(WatchJiraConfigSchema, () => v.parse(WatchJiraConfigSchema, {})),
+    refine: v.optional(WatchRefineConfigSchema, () => v.parse(WatchRefineConfigSchema, {})),
 });
 /**
  * Optional outbound push for unattended work (`spf watch`, any chain run) —
@@ -339,6 +435,33 @@ export const NotificationsConfigSchema = v.object({
     timeout_ms: v.optional(v.number(), 5_000),
     channels: v.optional(v.array(NotifyChannelSchema), () => []),
 });
+/**
+ * `simple_sdlc`'s human-signoff gate — see the ACCEPTED ADVERSARIAL
+ * AMENDMENTS on the review-accountability thread. `simple_sdlc.ts`'s
+ * `commit_build` predicate is the ONLY place in this codebase where an AI
+ * reviewer's `approved` flag gates a commit; `decideSignoff` (same file)
+ * turns that PROPOSAL into a human's DISPOSAL wherever a human is at the
+ * keyboard, and reads these two knobs when there isn't one.
+ *
+ * `require_human_signoff` defaults to FALSE for this release, deliberately:
+ * flipping it to fail-closed-by-default would break every unattended
+ * `simple-sdlc` run (`spf watch`, CI) the day this shipped, before `spf
+ * watch` itself is signoff-aware (its own human gate today is the PR merge,
+ * now informed by the reviewer digest — see `cli/commands/watch.ts`). An
+ * unattended run instead proceeds on the AI verdict alone with a LOUD
+ * one-time warning (`decideSignoff`'s `AI_ONLY_SIGNOFF_WARNING`) until that
+ * changes. Set `true` and an unattended run fails the phase CLOSED instead —
+ * see `decideSignoff`'s fail-closed branch — rather than silently
+ * auto-approving because nobody typed at a prompt that was never shown.
+ *
+ * `signoff_timeout_seconds` bounds the interactive prompt itself: expiry
+ * means NOT accepted (the confirm's own default), never an unbounded stdin
+ * read inside `run.phase()` — see `cli/ask.ts`'s `confirm(..., {timeoutMs})`.
+ */
+export const ReviewConfigSchema = v.object({
+    require_human_signoff: v.optional(v.boolean(), false),
+    signoff_timeout_seconds: v.optional(v.pipe(v.number(), v.minValue(1)), 300),
+});
 export const SFConfigSchema = v.object({
     defaults: v.optional(ConfigDefaultsSchema, () => v.parse(ConfigDefaultsSchema, {})),
     observability: v.optional(ObservabilityConfigSchema, () => v.parse(ObservabilityConfigSchema, {})),
@@ -346,7 +469,23 @@ export const SFConfigSchema = v.object({
     quality: v.optional(QualityConfigSchema, () => v.parse(QualityConfigSchema, {})),
     watch: v.optional(WatchConfigSchema, () => v.parse(WatchConfigSchema, {})),
     notifications: v.optional(NotificationsConfigSchema, () => v.parse(NotificationsConfigSchema, {})),
+    review: v.optional(ReviewConfigSchema, () => v.parse(ReviewConfigSchema, {})),
 });
+// ── Tracing ──────────────────────────────────────────────────────────────────
+/** The full set of event kinds any tracer.event()/makeEventRecord() call site emits — kept in sync with src/ui/shared/types.ts's EventType. */
+export const EVENT_RECORD_TYPES = [
+    "phase_start",
+    "agent_start",
+    "tool_call",
+    "handoff",
+    "gate_pass",
+    "gate_fail",
+    "log",
+    "agent_end",
+    "phase_end",
+    "error",
+];
+export const EventRecordTypeSchema = v.picklist(EVENT_RECORD_TYPES);
 export function makeEventRecord(input) {
     return {
         phase_id: "",

package/dist/core/gates.d.ts

@@ -29,5 +29,18 @@ export declare function diffMatchesClaims(envelope: EnvelopeBase, run: RunContex
  * reading a line of the diff.
  */
 export declare function verdictConsistent(envelope: EnvelopeBase, _run: RunContext): GateReport;
+/**
+ * The gate that turns `to-tickets`' flat, untyped ticket list into an
+ * actually-enforced feature/story-or-bug tree — see `RefinedIssueSchema`'s
+ * doc comment in `data_types.ts`. Checks the envelope's `issues` list
+ * against itself, never anything already published: `core/refine.ts` never
+ * gets a chance to publish a malformed tree in the first place, because a
+ * violation here re-prompts the SAME refiner session before `steps.refine()`
+ * ever hands off to `steps.publishIssues()`.
+ *
+ * "Container" and "leaf" are derived from the graph, not asserted by the
+ * agent: a node is a container iff some other node names it as `parent`.
+ */
+export declare function refinementWellFormed(envelope: EnvelopeBase, _run: RunContext): GateReport;
 /** Gate factory: the given shell command must exit 0, run from run.repo_root. */
 export declare function testsPass(command: string): GateFn;

package/dist/core/gates.js

@@ -128,6 +128,109 @@ export function verdictConsistent(envelope, _run) {
         : "approved=false but no blocking item or unmet requirement was given");
     return report;
 }
+const CONTAINER_KINDS = new Set(["epic", "feature"]);
+const LEAF_KINDS = new Set(["story", "bug", "task"]);
+/**
+ * The gate that turns `to-tickets`' flat, untyped ticket list into an
+ * actually-enforced feature/story-or-bug tree — see `RefinedIssueSchema`'s
+ * doc comment in `data_types.ts`. Checks the envelope's `issues` list
+ * against itself, never anything already published: `core/refine.ts` never
+ * gets a chance to publish a malformed tree in the first place, because a
+ * violation here re-prompts the SAME refiner session before `steps.refine()`
+ * ever hands off to `steps.publishIssues()`.
+ *
+ * "Container" and "leaf" are derived from the graph, not asserted by the
+ * agent: a node is a container iff some other node names it as `parent`.
+ */
+export function refinementWellFormed(envelope, _run) {
+    const report = new GateReport();
+    const issues = envelope.issues ?? [];
+    if (issues.length === 0) {
+        report.check("issues", false, "a refinement produced no issues at all — decompose the spec into at least one leaf");
+        return report;
+    }
+    const byKey = new Map();
+    for (const issue of issues) {
+        if (byKey.has(issue.key)) {
+            report.check(`key ${JSON.stringify(issue.key)}`, false, "duplicate key — every node needs a unique key within this refinement");
+        }
+        else {
+            byKey.set(issue.key, issue);
+        }
+    }
+    const childKeys = new Set(); // keys named as some OTHER node's parent -> that node is a container
+    for (const issue of issues) {
+        if (!issue.parent)
+            continue;
+        if (!byKey.has(issue.parent)) {
+            report.check(`${issue.key}.parent`, false, `parent ${JSON.stringify(issue.parent)} does not match any issue's key`);
+            continue;
+        }
+        childKeys.add(issue.parent);
+    }
+    for (const issue of issues) {
+        for (const blocker of issue.blocked_by) {
+            if (!byKey.has(blocker)) {
+                report.check(`${issue.key}.blocked_by`, false, `blocked_by ${JSON.stringify(blocker)} does not match any issue's key`);
+            }
+        }
+    }
+    // Cycle check over the union of parent + blocked_by edges — both mean
+    // "must exist before this node" from core/refine.ts's own topological
+    // publish order, so a cycle in either (or across both) would hang it.
+    const WHITE = 0;
+    const GRAY = 1;
+    const BLACK = 2;
+    const color = new Map();
+    let cyclic = false;
+    const edgesFrom = (key) => {
+        const issue = byKey.get(key);
+        if (!issue)
+            return [];
+        const out = [];
+        if (issue.parent && byKey.has(issue.parent))
+            out.push(issue.parent);
+        for (const b of issue.blocked_by)
+            if (byKey.has(b))
+                out.push(b);
+        return out;
+    };
+    const visit = (key) => {
+        if (cyclic)
+            return;
+        color.set(key, GRAY);
+        for (const next of edgesFrom(key)) {
+            const c = color.get(next) ?? WHITE;
+            if (c === GRAY) {
+                cyclic = true;
+                return;
+            }
+            if (c === WHITE)
+                visit(next);
+        }
+        color.set(key, BLACK);
+    };
+    for (const issue of issues) {
+        if ((color.get(issue.key) ?? WHITE) === WHITE)
+            visit(issue.key);
+    }
+    report.check("dependency graph", !cyclic, cyclic ? "parent/blocked_by edges form a cycle — nothing to publish first" : "acyclic");
+    for (const issue of issues) {
+        const isContainer = childKeys.has(issue.key);
+        if (isContainer && !CONTAINER_KINDS.has(issue.kind)) {
+            report.check(`${issue.key}.kind`, false, `has children but kind is ${JSON.stringify(issue.kind)} — a container must be "epic" or "feature"`);
+        }
+        else if (!isContainer && !LEAF_KINDS.has(issue.kind)) {
+            report.check(`${issue.key}.kind`, false, `has no children but kind is ${JSON.stringify(issue.kind)} — a leaf must be "story", "bug", or "task"`);
+        }
+        else {
+            report.check(`${issue.key}.kind`, true, isContainer ? "container" : "leaf");
+        }
+    }
+    const leafCount = issues.filter((i) => !childKeys.has(i.key)).length;
+    report.check("has leaves", leafCount > 0, leafCount > 0 ? `${leafCount} leaf issue(s)` : "every node is a container — nothing here is independently workable");
+    return report;
+}
 /** Gate factory: the given shell command must exit 0, run from run.repo_root. */
 export function testsPass(command) {
     const gate = (_envelope, run) => {