Repository navigation
Fix Epic Bugs - #84
Merged
Merged
Conversation
Specify keeping all Spektacular-managed artifacts in the main project during epic implementation. A spec's worktrees hold code only; their .spektacular directory is never read or written. - CLI always runs from the project root; plan, changelog, knowledge, design and epic writes land in the project's stores live. - Implement workflow output hands the child its worktree code roots, so epic children run the standard spek-implement skill unchanged. - Lanes, workflow state and working notes stay in the project, keyed by spec; the in-worktree repo overlay is retired. - epic merge refuses a branch that changes anything under .spektacular/. - Public epics docs updated to describe the new model. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EGWQ8Yier1bAcWbYA2RYeE Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
Plan keeping all Spektacular artifacts in the main project during epic implementation, with spec worktrees holding code only. - epic worktree records each spec's code roots in the main project and stops writing the repo overlay into the worktree. - implement new/goto read the record (no git) and the read-plan and feature-changelog steps list the worktree roots; standalone output is unchanged. - Implement auto-commit splits code (spec worktrees) from that spec's artifacts (path-scoped commit in the main checkout under the lock). - status reads lanes and finished evidence from the main project. - epic merge refuses a branch that changes anything under .spektacular/. - Epic and implement skills point children at the project root; docs epics page updated. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01EGWQ8Yier1bAcWbYA2RYeE Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…orktree record Merging a spec now refuses a branch that changes anything under a .spektacular directory in any repo (new error epic_merge_touches_spektacular, listing the offending paths per repo and nothing merged). Creating a spec's worktrees also writes a record in the main project (.spektacular/worktrees/<spec>/record.json) mapping each repo to its code root inside the worktrees; it is read without git and removed on merge. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…ld from the project Epic children now run every Spektacular command from the project root and build code in the spec's worktrees, which hold only code: - the implicit in-worktree repo overlay is removed; repo.NewWithCodeRoots gives an explicit spec-scoped view from the worktree record; - implement new/goto read the record (no git) and the read-plan and feature-changelog steps name each repo's worktree code root; - implement auto-commit commits code on spek/<spec> in the worktrees and only the spec's own artifacts, path-scoped under the commit lock, in the main checkouts; - status reads implement progress from the project only; - the epic implement and implement skills and `epic worktree` help point children at the project root; - an end-to-end test proves artifacts stay in the project and merges bring only code. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…be code-only worktrees The public epics page now says each spek's worktrees hold only code, that specs, plans, changelogs and progress stay in the project where they can be followed during a run, and that a spek whose branch changes Spektacular's own files is not merged. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
Epic worktrees now hold only code. Spektacular always runs from the main project; a per-spec worktree record tells the implement workflow each repo's code root, auto-commit splits code (spec branch) from the spec's own artifacts (main checkout, path-scoped under the lock), status reads progress from the project, and epic merge refuses any branch that changes a .spektacular directory. Adds the manual test plan, the project and repo changelog records, and reconciles the spec. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
Every implement run builds in its own worktrees by default (with an opt-out for runs started on their own) and merges back at the end, all-or-nothing. Also closes the gaps from issue #78: sub-agents are told where the code lives, repos can declare a worktree setup command, and the epic's uncommitted-work warning covers only touched repos and names them. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
Plan for building every implement run in the spec's own git worktrees. - M1: per-repo worktree_setup command run in new worktrees; shared code-locations block in implement steps 02-05 telling sub-agents where code lives; epic dirty warning limited to touched repos (dirty_repos, ported from PR #79). - M2: worktree runs always commit code on the spec branch; new `implement merge` command (all-or-nothing, shared with epic merge); implemented-but-unmerged dependencies count as unmet in implement and status. - M3: implement.worktrees opt-out (default on, no schema bump); per-spec lanes for runs started on their own; worktree creation at implement new; finished step instructs implement merge; end-to-end flow tests. - M4: docs for the new config keys, worktree runs and the narrowed warning. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…b-agents briefed, dirty warning narrowed - A repo can declare `worktree_setup` in its repo.yaml (set by `repo add`, shown by `repo list`); the worktree manager runs it in each newly created worktree of a touched repo, reading it from the main registration, and on failure removes the worktree and refuses with worktree_setup_failed. - New implement-code-locations partial in the analyze, implement, test and verify steps: names each repo's worktree root (or registry root), requires every sub-agent to be given those locations and work only there, and explains that worktrees hold only tracked files. - Epic status checks only repos its plans touch for uncommitted work and names them in `dirty_repos` (ported from PR #79); the epic skill tells the agent to name them to the user. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…mit, implement merge, unmerged deps unmet
- Implement runs built in worktrees commit their code on the spec branch at
completion even with auto_commit off (code only, nothing in the main
checkouts); the commit-message request uses the same decision, with
code-only wording.
- New `implement merge` command: all-or-nothing merge of a spec's worktree
branches via the shared worktree manager, sharing result and conflict
reporting with `epic merge`.
- A dependency that is implemented but whose worktree record still exists
counts as unmet in both the implement dependency check and status
("implemented but not yet merged"); the refusal offers to merge it.
Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…n build in worktrees and merge back - New `implement.worktrees` setting, on by default with no schema bump; `false` restores main-checkout runs exactly. - A run the user starts keeps its progress in a per-spec lane (data `lane: true`, separate from `orchestrated`), so specs can be implemented side by side from different terminals; resume, notes paths, lane cleanup and the session log follow the lane. - `implement new` creates the spec's worktrees in every touched repo (running setup commands), refusing with worktree_unavailable for a repo not in git or without commits. - The finished step of a complete worktree run tells the agent to run `implement merge` and to report and stop on a refusal; the implement skill gains a Worktrees section. - End-to-end flow tests on a two-repo git fixture; the harbor implement suite opts out. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…setup command and narrowed warning - Configuration reference: new `implement` section (`implement.worktrees`, on by default; epics always use worktrees) and the per-repo `worktree_setup` key; seventeen top-level keys. - How it works: implement runs build in their own worktrees, merge back all or nothing when the plan is complete, leave conflicts to the user; an unmerged dependency counts as not implemented. - Epics: uncommitted-work check covers only the repos an epic builds and status names them in `dirty_repos`; worktrees run `worktree_setup`. - Projects: `worktree_setup` listed with a repository's own settings. - Site changelog entry. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
Implement runs build in their own worktrees and merge back. - Test plan with the manual checks: two real terminals, a real multi-repo epic run (main checkouts untouched, setup command ready), a real standalone two-repo run, the harbor implement suite, and the docs pages. - Project changelog record plus derived records for the spektacular and docs repos. - Spec reconciled: every requirement and all but one acceptance criterion ticked; "Main checkouts' code is unchanged by a run" stays open until the epic half is observed in a real run (test plan item 2). Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…ents Specify how an implement run (interactive or orchestrated) handles a spec or referenced design that turns out to be wrong: a defined stop that hands the conflict back to the user, user-approved amendments applied in the project by the orchestrator or interactive agent (never by a child), an Amendments record on the spec plus a plan changelog entry, exemption of recorded amendments from plan staleness, and the child re-reading the amended document. Closes #78 item 6. Also includes uncommitted work already in the tree (cmd/gate, cmd/status, internal/autocommit, spek-implement-epic skill) at the user's request. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
Plan a defined path for correcting a spec or a referenced design while it is being implemented: - a shared spec-conflict stop in the analyze, implement, test and verify steps (interactive runs ask the user; orchestrated children hand back a QUESTION and never edit the spec or design themselves); - a new `spec amend` command that derives the changed sections, limits them to requirements, acceptance criteria, constraints and success metrics, appends an append-only `## Amendments` entry and records a checkbox-normalised body hash in the spec's frontmatter; - a PlanIsStale exemption when the spec body matches its last recorded amendment, so strict-mode runs continue while unrecorded edits stay stale; - skill updates for spek-implement and spek-implement-epic, README and docs-site pages. 10 tasks across 3 milestones in the spektacular and docs repos. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…ithout staling the plan Add `spektacular spec amend`, the supported way to change a planned spec's Requirements, Acceptance Criteria, Constraints or Success Metrics during an implement run, or to record a revision made to a design it references. The CLI derives the changed sections itself, refuses any other change (including moved sections and edits to the append-only history), appends a dated `## Amendments` entry with the reason and run, and stores an `amendments` record with a checkbox-normalised body hash in the spec's frontmatter. `status.PlanIsStale` treats a spec whose body still matches its last recorded amendment as unchanged, so under plan.strict_spec_changes a recorded amendment no longer stalls status, implement new/goto or an orchestrated lane, while any unrecorded edit still makes the plan stale. Also start 13 cmd tests in their own temp dirs so the suite passes when the checkout sits inside a spec's worktree. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
…ithout staling the plan Add `spektacular spec amend`, the supported way to change a planned spec's Requirements, Acceptance Criteria, Constraints or Success Metrics during an implement run, or to record a revision made to a design it references. The CLI derives the changed sections itself, refuses any other change (including moved sections and edits to the append-only history), appends a dated `## Amendments` entry with the reason and run, and stores an `amendments` record with a checkbox-normalised body hash in the spec's frontmatter. `status.PlanIsStale` treats a spec whose body still matches its last recorded amendment as unchanged, so under plan.strict_spec_changes a recorded amendment no longer stalls status, implement new/goto or an orchestrated lane, while any unrecorded edit still makes the plan stale. Also start 13 cmd tests in their own temp dirs so the suite passes when the checkout sits inside a spec's worktree. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
… wrong spec or design The analyze, implement, test and verify steps now share a stop for a spec or referenced design that turns out to be wrong. The run names the document, section, conflict and proposed amendment. An interactive run asks the user and, only after explicit approval, applies it with `spec amend` (or revises the design with `design author`/`design write` and records it). An orchestrated child never writes spec or design text and hands the proposal back. Either way the run re-reads the amended text and re-runs the step's check. The plan changelog entry gains an Amendments field. The spek-implement skill describes the interactive path and tells an orchestrated child it never amends. The spek-implement-epic skill counts a wrong spec or design as a genuine question, restates the rule in the child prompt, names `design` and `spec amend` in its store-access rule, and describes how the orchestrator applies an approved amendment from the project root and answers the child. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
… wrong spec or design The analyze, implement, test and verify steps now share a stop for a spec or referenced design that turns out to be wrong. The run names the document, section, conflict and proposed amendment. An interactive run asks the user and, only after explicit approval, applies it with `spec amend` (or revises the design with `design author`/`design write` and records it). An orchestrated child never writes spec or design text and hands the proposal back. Either way the run re-reads the amended text and re-runs the step's check. The plan changelog entry gains an Amendments field. The spek-implement skill describes the interactive path and tells an orchestrated child it never amends. The spek-implement-epic skill counts a wrong spec or design as a genuine question, restates the rule in the child prompt, names `design` and `spec amend` in its store-access rule, and describes how the orchestrator applies an approved amendment from the project root and answers the child. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
The README's plan.strict_spec_changes description names the recorded-amendment exemption: a change recorded with `spec amend` keeps the plan current, and any other edit still makes it stale. Docs: the how-it-works implement stage and a new epics subsection, "When the spek or a design is wrong", explain raising, approving, applying and recording a mid-run amendment. The documents page lists `spec amend`, the design-documents page notes a design can be corrected mid-run after approval, the configuration page documents plan.strict_spec_changes and its exemption, and the plan-tasks stale state mentions it. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
The README's plan.strict_spec_changes description names the recorded-amendment exemption: a change recorded with `spec amend` keeps the plan current, and any other edit still makes it stale. Docs: the how-it-works implement stage and a new epics subsection, "When the spek or a design is wrong", explain raising, approving, applying and recording a mid-run amendment. The documents page lists `spec amend`, the design-documents page notes a design can be corrected mid-run after approval, the configuration page documents plan.strict_spec_changes and its exemption, and the plan-tasks stale state mentions it. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
Record the finished implementation of mid-run spec and design amendments. The test plan covers the manual checks: a real epic run with a seeded spec/design conflict, a harbor implement-workflow run, and a read-through of the docs pages. The project changelog record and the per-repo records for spektacular and docs describe what was built and how it differed from the plan. The spec is reconciled: every requirement and the six automatically verified acceptance criteria are ticked, while the four criteria that describe a live agent's behaviour await the manual epic run. Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
Signed-off-by: Nic Jackson <jackson.nic@gmail.com>
Collaborator
Author
|
/approve |
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: nicholasjackson The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This PR fixes bugs and bad ux found when manually testing the Epics feature.