specfuse-loop 0.3.7__tar.gz → 0.3.9__tar.gz

{specfuse_loop-0.3.7/specfuse_loop.egg-info → specfuse_loop-0.3.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: specfuse-loop
-Version: 0.3.7
+Version: 0.3.9
 Summary: Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology.
 Author: Specfuse contributors
 License: Apache-2.0

{specfuse_loop-0.3.7 → specfuse_loop-0.3.9}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "specfuse-loop"
-version = "0.3.7"
+version = "0.3.9"
 description = "Local-first executor for the Specfuse Plan + Work Unit gate-cycle methodology."
 readme = "README.md"
 requires-python = ">=3.10"

specfuse_loop-0.3.9/specfuse/loop/data/VERSION

@@ -0,0 +1 @@
+0.3.9

{specfuse_loop-0.3.7 → specfuse_loop-0.3.9}/specfuse/loop/data/rules/correlation-ids.md

@@ -10,9 +10,9 @@ feature folder, the WU file, the event log, the branch, and the commit history.
 This rule defines the format, the surfaces the ID must appear on, how the next ID
 is chosen, and what to do when you see — or are about to produce — a malformed one.
 
-[`docs/methodology.md`](../../docs/methodology.md) §1 is normative on the
-correlation-ID scheme; this file is the operational reference every session reads
-before emitting an ID.
+`methodology.md` §1 (the gate-cycle canonical, in this shared substrate set) is
+normative on the correlation-ID scheme; this file is the operational reference
+every session reads before emitting an ID.
 
 ## Format
 
@@ -192,6 +192,6 @@ any downstream tooling filter and join on these IDs; a typo breaks the thread.
   feature crosses a calendar boundary.
 
 When you detect a malformed ID in your own work in progress, fix it before reporting.
-When you detect one in an artifact that is already committed, emit
-`status: blocked` rather than silently rewriting history — the
-[result-contract](result-contract.md) discipline applies here too.
+When you detect one in an artifact that is already committed, signal blocked
+rather than silently rewriting history — the
+[verification-discipline](verification-discipline.md) applies here too.

{specfuse_loop-0.3.7 → specfuse_loop-0.3.9}/specfuse/loop/data/rules/never-touch.md

@@ -8,9 +8,10 @@ Licensed under the Apache License, Version 2.0. See LICENSE.
 Three categories of path are off-limits to every work-unit session, regardless of
 unit type. If a unit's acceptance criteria or verification commands appear to
 require modifying something in this list, that is an escalation condition, not a
-license to proceed — emit `status: blocked` per
-[`result-contract.md`](result-contract.md) with a `blocked_reason` naming the
-boundary.
+license to proceed — signal blocked per
+[`verification-discipline.md`](verification-discipline.md), naming the
+boundary. (How "blocked" is signalled is surface-specific — a `status: blocked`
+RESULT on the loop, a `blocked_*` transition on the orchestrator.)
 
 ## 1. Generated code directories
 
@@ -29,7 +30,7 @@ leaves no trace of why.
 
 When a generated file is wrong, the response is to change the spec or the generator
 that produced it, not the file itself. If that is outside this unit's boundary,
-emit `status: blocked` with the spec/generator change named.
+signal blocked with the spec/generator change named.
 
 ## 2. Secrets and credentials
 
@@ -53,9 +54,10 @@ You must not:
 
 ## 3. `.git/` internals
 
-The `.git/` directory is the repository's internal state. The driver owns all git
-operations for work units (see [`result-contract.md`](result-contract.md) rule 1);
-you do not run `git` at all. Beyond that, never write under `.git/` directly:
+The `.git/` directory is the repository's internal state. On the loop surface the
+driver owns all git operations for work units and the session does not run `git`
+at all; on the orchestrator surface an agent may use `git`/`gh` within its unit's
+scope. Either way, never write under `.git/` directly:
 
 - No edits to `.git/hooks/*` to bypass checks. If a hook is failing, the right
   response is to diagnose the underlying issue.
@@ -77,5 +79,5 @@ response to a failing gate is to fix what it is flagging, not to silence it.
 Before writing to any path, confirm it is not in one of the three categories above.
 If you are uncertain whether a path is "generated" or "hand-written," the repo's
 declaration is authoritative; if the declaration is missing or ambiguous, treat
-the path as generated and emit `status: blocked` rather than write. Silence at a
+the path as generated and signal blocked rather than write. Silence at a
 boundary is not permission.

{specfuse_loop-0.3.7 → specfuse_loop-0.3.9}/specfuse/loop/data/rules/result-contract.md

@@ -18,6 +18,13 @@ wastes an attempt and teaches the next session nothing.
 
 ## The four-step discipline
 
+This contract is the loop-surface expression of the neutral
+[`verification-discipline.md`](verification-discipline.md) rule (vendored from the
+Specfuse methodology core): it extends that rule's **state intent → act → verify →
+report** cycle with the loop's concrete RESULT-block shape and status vocabulary.
+The neutral rule is normative on *what* the discipline requires; this file is
+normative on *how* the loop surface reports it.
+
 Every session operates on the same cycle: **state intent, act, verify, report.** The
 RESULT block is step 4, but it is only trustworthy when steps 1–3 ran first.
 

{specfuse_loop-0.3.7 → specfuse_loop-0.3.9}/specfuse/loop/data/rules/security-boundaries.md

@@ -25,8 +25,7 @@ anything conventionally treated as a credential (see the enumeration in
   This applies whether the value came from a real secret or was constructed.
 - **Never commit.** Secrets files are excluded from commits categorically. A
   `.env` in your working directory is a mistake; remove it before the driver
-  commits, not after. If you discover a secret already committed, emit
-  `status: blocked` immediately — do not attempt history rewriting.
+  commits, not after. If you discover a secret already committed, signal blocked immediately — do not attempt history rewriting.
 - **Reference by name, not by value.** When a command needs a secret, pass it via
   an environment variable reference (`$GITHUB_TOKEN`) rather than substituting
   the value into the command line. Do not expand secret variables into log output;
@@ -51,15 +50,15 @@ is almost always a unit-definition problem, not a license to break the rule.
 2. **Re-read the unit.** Verify you have understood the step correctly. Often the
    unit describes how the *human* will verify, with the session doing an
    upstream-only step.
-3. **If the requirement is genuine, escalate via the RESULT block.** Emit
-   `status: blocked` with a precise `blocked_reason` naming the privilege
-   required (e.g., "verification command requires reading
-   `config/db-prod.env`"). The driver halts the gate and the human decides
-   whether to adjust the unit, run the step out-of-band, or provide a scoped
-   credential.
+3. **If the requirement is genuine, signal blocked.** Name the privilege
+   required (e.g., "verification command requires reading `config/db-prod.env`")
+   as the blocked reason. Work halts and the human decides whether to adjust the
+   unit, run the step out-of-band, or provide a scoped credential. (The signal is
+   surface-specific — a `status: blocked` RESULT on the loop, a `blocked_*`
+   transition on the orchestrator.)
 4. **Do not report the unit complete.** A verification that could not be run is
    not a verification; a unit whose verification cannot be run is not done (see
-   [`result-contract.md`](result-contract.md)).
+   [`verification-discipline.md`](verification-discipline.md)).
 
 The common mistake here is to "helpfully" substitute a weaker check for a
 privileged one — "I couldn't run the secret-requiring command, so I inspected the
@@ -76,7 +75,7 @@ yours, and you are not expected to inspect or transmit them. The prohibition is
 unit's scope* — not on using a credentialed tool to do the work the unit names.
 
 If an authenticated tool returns an error that implies a credential problem
-(expired token, permission denied, 401/403), stop and emit `status: blocked`. Do
+(expired token, permission denied, 401/403), stop and signal blocked. Do
 not attempt to re-authenticate, reconfigure the credential, or swap accounts.
 
 ## Log hygiene

specfuse_loop-0.3.9/specfuse/loop/data/rules/verification-discipline.md

@@ -0,0 +1,81 @@
+<!--
+Copyright 2026 Specfuse Contributors
+Licensed under the Apache License, Version 2.0. See LICENSE.
+-->
+
+# Rule: the verification discipline
+
+Every unit of work runs the same four-step cycle: **state intent, act, verify,
+report.** This is the surface-neutral core of the discipline. Each execution
+surface expresses step 4 (report) in its own shape — the loop's RESULT block, the
+orchestrator's `task_completed` event — but the cycle, and the honesty it demands,
+are identical everywhere. This rule is core substrate; the surface-specific report
+shapes (`result-contract.md` on the loop, `verify-before-report.md` on the
+orchestrator) build on it and must not weaken it.
+
+## The four steps
+
+### 1. State intent
+Before acting, state in one sentence what you are about to do and why it is the
+next right step. If you cannot state it clearly, you are not ready to act; if the
+intent disagrees with the unit's acceptance criteria, the unit is not what you
+thought it was. Stay factual and present-tense.
+
+### 2. Act
+Perform the change within the scope declared in step 1. If the act expands beyond
+the intent — "while I was here I also fixed X" — either revise the intent and
+stay, or stop and leave X for another unit. Drift between intent and action is the
+most common source of ambiguous diffs. The unit's **Do not touch** boundary is
+binding.
+
+### 3. Verify
+Two generic meanings, both apply unless the unit narrows the scope:
+
+- **Re-read the produced artifact.** After writing a file, read it back; after
+  editing a fixture, inspect the result. The Write/Edit tool reports success for
+  the action it took, not for the property you wanted. This catches silent
+  truncation, encoding surprises, and "I thought I wrote X but wrote Y."
+- **Run the declared verification commands.** The unit names the checks that
+  decide done. Run them yourself first, in declared order, with full output.
+  Generic verifications — "I assume the tests still pass" — are not verifications.
+  The commands are the verification.
+
+**Verification is the exit oracle.** The agent's own report is advisory; done is
+decided by the checks passing, not by the agent's belief. If a check fails you are
+in one of three situations:
+
+1. **Correctable locally.** Fix the cause, re-run the **full** check set from the
+   top, then continue. A re-run that fixes the original failure but introduces a
+   new one is still a failed cycle.
+2. **Spinning threshold reached** (typically three fresh attempts on one unit).
+   Signal blocked with precise evidence rather than spending the cycle guessing.
+3. **Fundamentally blocked.** A spec ambiguity, generated code that must change, a
+   missing dependency — signal blocked immediately, naming the boundary.
+
+### 4. Report
+Report only what verification confirmed. An optimistic report is worse than none:
+the driver (or merge gate) re-runs the checks, discovers the gap, the attempt is
+wasted, and the next session inherits no useful evidence about why. The concrete
+report shape is surface-specific — see `result-contract.md` (loop RESULT block) or
+`verify-before-report.md` (orchestrator event). Both carry the same obligation:
+no claim of completion without the verification evidence behind it.
+
+## Blocked is a respectable outcome
+
+Signalling blocked after one honest attempt is cheaper than three fresh attempts
+chasing a completion the checks keep rejecting. When an escalation trigger fires,
+or a unit's acceptance criteria appear to require crossing a boundary named in
+`never-touch.md` or `security-boundaries.md`, **stop and signal blocked with a
+precise reason naming the boundary** — do not work around it. Silence at a
+boundary is not permission. How "blocked" is signalled is surface-specific (a
+`status: blocked` RESULT on the loop; a `blocked_*` state transition plus
+escalation on the orchestrator); the obligation to stop rather than improvise is
+core.
+
+## Honesty over optimism
+
+The whole coordination model runs on the report being an honest claim about what
+happened. When a session skips verification, the cost is not its own — it is paid
+by the next session that inherits a broken assumption, the driver that wastes
+attempts, and the human who reviews evidence that turns out to be wrong. State
+intent. Act. Verify. Report. Every time.

specfuse_loop-0.3.9/specfuse/loop/data/schemas/event.schema.json

@@ -0,0 +1,78 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specfuse.dev/orchestrator/schemas/event.schema.json",
+  "title": "Event log entry",
+  "$comment": "Additive history (WU 2.14, F2.4): Phase 1 baseline enum — feature_created, spec_validated, task_graph_drafted, plan_ready, plan_generated, plan_approved, task_created, task_ready, task_started, task_completed, task_blocked, spec_issue_raised, override_applied, override_expired, human_escalation. Phase 2 additions: template_coverage_checked (WU 2.6), feature_state_changed (WU 2.9). Phase 3 additions: test_plan_authored (WU 3.2), qa_execution_completed + qa_execution_failed (WU 3.3), qa_regression_filed + qa_regression_resolved + escalation_resolved (WU 3.4; escalation_resolved is substrate — resolution_kind discriminator, first application retires the Phase 2 orphan inbox file FEAT-2026-0005-plan-review-cycle.md; closes carry-item F2.10), regression_suite_curated (WU 3.5; emitted by the qa-curation skill on curation-PR merge; envelope correlation_id task-level on the qa_curation task; affected_feature_correlation_ids in payload carries the cross-feature fanout). Phase 4 additions: spec_issue_resolved + spec_issue_routed (WU 4.5; emitted by the specs agent's spec-issue-triage skill — spec_issue_resolved when a spec-content fix is applied in /product/, spec_issue_routed when the issue is filed against the generator project). Per-type payload schemas for these types live under shared/schemas/events/. NOTE: plan_reingested was considered in WU 2.14 but deliberately not added — WU 2.11's template_coverage_checked re-chain on every Phase B success already makes Phase B observable in the event log. Reframe migration (docs/naming-convention.md, additive): correlation_id pattern widened from ^FEAT-\\d{4}-\\d{4}(/T\\d{2})?$ to ^(FEAT|INIT)-\\d{4}-\\d{4}(/F\\d{2})?(/T\\d{2})?$ to carry the initiative/feature/work-unit hierarchy (INIT-YYYY-NNNN[/FNN][/TNN]) alongside the legacy/component-local FEAT- forms; existing FEAT- entries validate unchanged. Per-type payload schemas under events/ broadened their FEAT-only correlation/path patterns the same way.",
+  "description": "A single JSONL entry in a feature's event log. Event log semantics are defined in orchestrator-architecture.md §7.3.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "timestamp",
+    "correlation_id",
+    "event_type",
+    "source",
+    "source_version",
+    "payload"
+  ],
+  "properties": {
+    "timestamp": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 timestamp with timezone offset (e.g. 2026-04-20T14:32:05Z or 2026-04-20T10:32:05-04:00).",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d+)?(Z|[+-]\\d{2}:\\d{2})$"
+    },
+    "correlation_id": {
+      "type": "string",
+      "description": "Correlation ID at any level of the unit hierarchy (docs/naming-convention.md): initiative INIT-YYYY-NNNN, dispatched feature INIT-YYYY-NNNN/FNN, work unit INIT-YYYY-NNNN/FNN/TNN; or the legacy/component-local feature FEAT-YYYY-NNNN and task FEAT-YYYY-NNNN/TNN. Existing FEAT- entries validate unchanged.",
+      "pattern": "^(FEAT|INIT)-\\d{4}-\\d{4}(/F\\d{2})?(/T\\d{2})?$"
+    },
+    "event_type": {
+      "type": "string",
+      "description": "Minimum event type set from architecture §7.3. New types must be registered in this schema before use.",
+      "enum": [
+        "initiative_created",
+        "feature_created",
+        "spec_validated",
+        "feature_graph_drafted",
+        "task_graph_drafted",
+        "template_coverage_checked",
+        "plan_ready",
+        "plan_generated",
+        "plan_approved",
+        "task_created",
+        "task_ready",
+        "task_started",
+        "task_completed",
+        "task_blocked",
+        "spec_issue_raised",
+        "override_applied",
+        "override_expired",
+        "human_escalation",
+        "feature_state_changed",
+        "test_plan_authored",
+        "qa_execution_completed",
+        "qa_execution_failed",
+        "qa_regression_filed",
+        "qa_regression_resolved",
+        "escalation_resolved",
+        "regression_suite_curated",
+        "spec_issue_resolved",
+        "spec_issue_routed"
+      ]
+    },
+    "source": {
+      "type": "string",
+      "description": "Emitter of the event: a fixed role (`specs`, `pm`, `qa`, `config-steward`, `merge-watcher`), the loop's single-repo `driver`, a component agent scoped by repo (`component:<name>`), or `human`. The `driver` value is the loop execution surface's sole emitter (single-repo gate-cycle); the orchestrator surface uses the role-scoped values. For `component:<name>`, `<name>` is the bare component repository name with no owner prefix — the short form of the git remote (e.g. `component:api-sample`, not `component:acme/api-sample`). This matches the `source: component:<repo>` convention used across roles; the PM and QA agents emit events with `source: pm` and `source: qa` respectively (no repo suffix, since those roles are not scoped by component repo).",
+      "pattern": "^(human|driver|specs|pm|qa|config-steward|merge-watcher|component:[a-z0-9][a-z0-9-]*)$"
+    },
+    "source_version": {
+      "type": "string",
+      "description": "Agent configuration version in effect when the event was emitted. Format is semver-like but not enforced here; `human` events use the orchestration repo commit SHA or `n/a`.",
+      "minLength": 1
+    },
+    "payload": {
+      "type": "object",
+      "description": "Event-specific structured content. Per-type payload schemas will be added under /shared/schemas/events/ as they stabilize."
+    }
+  }
+}

specfuse_loop-0.3.9/specfuse/loop/data/schemas/events/initiative_created.schema.json

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specfuse.dev/orchestrator/schemas/events/initiative_created.schema.json",
+  "title": "initiative_created event payload",
+  "$comment": "Provenance: authored for the Model-B reframe (docs/naming-convention.md) as the initiative-level counterpart of feature_created. Emitted by the specs agent's initiative-intake skill (renamed from feature-intake) when a new INITIATIVE registry entry is created. Fields mirror feature_created with initiative_title in place of feature_title and an INIT-YYYY-NNNN correlation ID. feature_created is retained for legacy/feature-level use.",
+  "description": "Payload shape for the `initiative_created` event emitted by the specs agent during initiative intake. Captures the human-provided inputs (title, repos, autonomy) alongside the minted initiative correlation ID, duplicated from the envelope for payload self-containment.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "initiative_title",
+    "involved_repos",
+    "autonomy_default",
+    "correlation_id"
+  ],
+  "properties": {
+    "initiative_title": {
+      "type": "string",
+      "description": "Human-provided title for the initiative. Free-form prose; used in the initiative registry's Description header. Not a machine identifier — the correlation ID is the stable reference.",
+      "minLength": 1
+    },
+    "involved_repos": {
+      "type": "array",
+      "description": "Component repositories this initiative spans, as `owner/repo` strings. Mirrors the `involved_repos` frontmatter field at creation time.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "autonomy_default": {
+      "type": "string",
+      "description": "Initiative-level autonomy default chosen by the human at intake. One of `auto`, `review`, or `supervised`.",
+      "enum": ["auto", "review", "supervised"]
+    },
+    "correlation_id": {
+      "type": "string",
+      "description": "The initiative-level correlation ID minted during intake (INIT-YYYY-NNNN). Matches the envelope `correlation_id` and the registry filename. Duplicated here for payload self-containment.",
+      "pattern": "^INIT-\\d{4}-\\d{4}$"
+    }
+  }
+}

specfuse_loop-0.3.9/specfuse/loop/data/schemas/events/spec_issue_resolved.schema.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specfuse.dev/orchestrator/schemas/events/spec_issue_resolved.schema.json",
+  "title": "spec_issue_resolved event payload",
+  "$comment": "Provenance: authored 2026-04-25 in WU 4.5 (spec-issue-triage skill). Fields: original_issue_correlation_id (required, task-level FEAT-YYYY-NNNN/TNN — the correlation ID from the triggering task that filed the spec issue), affected_files (required, array of paths edited in /product/ to resolve the issue), resolution_summary (required, string describing what was fixed and why). Emitted by the specs agent after fixing a spec-content problem in /product/ and re-validating the affected spec. The event type is new in Phase 4; per-type schema is authored alongside.",
+  "description": "Payload shape for the `spec_issue_resolved` event emitted by the specs agent's spec-issue-triage skill when a spec issue filed by a downstream agent (component, QA) is resolved by editing spec content under `/product/`. The resolution is a spec-side fix — the specs agent edits the affected spec file, re-validates, and emits this event. The original inbox file is archived to `/inbox/spec-issue/processed/`, never deleted.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "original_issue_correlation_id",
+    "affected_files",
+    "resolution_summary"
+  ],
+  "properties": {
+    "original_issue_correlation_id": {
+      "type": "string",
+      "description": "The task-level correlation ID from the triggering task that filed the spec issue (e.g. `FEAT-2026-0042/T09`). Links the resolution event back to the original `spec_issue_raised` event and the downstream task that discovered the problem. This is the task-level ID, not the feature-level ID, because spec issues are raised in the context of a specific task's work.",
+      "pattern": "^((FEAT-\\d{4}-\\d{4})|(INIT-\\d{4}-\\d{4}/F\\d{2}))/T\\d{2}$"
+    },
+    "affected_files": {
+      "type": "array",
+      "description": "Paths of spec files edited under `/product/` to resolve the issue, relative to the product specs repo root (e.g. `product/specs/inventory-api-bookmarks.yaml`). At least one file must be affected — a resolution that touches no files is not a resolution.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1,
+      "uniqueItems": true
+    },
+    "resolution_summary": {
+      "type": "string",
+      "description": "Human-readable summary of what was fixed and why. States the concrete change (e.g. 'Changed response status from 201 to 200 for the idempotent repeat case on POST /bookmarks') — enough for downstream agents and the human to understand the fix without re-reading the diff.",
+      "minLength": 1
+    }
+  }
+}

specfuse_loop-0.3.9/specfuse/loop/data/schemas/events/spec_issue_routed.schema.json

@@ -0,0 +1,31 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specfuse.dev/orchestrator/schemas/events/spec_issue_routed.schema.json",
+  "title": "spec_issue_routed event payload",
+  "$comment": "Provenance: authored 2026-04-25 in WU 4.5 (spec-issue-triage skill). Fields: original_issue_correlation_id (required, task-level FEAT-YYYY-NNNN/TNN — the correlation ID from the triggering task that filed the spec issue), target_project (required, owner/repo of the generator project the issue was filed against), filed_issue_reference (required, GitHub issue reference in owner/repo#N format). Emitted by the specs agent after determining a spec issue is a generator-template problem and filing a GitHub issue against the generator project. The event type is new in Phase 4; per-type schema is authored alongside.",
+  "description": "Payload shape for the `spec_issue_routed` event emitted by the specs agent's spec-issue-triage skill when a spec issue filed by a downstream agent (component, QA) is determined to be a generator-template problem rather than a spec-content problem. The specs agent files a GitHub issue against the generator project and emits this event. The original inbox file is archived to `/inbox/spec-issue/processed/`, never deleted. The generator feedback loop (Phase 5) will consume these issues; Phase 4 only files them.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "original_issue_correlation_id",
+    "target_project",
+    "filed_issue_reference"
+  ],
+  "properties": {
+    "original_issue_correlation_id": {
+      "type": "string",
+      "description": "The task-level correlation ID from the triggering task that filed the spec issue (e.g. `FEAT-2026-0042/T09`). Links the routing event back to the original `spec_issue_raised` event and the downstream task that discovered the problem.",
+      "pattern": "^((FEAT-\\d{4}-\\d{4})|(INIT-\\d{4}-\\d{4}/F\\d{2}))/T\\d{2}$"
+    },
+    "target_project": {
+      "type": "string",
+      "description": "The GitHub `owner/repo` identifier of the generator project the issue was filed against (e.g. `acme/specfuse-generator`). Identifies which project owns the template that needs fixing.",
+      "pattern": "^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+$"
+    },
+    "filed_issue_reference": {
+      "type": "string",
+      "description": "The GitHub issue reference for the filed generator issue, in `owner/repo#N` format (e.g. `acme/specfuse-generator#42`). This is the durable reference that the generator feedback loop (Phase 5) will track.",
+      "pattern": "^[a-zA-Z0-9_.-]+/[a-zA-Z0-9_.-]+#\\d+$"
+    }
+  }
+}

specfuse_loop-0.3.9/specfuse/loop/data/schemas/events/spec_validated.schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://specfuse.dev/orchestrator/schemas/events/spec_validated.schema.json",
+  "title": "spec_validated event payload",
+  "$comment": "Provenance: authored 2026-04-25 in WU 4.4 (spec-validation skill). Fields: feature_correlation_id (required, FEAT-YYYY-NNNN), pass (required, boolean), spec_files_checked (required, array of paths), errors (required, array of structured error objects — empty on pass), validator_version (required, string). The spec_validated event type has existed in event.schema.json since the Phase 1 baseline; this per-type schema is additive, preserving the Phase 1 freeze contract.",
+  "description": "Payload shape for the `spec_validated` event emitted by the specs agent on every validation run (pass or fail). The event is append-only: re-validation after a fix produces a new `spec_validated` event; prior failures are preserved in the event log. Consumers use the most recent `spec_validated` event to determine current validation status. The `errors` array is empty on a clean pass and populated with structured error objects on failure — each object carries enough context (file, line, message, severity) for the spec-validation skill to produce actionable remediation guidance without the human needing to consult raw validator output.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "feature_correlation_id",
+    "pass",
+    "spec_files_checked",
+    "errors",
+    "validator_version"
+  ],
+  "properties": {
+    "feature_correlation_id": {
+      "type": "string",
+      "description": "The feature-level correlation ID of the feature whose specs were validated. Duplicated from the envelope `correlation_id` for payload self-containment — downstream consumers that index payloads without re-reading the envelope benefit from the redundancy.",
+      "pattern": "^(FEAT|INIT)-\\d{4}-\\d{4}(/F\\d{2})?$"
+    },
+    "pass": {
+      "type": "boolean",
+      "description": "True if all spec files passed validation with zero errors (warnings do not block); false if any file produced at least one error-severity finding."
+    },
+    "spec_files_checked": {
+      "type": "array",
+      "description": "Paths of every spec file the validator checked, relative to the product specs repo root (e.g. `product/specs/inventory-api-bookmarks.yaml`, `product/features/FEAT-2026-0042.md`). Order matches the order the validator processed them. At least one file must be checked — a validation run against zero files is a configuration error, not a pass.",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1
+    },
+    "errors": {
+      "type": "array",
+      "description": "Structured error objects from the validator. Empty array when `pass` is true; at least one element when `pass` is false. Each object identifies the file, line, raw message, and severity of the finding. The spec-validation skill's interpretation table translates each raw message into actionable remediation guidance for the human.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "file",
+          "line",
+          "message",
+          "severity"
+        ],
+        "properties": {
+          "file": {
+            "type": "string",
+            "description": "Path of the spec file that produced this error, relative to the product specs repo root.",
+            "minLength": 1
+          },
+          "line": {
+            "type": "integer",
+            "description": "Line number in the spec file where the error was detected. 0 when the validator does not report line-level granularity for this error type (e.g. a missing top-level field, a cross-file reference error).",
+            "minimum": 0
+          },
+          "message": {
+            "type": "string",
+            "description": "The validator's raw error message. Preserved verbatim for audit — the spec-validation skill interprets this into human-readable guidance but keeps the original for traceability.",
+            "minLength": 1
+          },
+          "severity": {
+            "type": "string",
+            "description": "Severity level reported by the validator. `error` blocks validation (causes `pass: false`); `warning` is advisory and does not block — the validation can still pass with warnings.",
+            "enum": ["error", "warning"]
+          }
+        }
+      }
+    },
+    "validator_version": {
+      "type": "string",
+      "description": "Version string of the Specfuse validator used for this run (e.g. `1.0.0`). Captured at invocation time via the validator's version-reporting mechanism, not cached across runs or eye-read from a config file.",
+      "minLength": 1
+    }
+  }
+}

{specfuse_loop-0.3.7 → specfuse_loop-0.3.9}/specfuse/loop/loop.py

@@ -62,7 +62,7 @@ SPECFUSE_DIR = Path(".specfuse")
 REPO_ROOT = SPECFUSE_DIR.parent
 FEATURES_DIR = SPECFUSE_DIR / "features"
 VERIFICATION_PATH = SPECFUSE_DIR / "verification.yml"
-DRIVER_VERSION = "0.3.7"
+DRIVER_VERSION = "0.3.9"
 # Oldest scaffold layout this driver can drive. init.sh stamps the scaffold's own
 # version into `.specfuse/VERSION`; check_scaffold_version() fails loud at startup if
 # the consumer's scaffold is older than this, pointing at `specfuse upgrade`. Bump
@@ -880,8 +880,19 @@ def prepare_feature(feat_fm: dict, feature_dir: "Path", feature_id: str) -> None
     """
     branch = feat_fm.get("branch")
     ensure_feature_branch(feat_fm, feature_dir)
-    git("add", "--", str(feature_dir))
-    staged = git("status", "--porcelain", "--", str(feature_dir))
+    # Stage the feature folder AND the roadmap surfaces draft-feature wrote but
+    # left uncommitted (#127). The roadmap row is part of the feature's initial
+    # state; if it isn't folded into this scaffold commit, the first WU's
+    # per-attempt `git reset --hard head_before` discards it and terminal close
+    # fails with roadmap_row_not_done ~20 minutes later. ensure_feature_branch
+    # has already vetted the dirty set down to the expected /pick-feature flips.
+    repo_root = Path(git("rev-parse", "--show-toplevel"))
+    add_paths = [str(feature_dir)]
+    for rel in (".specfuse/roadmap.md", ".specfuse/roadmap-archive.md"):
+        if (repo_root / rel).exists():
+            add_paths.append(str(repo_root / rel))
+    git("add", "--", *add_paths)
+    staged = git("status", "--porcelain", "--", *add_paths)
     if staged:
         git("commit", "-m", f"chore: scaffold feature {feature_id}")
         print(f"Prepared: committed feature folder on branch '{branch}'.")
@@ -2927,7 +2938,12 @@ def assert_terminal_flips_fired(
     if not parsed:
         return (
             False,
-            f"roadmap_row_not_done: row for {feature_id} not found",
+            f"roadmap_row_not_done: row for {feature_id} not found in "
+            f"{roadmap_path}. /draft-feature writes this row but leaves it "
+            f"uncommitted; if it was dropped before dispatch, restore it and "
+            f"re-commit. `specfuse-loop --prepare` folds the row into the "
+            f"scaffold commit — dispatch through it so the row survives the "
+            f"per-attempt reset.",
         )
     row_status = parsed["columns"].get("Status", "").strip()
     if row_status != "done":

{specfuse_loop-0.3.7 → specfuse_loop-0.3.9}/specfuse/loop/scaffold.py

@@ -164,6 +164,7 @@ _RULES_BLOCK = (
     "@.specfuse/rules/correlation-ids.md\n"
     "@.specfuse/rules/never-touch.md\n"
     "@.specfuse/rules/security-boundaries.md\n"
+    "@.specfuse/rules/verification-discipline.md\n"
 )
 
 _RULES_SENTINEL = "@.specfuse/rules/result-contract.md"
@@ -304,7 +305,7 @@ def _parse_version(v: str) -> tuple[int, int, int]:
 
 
 # Seed relpaths overlaid verbatim into .specfuse/<relpath> on upgrade
-_VERSIONED_OVERLAY_PREFIXES: tuple[str, ...] = ("templates/", "rules/", "docs/")
+_VERSIONED_OVERLAY_PREFIXES: tuple[str, ...] = ("templates/", "rules/", "docs/", "schemas/")
 _VERSIONED_OVERLAY_EXACT: frozenset[str] = frozenset({"verification.yml.example", "VERSION"})
 
 # Versioned directories whose contents are pruned on upgrade