Spec: M6 — Matt migration and first release candidate

[Sandstorm831]

Milestone: #209 (M6: Matt migration). Parent wayfinder: #2.

Problem Statement

Secant can run the maintained front of the Matt workflow as an External Workflow Bundle, but the daily route from an initial idea through a grill, a published spec, approved tickets, and separate implementation sessions is incomplete. The current front carries sample skills rather than the maintainer-supplied folders. It does not let the user choose where the spec and tickets live, provide a Run-owned home for a Local tracker, or start an implementation conversation with the next ready ticket. An ordinary Agent Turn ending is only a Harness boundary and cannot tell Secant that a ticket is complete.

The first release candidate must carry the Matt workflow as Secant's sole built-in Bundle. It must also fix the legacy-conhost startup notice: the TUI currently takes over before a user can read the warning.

Solution

The user launches Matt in the TUI with an initial idea and one of the two v1 Harnesses. An Interactive grill starts from that idea and uses the original bundled skills. The user ends the grill explicitly. A Human Gate then offers Local, GitHub, and Other as tracker choices; Other accepts a typed name for a tracker available through the user's Harness tools. There is no spec-approval Gate. The original to-spec skill publishes the spec to the chosen tracker, and the original to-tickets skill discusses and publishes the approved ticket breakdown in the same planning Harness Session.

The chosen tracker alone owns ticket status and blocking relationships. Local spec and ticket files are editable working files in a dedicated directory owned by this Run under Secant home. GitHub and Other issues live in their remote tracker, without a local status mirror. Secant retains only the references needed to reach them. Each implementation iteration starts a fresh Interactive Harness Session that reads the selected tracker, identifies one unblocked ready ticket, states its choice, and runs the original implement skill. The agent and human manage the work and update that tracker. At a Turn boundary the user can ask another question, press Continue to open the next fresh ticket Session, or choose End implementation stage. End Stage requires a confirmation explaining that Secant has not checked the tracker and should be used only after the human and agent have verified that implementation tickets are over. Secant does not parse the agent's prose or keep a second ticket list.

M6 adds the generic Interactive Step and Run working-area capabilities this routing needs, without branching on the Matt Bundle identity. The complete Bundle is built once, embedded as exact .wfb bytes in each compiled binary, digest-locked, and installed at startup through ordinary ingestion. The Test Repair Proof Bundle remains External. The legacy-conhost notice waits for a keypress before TUI takeover. The first release candidate follows the established three-OS and protected release evidence path.

User Stories

Launch and grill

1. As a workflow user, I want to enter my initial idea before launching Matt, so that the first grill question addresses my actual task.
2. As a workflow user, I want to select a qualified Claude Code or Codex Harness, so that the Run uses the agent I have available.
3. As a workflow user, I want the initial idea sent in the grill's first Turn, so that I need not paste it a second time.
4. As a workflow user, I want the original grill-me and grilling folders used intact, so that the interview follows my daily skill discipline.
5. As a workflow user, I want the agent to ask one frontier of decisions at a time with recommendations, so that I can answer related decisions together.
6. As a workflow user, I want the agent to gather project facts itself, so that I am asked to decide rather than do its research.
7. As a workflow user, I want multiple human Turns in the grill's one Harness Session, so that later questions build on earlier answers.
8. As a workflow user, I want to end the grill through Secant's End Step control, so that a phrase from the agent cannot advance the Routing.
9. As a workflow user, I want the planning Session retained for spec and ticket work, so that those stages use the discussion we just had.
10. As a workflow user, I want a halt and resume to preserve a recoverable planning Session, so that interruption does not silently restart the conversation.
11. As a workflow user, I want an unusable Session reported instead of replaced, so that the later spec is not based on fabricated context.
12. As a reviewer, I want the grill transcript and End Step visible in the Run timeline, so that the transition into spec writing is auditable.

Tracker choice and spec

13. As a workflow user, I want to choose a tracker after the grill, so that this Run publishes where I want its planning work to live.
14. As a workflow user, I want Local and GitHub shown as quick choices, so that I can select either without typing its name.
15. As a workflow user, I want an Other choice with free text, so that I can name a tracker available through my agent's tools, including Linear through MCP.
16. As a workflow user, I want the chosen tracker recorded durably, so that resume and later prompts use the same destination.
17. As a workflow user, I want the spec-writing agent told my tracker choice, so that it does not infer a different destination from the repository.
18. As a workflow user, I want spec writing to start after tracker choice without another approval Gate, so that the flow does not ask for redundant permission.
19. As a workflow user, I want the original to-spec folder used intact, so that the resulting spec follows its agreed structure.
20. As a workflow user, I want test seams confirmed during the planning conversation, so that the spec-writing Turn can synthesize without reopening the interview.
21. As a workflow user choosing Local, I want the spec written only in this Run's Local tracker directory, so that the project Workspace is not filled with planning files.
22. As a workflow user choosing GitHub, I want the spec published as a GitHub issue, so that it can parent the implementation tickets.
23. As a workflow user choosing Other, I want the agent to use the connected tracker tool, so that Secant does not need to implement that tracker's API.
24. As a workflow user, I want an unavailable tracker connection stated plainly, so that a completed Turn is not mistaken for a published spec.
25. As a workflow user, I want the spec reference retained as a Run fact, so that ticketing and later implementation Sessions can find it.
26. As a reviewer, I want the supplied skill's default spec triage behavior used, so that the Bundle follows the maintainer-approved skill set.

Ticket planning

27. As a workflow user, I want to-tickets to read the published spec and planning Session, so that its slices preserve the agreed intent.
28. As a workflow user, I want tracer-bullet tickets that deliver complete behavior, so that each ticket can be implemented and checked independently.
29. As a workflow user, I want every ticket's blocking edges made explicit, so that ready work can be distinguished from blocked work.
30. As a workflow user, I want to see a proposed breakdown before publication, so that I can correct granularity and dependencies.
31. As a workflow user, I want to revise the breakdown across multiple Turns, so that approval is based on the final graph.
32. As a workflow user, I want the tickets published only after I approve them, so that draft ideas do not become tracker work accidentally.
33. As a workflow user choosing Local, I want one editable file per approved ticket in this Run's Local tracker directory, so that Local remains the only ticket source.
34. As a workflow user choosing GitHub, I want each ticket created in GitHub with its parent and blocking links, so that GitHub remains the only ticket source.
35. As a workflow user choosing Other, I want the agent to create tickets through my connected tool, so that the chosen tracker remains authoritative.
36. As a workflow user, I want the original to-tickets folder used intact, so that its templates, review, and label rules are preserved.
37. As a workflow user, I want the skill's ready-for-agent status applied to approved tickets, so that the selected tracker reflects their intended next action.
38. As a reviewer, I want Local and remote tracker modes to create no second issue-status list, so that ticket state has one owner.

One ticket per implementation Session

39. As a workflow user, I want each implementation iteration to ask the selected tracker for the current ready frontier, so that changes made since ticket publication can be seen.
40. As a workflow user, I want the agent to choose one unblocked ready ticket, so that it does not begin work on a blocked dependency.
41. As a workflow user, I want the selected ticket's exact path or remote reference stated before work begins, so that I can catch a wrong selection.
42. As a workflow user, I want each ticket to use a fresh Harness Session, so that previous tickets do not consume its context window.
43. As a workflow user, I want the original implement folder supplied to that Session, so that the agent follows my existing implementation skill.
44. As a workflow user, I want tdd, code-review, and codebase-design available as complete bundled folders, so that referenced guidance resolves without a global installation.
45. As a workflow user, I want the implementation Session to start from the selected tracker and spec context, so that I need not paste a ticket into it.
46. As a workflow user, I want to ask questions in later Turns of the same ticket Session, so that I can collaborate while the ticket is being worked.
47. As a workflow user, I want Continue offered only at a Turn boundary, so that it cannot race active agent work.
48. As a workflow user, I want a completed Harness Turn to leave the ticket Session available for my questions, so that only my explicit Continue or confirmed End Stage releases the Step.
49. As a workflow user, I want the implementation prompt to tell the agent to update the chosen tracker as part of its own work, so that the next fresh Session sees the current ticket state.
50. As a workflow user, I want Secant to leave code changes, commits, review order, and tracker updates to the agent and me, so that it does not manage the inner implementation task.
51. As a workflow user, I want Continue to say that it does not close the selected tracker ticket, so that I know an open ticket may be selected again.
52. As a workflow user, I want the next iteration to read the tracker again, so that it does not rely on an old list of tickets.
53. As a workflow user, I want one Continue control after I have had a chance to ask questions, so that I can open a fresh Session for the next ticket.
54. As a workflow user, I want an End implementation stage control, so that I can deliberately complete this Run after verifying the selected tracker with the agent.
55. As a workflow user, I want End Stage to show a confirmation saying Secant has not checked the tracker, so that I do not mistake my declaration for an automatic verification.
56. As a workflow user, I want halted or lost Turns to retain normal recovery behavior without advancing to another ticket, so that partial work is not skipped.
57. As a reviewer, I want each implementation Session's ticket choice, Turns, Continue, and confirmed End Stage visible in Run history, so that the Run can be audited without mirroring tracker status.
58. As a workflow user, I want Continue and confirmed End Stage to satisfy the human checkpoint for each iteration, so that Secant does not ask me to continue twice.
59. As a workflow user, I want a visible Interrupt control during a live Interactive Turn, so that I can stop long-running agent work and resume the same ticket conversation.

Run-owned Local work and skill folders

60. As a workflow user choosing Local, I want spec and ticket files under a dedicated directory owned by this Run in Secant home, so that planning files stay with the Run.
61. As a workflow user, I want planning prompts to state the exact allowed write directory, so that the agent knows where Local files belong.
62. As a workflow user, I want that directory writable to the selected Harness without making Secant's private database or Artifact repository writable as a group, so that the local tracker does not expose unrelated Run internals.
63. As a workflow user, I want Local files to survive halt and resume, so that a long planning session can continue.
64. As a workflow user, I want deleting the Run to remove its Local files, so that they share the Run's lifecycle.
65. As a workflow user, I want every supporting file in each of the eight skill folders packaged unchanged, so that relative references inside a skill still work.
66. As a workflow user, I want nested Skill-tool instructions resolved through bundled paths, so that the supplied skills can be followed with Secant's plain-path delivery.
67. As a reviewer, I want a change to any skill byte to require a new built-in identity version and digest, so that released behavior is reproducible.

Built-in shipping and release

68. As a new Secant user, I want Matt available in the Catalog on first startup, so that I can launch it without importing a Bundle.
69. As a headless user, I want the built-in listed and inspectable after startup, so that scripts can see the installed exact version.
70. As a headless user, I want an attempted Matt launch refused at Preflight with TUI remediation, so that headless v1 does not pretend to support Interactive Turns.
71. As an upgrading user, I want an older built-in version preserved beside a newer one, so that resting Runs keep their exact digest.
72. As a restarting user, I want startup ensure to leave an already installed equal digest unchanged, so that repeated launches are idempotent.
73. As a user facing a built-in ensure failure, I want the cause and remedy shown while other Bundles remain usable, so that startup is not all-or-nothing.
74. As a user importing a same-identity Bundle, I want ordinary equal-digest and identity-collision behavior, so that the built-in shares the Catalog contract.
75. As a Bundle author, I want the Test Repair Proof Bundle kept external, so that it still guards external ingestion and generic routing.
76. As a reviewer, I want only the allow-listed Matt .wfb embedded in the compiled binaries, so that unrelated maintained Bundles do not ship.
77. As a reviewer, I want the exact built-in identity and digest in the release approval summary, so that approval names the content users receive.
78. As a reviewer, I want the Matt flow exercised against fake and recorded Harness behavior on the three-OS matrix, so that CI proves routing without credentials.
79. As a reviewer, I want startup install and digest checked through a copied compiled binary on every gated OS, so that the released artifact proves the path users take.
80. As a reviewer, I want the first release candidate to pass the established CI, consumer, terminal, and protected validation path, so that M6 adds no weak release lane.
81. As a reviewer, I want required real installed-Harness evidence recorded for Claude Code and Codex, so that the support claims are not inferred from replayers.

Legacy conhost notice

82. As a user launching the TUI in legacy conhost, I want the Windows Terminal warning printed before renderer takeover, so that I can read it.
83. As a user seeing that warning, I want Secant to wait for a keypress, so that the notice does not vanish immediately.
84. As a user in Windows Terminal, I want no conhost warning or wait, so that normal startup remains immediate.
85. As a headless user, I want no terminal wait, so that commands still work in scripts.
86. As a reviewer, I want a real legacy-conhost observation of readability, so that a pseudo-terminal does not supply false confidence.
87. As a reviewer, I want legacy conhost omitted from the support matrix, so that the notice is not treated as a support claim.

Implementation Decisions

• The eight Bundle skill assets are grill-me, grilling, to-spec, to-tickets, implement, tdd, code-review, and codebase-design. Complete directories, including supporting Markdown and metadata, are copied without editing them. Bundle prompts resolve nested skill references through their bundled paths. The conditional tracker-setup skill remains a user instruction for an unconfigured project.
• The Bundle declares a required free-text idea Launch input and supports the two v1 Harnesses on the three gated platforms. The idea is passed to the grill's first Turn.
• The grill, spec, and ticket stages share one named planning Harness Session. The user ends the grill explicitly. No approve/reject Gate precedes the spec.
• A generic free-text Human Gate gains suggested answers for Local and GitHub plus an Other text entry. It produces one durable text Run Artifact passed to later prompts. Other may name Linear when the user has connected its MCP; Secant supplies no Linear Adapter.
• The selected tracker is the sole source of spec and ticket state. Local planning files live in a dedicated Run-owned editable working area; GitHub and Other issues live remotely. Run history may retain references and observations, but never a mirrored status list or worklist.
• The Run Store owns the Local working area as a lifecycle child of the Run, isolated from its private database and Artifact repository. It persists through resume and is removed on Run deletion. Its path is exposed through a generic Run-owned reference to the relevant Step prompts. Harness preparation adds only that narrow writable directory when required by native sandbox rules, without changing the user's broader permission posture.
• The to-spec stage follows the supplied skill's publication contract for the selected tracker and records the resulting reference as a Run Artifact. Agent-produced reference capture and required-output validation are generic Agent Step capabilities; a missing receipt fails the Step. A remote reference is an agent observation, not independent proof that the remote tracker accepted publication. The to-tickets stage stays conversational until the user approves the breakdown, then publishes tickets and blocking edges to that same tracker. The supplied skills' default triage and ticket status rules govern this flow by explicit maintainer instruction.
• Each implementation iteration reads the selected tracker afresh. Its Interactive prompt asks the agent to identify one unblocked ready ticket, state its exact reference, run the supplied implement skill, and update that same tracker as part of the agent/human task. If no ticket remains or tracker access fails, the agent reports that in the conversation and the human can ask questions or decide what to do. Secant does not close issues, move Local files, commit code, run code review separately, or decide ticket correctness.
• At a Turn boundary, Continue settles the current Interactive Step and opens another Repeat iteration with a fresh Session. A separate End implementation stage Operation asks for explicit human confirmation and then settles the stage and Run as human-completed. It neither queries nor mutates the tracker. A declined confirmation leaves the current Interactive Step available for more Turns. Run history distinguishes human-declared completion from automatically verified completion.
• The current generic Interactive Step contract must grow: authored first-prompt delivery, optional entry Turn, one durable Session identity per Repeat iteration, Turn-taking and recovery within that identity, an iteration-aware Attempt id, support for Interactive Steps inside Repeat groups, and explicit human End control that advances exactly once. Existing Interactive Bundles without the option keep their current wait-for-user behavior.
• The Repeat group gains a generic human-controlled mode: Continue starts its next iteration and confirmed End Stage exits it successfully. This is distinct from the existing Verdict-driven mode and from Cancel Run. Both controls are available only at a Turn boundary and are idempotent by Operation id. Each human action is the review checkpoint for that iteration, so this mode does not raise an additional periodic Review checkpoint. The engine never reads a phrase or structured completion claim from the agent to choose the exit.
• New capabilities land at the generic Human Gate, Interactive Step, Run working-area, or Step output seams. Runtime source never inspects the Matt Bundle identity, name, or asset path.
• Module ownership stays in the existing dependency direction. Workflow owns only static Step and Repeat vocabulary plus Composition checks; Run execution owns scheduling, iteration identity, and Interactive lifecycle; Run Store owns durable Attempt and Session facts plus the Local working-area lifecycle; Application admits intent and projects Offers through the Projection Port; TUI renders those Offers and sends Operations; Harness Adapters own native launch, Turn, permission, recovery, and failure semantics without seeing Bundle or tracker concepts; Bundle owns prompts, skills, and tracker instructions. Composition wires their Interfaces and contains no workflow policy. No new public package entrypoint or tracker Module is introduced.
• The Run Store Interface provides the narrow Run working-area location to execution without requiring Application, TUI, or Harness to reconstruct a private storage path. Execution passes only that dedicated directory to a Harness as an additional writable location for Local planning. Clients receive normalized Projections and Resource References rather than the Store root or native Harness objects.
• Continue and End Stage use typed Action Offers and Operations at the Projection Port; the Workbench owns presentation and key routing only. The confirmation belongs on its existing modal stack, and the live Interactive interrupt must preserve that stack, focus, and terminal lifecycle ordering. No new runtime dependency is added for these controls.
• The Matt Bundle becomes the only v1 Shipped Bundle. Release tooling builds exact .wfb bytes once, embeds those bytes in each Bun-compiled executable, and locks authored identity and version to a digest consistent across all three OS builds. Startup ensures it through ordinary Bundle ingestion in TUI and headless, with app-release origin and trust, first-install-wins collision behavior, side-by-side upgrades, and non-blocking failure notices.
• Headless v1 still refuses every Bundle containing an Interactive agent Step at Preflight. Its Matt CI path proves installation, inspection, and refusal through the compiled binary; TUI and fake or recorded Harness paths prove interactive behavior.
• At the TUI startup seam, a detected legacy-conhost launch prints the warning and waits for one keypress before renderer creation. Windows Terminal suppression and headless behavior remain. Conhost remains outside the support matrix.
• The first release candidate uses the existing candidate-validation and protected release gates. The approval summary includes the built-in identity and digest beside candidate digests and required terminal evidence. Publication remains protected by the existing human release process.

Testing Decisions

• Good tests drive a caller-facing Interface and assert observable or durable consequences: Projection snapshots and Offers, typed Problems, Run state, Session and Turn evidence, selected tracker references, Local files, Catalog identity and digest, compiled-binary output, and terminal behavior. They do not assert private helper calls, internal database rows, or transient storage layout.
• The highest Matt behavior seam is the shared Projection Port. Tests drive the real Application and Run Store over temporary homes with injected Process and Harness doubles. They prove initial idea handoff, grill Turns, tracker selection, same-Session planning, ticket review, tracker reference flow, distinct implementation Sessions, Continue, confirmed End Stage, halt, resume, and Run deletion.
• The existing Module-boundary gate checks the allowed import direction for every changed Interface. A behavioral Port test proves the same Continue and End Stage consequences regardless of TUI layout; Store Interface tests prove only the dedicated Local area is exposed, while Harness conformance proves native writable-directory handling behind its Seam.
• The Interactive Step tests prove optional authored first Turn, subsequent verbatim human Turns, Continue and End Stage only at a Turn boundary, distinct Sessions and Attempt ids for Repeat iterations, no auto-advance on Turn completion, declined and confirmed End Stage, no duplicate checkpoint, live-Turn interrupt, and recovery in the same ticket Session.
• The human-controlled Repeat test proves Continue starts the next iteration, confirmed End Stage completes the Run, declining End Stage leaves it blocked for more Turns, and agent text alone never ends it. The existing Verdict-driven Repeat remains green on all three operating systems.
• The tracker-choice test proves suggested Local and GitHub answers, typed Other, durable binding into later prompts, and a clear failure when the selected tracker is unavailable to the Harness. The same generic Gate operation remains available to both clients even though this Bundle is TUI-only.
• The Local working-area tests prove one directory per Run, no additional write root covering the private Run Store files, survival through resume, deletion with the Run, and a precise path in planning prompts. Test path validation at the owning ingress and a typed failure if native Harness policy cannot allow the added directory.
• Bundle build and Composition tests prove all eight full skill folders, supporting files, references, all-platform declarations, and the absence of undeclared bytes. The maintained Matt Bundle is built, installed, and exercised like a user's Bundle.
• Harness conformance and standalone runtime-conformance tests prove plain-path skill delivery, the additional Run writable directory, Turn ordering, interruption, resume, and recorded Claude Code and Codex behavior. Real Harnesses do not run in CI.
• TUI renderer tests prove idea input, tracker suggestions and Other entry, first Interactive prompt, ticket reference visibility, Continue, an End Stage confirmation stating the tracker has not been checked, a visible interrupt during a live Interactive Turn, resume, focus and key routing, small terminals, large content, and state wording independent of color. Apply the deferred TUI interaction and platform checks to every TUI slice.
• Compiled-binary consumer tests on the three-OS matrix prove exact embedded allow-listed bytes, locked digest, first-start install, second-start no-op, origin, catalog inspection, collision and ensure failure, and headless Interactive-step refusal. Existing package smoke and release-consumer scenarios are prior art.
• The conhost guard's deterministic tests cover detection, suppression, keypress wait, Ctrl+C exit without TUI takeover, and exit behavior without invoking Windows APIs on other platforms. A human real legacy-conhost launch records notice readability before takeover; the required Windows Terminal human check remains separate.
• The external Test Repair Proof Bundle continues to be built, installed, and run in CI. Both Harness paths remain regression evidence against workflow-specific runtime behavior.
• Every slice names a blocking CI scenario on Windows x64, macOS arm64, and Linux x64. The first candidate uses the existing release checklist, support matrix, recorded human Harness evidence, and terminal evidence. A local green run alone is not acceptance.

Out of Scope

• A third v1 Harness, including OpenCode or Gemini.
• Native Harness skill registration or editing the supplied skill folders.
• Headless Interactive agent passthrough.
• A Secant-owned GitHub, Linear, or arbitrary tracker API Adapter.
• Agent-generated terminal markers or structured no-work reports as a Run-completion condition.
• A mirrored ticket queue or status database for remote trackers.
• Secant-controlled commits, code review order, issue closure, or judgements that implementation work is correct.
• Cloud execution, a daemon, parallel Workflow execution, and multiple Harnesses in one Run.
• Shipping the Test Repair Proof Bundle as a built-in.
• Treating legacy conhost as a supported terminal or claiming its exit defect is fixed.
• Public release promotion, deferred signing channels, and G4's later human plan review.

Further Notes

• The current Matt-front sample skill content is not the source for this Bundle. The maintainer supplied eight original skill directories and approved complete-folder, plain-path delivery. A content change requires a built-in version bump and digest-lock update.
• The M3 Interactive-step slice intentionally handled top-level pauses only: it restricted Interactive Steps to top-level Routing, gave their Attempts iteration zero, passed their Session names literally, and sent no authored prompt on entry. M6 must extend these generic contracts to support one fresh Interactive implementation Session per Repeat iteration and a human-controlled Repeat end.
• The selected tracker owns all ticket status. Agent observations and stored references are evidence for the Run, not another tracker. Confirmed End Stage is a human declaration, not independent tracker verification; the Run summary must say so. The editable Local area adds a Run-owned working-file concept; the Run Store ADR and glossary need a deliberate amendment. Other depends on the user's available Harness tools; an unavailable connection is surfaced instead of silently switching destinations.
• User instruction selected the supplied skills' default triage behavior for this workflow and this spec, superseding the repository's current milestone-specific label convention.
• The Test Repair Proof Bundle remains the genericity guard. Any capability Matt needs lands at a named generic Step or Module Seam, with no runtime branch on workflow identity.
• The first release candidate and the Keep the legacy-conhost startup notice readable before TUI takeover #70 notice are M6 obligations in addition to the daily Matt flow. OpenCode is presentation comparison evidence, not Secant policy.
• The OpenCode checkout was studied for its active-session interrupt cue and prompt focus behavior. Secant retains its own Projection Port, Workbench modal stack, Run lifecycle, and Harness Session model. If implementation reuses presentation code or patterns, the implementing ticket records what was taken and what differs in the vendor provenance record.