-
Notifications
You must be signed in to change notification settings - Fork 0
feat: promote parallel autonomous governance preset v0.2.0 #73
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from 5 commits
Commits
Show all changes
13 commits
Select commit
Hold shift + click to select a range
87828fd
feat: add parallel autonomous run governance preset
hindermath 2589ea3
fix: inherit sequential worker heads
hindermath 57b0e44
feat: prepare native Secure CaseTracker field campaign
hindermath 3cf8ca6
fix: expose field stop and resume actions
hindermath da6790b
test: guard concurrent campaign resume
hindermath 186c7a8
docs: align preset README metadata
hindermath 71e52d0
docs: address preset README review feedback
hindermath 8295810
docs: complete preset README review follow-up
hindermath 22409ff
docs: finish preset README review cleanup
hindermath 55b6fb6
docs: expand preset README guidance
hindermath 12475e5
docs: address final preset README review notes
hindermath 08329f9
feat: promote parallel autonomous preset v0.2.0
hindermath 0336c45
docs: complete eight-preset learning tables
hindermath File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
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
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,57 @@ | ||
| # Implementation Plan: Parallel Autonomous Run Governance | ||
|
|
||
| ## Architecture | ||
|
|
||
| The preset adds a campaign layer above autonomous single runs. A tracked | ||
| campaign manifest declares portable intent. A local runner-profile file binds | ||
| agent and provider commands without storing secrets. Runtime worktrees, logs, | ||
| locks, and process results live outside tracked feature artifacts. | ||
|
|
||
| The PowerShell 7 coordinator is the canonical structured implementation. The | ||
| Bash entry point delegates argument-for-argument to that implementation, which | ||
| keeps behavior identical on macOS, Linux, and Windows where PowerShell 7 is part | ||
| of the required workspace toolchain. | ||
|
|
||
| ## Contracts | ||
|
|
||
| - `parallel-campaign.json`: immutable campaign intent and worker graph. | ||
| - `parallel-runner-profiles.json`: local executable/argument-array bindings. | ||
| - `parallel-campaign-state.json`: resumable aggregate lifecycle. | ||
| - `worker-result.json`: worker outcome, head, evidence, and optional PR. | ||
| - Existing `autonomous-run-state.json`: authoritative worker-internal state. | ||
|
|
||
| ## Delivery | ||
|
|
||
| Implement and validate in Level 0, publish v0.1.0 in a protected standalone | ||
| repository, then opt in the Secure CaseTracker coordinator and six language | ||
| repositories. Promote to v0.2.0 and the standard eight-preset matrix only after | ||
| the Units 00-03 field campaign succeeds. | ||
|
|
||
| ## Native Development Override | ||
|
|
||
| Repository owner Thorsten Hindermann explicitly authorized both the 13-worker | ||
| smoke set and the Secure CaseTracker Units 00-03 field campaign to run natively | ||
| on the development Mac on 2026-07-18. This is a deliberate development-phase | ||
| override of the otherwise binding Secure Trader Container-First rule. | ||
|
|
||
| The campaign evidence MUST record the override, host platform, agent family, | ||
| maximum configured and observed concurrency, repositories, run IDs, and start | ||
| and completion times. Concurrency remains capped at three. The override ends | ||
| after field findings are captured and does not apply to learner, production, | ||
| routine maintenance, or later campaigns. Those return to Container-First | ||
| unless the repository owner issues a new explicit authorization. | ||
|
|
||
| ## GitHub Billing Development Override | ||
|
|
||
| Repository owner Thorsten Hindermann explicitly authorized the development | ||
| field campaign to continue despite GitHub Actions jobs in the six private | ||
| Secure CaseTracker repositories being rejected before their first step with | ||
| the account-payment or spending-limit annotation. | ||
|
|
||
| This exception is narrow: those exact startup rejections are recorded as | ||
| external provider `N/A`, not as passing technical evidence. Every local build, | ||
| test, security, accessibility, documentation, and autonomous-state gate remains | ||
| required. Technical CI failures, actionable reviews, missing worker evidence, | ||
| and any other unavailable check remain blocking. Ordered merges may use the | ||
| owner's admin bypass only after the all-ready barrier and successful local | ||
| gates. The exception expires with the native field campaign. | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,84 @@ | ||
| # Feature Specification: Parallel Autonomous Run Governance | ||
|
|
||
| **Feature Branch**: `007-parallel-autonomous-run-governance` | ||
| **Created**: 2026-07-18 | ||
| **Status**: Approved for implementation | ||
|
|
||
| ## Goal | ||
|
|
||
| Create an experimental Spec Kit preset that coordinates several existing | ||
| `autonomous-run-governance` runs without weakening their lifecycle, evidence, | ||
| or permission boundaries. | ||
|
|
||
| ## User Scenarios | ||
|
|
||
| 1. Run one language-neutral assignment in several isolated repositories. | ||
| 2. Run independent features concurrently without sharing branches or worktrees. | ||
| 3. Produce alternative solutions and require an explicit human selection before | ||
| consolidation. | ||
| 4. Execute a dependency-ordered agent pipeline with immutable, hashed handoffs. | ||
| 5. Stop, inspect, and resume a campaign without guessing whether child work | ||
| completed. | ||
|
|
||
| ## Functional Requirements | ||
|
|
||
| - **FR-001**: The preset MUST use immutable UUID campaign and worker run IDs. | ||
| - **FR-002**: Every worker MUST have an isolated branch and Git worktree. | ||
| - **FR-003**: Concurrency MUST be limited to a declared value from 1 through 3. | ||
| - **FR-004**: The campaign MUST support `ReplicatedTargets`, | ||
| `IndependentFeatures`, `AlternativeSolutions`, and `Pipeline`. | ||
| - **FR-005**: Pipeline dependencies MUST form a directed acyclic graph. | ||
| - **FR-006**: A worker MUST retain the existing autonomous-run state contract; | ||
| campaign state MUST reference rather than duplicate it. | ||
| - **FR-007**: Runner commands MUST execute as executable plus argument array, | ||
| without shell evaluation. | ||
| - **FR-008**: Ordinary worker failure MUST not cancel unrelated running work. | ||
| - **FR-009**: Failed pipeline dependencies MUST block their descendants. | ||
| - **FR-010**: Campaign-integrity, security, permission, or evidence failures | ||
| MUST stop new scheduling. | ||
| - **FR-011**: Stop MUST be cooperative. Unexpected process loss MUST require | ||
| revalidation before retry. | ||
| - **FR-012**: Alternative solutions MUST require a named human selection. | ||
| - **FR-013**: Merge-and-sync delivery MUST enforce an all-ready barrier before | ||
| the first merge and MUST stop after the first merge failure. | ||
| - **FR-014**: Handoffs MUST identify producer, consumer, path, and SHA-256. | ||
| - **FR-015**: Installation MUST grant no execution or remote authority. | ||
| - **FR-016**: Bash and PowerShell entry points MUST expose equivalent behavior. | ||
| - **FR-017**: A sequential worker MAY inherit the validated exact head of one | ||
| direct dependency in the same repository without sharing its worktree. | ||
| - **FR-018**: Reviewed campaign-specific operator instructions MUST be routed | ||
| visibly to every worker without weakening undeclared authority boundaries. | ||
|
|
||
| ## Success Criteria | ||
|
|
||
| - **SC-001**: Deterministic fixtures pass for all four topologies. | ||
| - **SC-002**: The scheduler never observes more than three active workers. | ||
| - **SC-003**: Duplicate IDs, branch collisions, cycles, dirty repositories, and | ||
| malformed result contracts fail before unsafe continuation. | ||
| - **SC-004**: Alternative consolidation cannot proceed without explicit | ||
| selection. | ||
| - **SC-005**: A 13-worker local agent smoke set completes natively on the | ||
| authorized development Mac without remote writes. | ||
| - **SC-006**: Secure CaseTracker Units 00 through 03 complete in all six MSL | ||
| repositories with no more than three workers active, using the same | ||
| explicitly authorized native development override. | ||
|
|
||
| ## Boundaries | ||
|
|
||
| - Version 0.1.0 is experimental and opt-in. | ||
|
hindermath marked this conversation as resolved.
Outdated
|
||
| - No model name is prescribed. | ||
| - Provider-specific merge behavior is supplied through a local runner profile. | ||
| - The workspace standard matrix remains at seven presets until field validation | ||
| succeeds. | ||
| - The repository owner's 2026-07-18 instruction explicitly overrides | ||
| Container-First only for the native macOS development smoke set and the | ||
| Secure CaseTracker field campaign for this preset. The override is not a | ||
| reusable exception and expires when the field findings are captured. | ||
| - The repository owner's 2026-07-18 instruction also permits the development | ||
| field campaign to classify only GitHub Actions jobs rejected before their | ||
| first step with the known account-payment or spending-limit annotation as an | ||
| external provider `N/A`. Local and agent-side gates remain required. Any | ||
| technical CI failure, review finding, or different unavailable check remains | ||
| blocking. | ||
| - Container-First remains binding for normal Secure Trader work and for any | ||
| later production, learner, or routine campaign. | ||
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,17 @@ | ||
| # Tasks: Parallel Autonomous Run Governance | ||
|
|
||
| - [x] T001 Define campaign, runner, state, result, and handoff schemas. | ||
| - [x] T002 Implement campaign validation and DAG checks. | ||
| - [x] T003 Implement isolated worktree creation and bounded scheduling. | ||
| - [x] T004 Implement status, cooperative stop, resume, and reconciliation. | ||
| - [x] T005 Implement all-ready consolidation and human alternative selection. | ||
| - [x] T006 Add Bash entry points and PowerShell comment-based help. | ||
| - [x] T007 Add commands, agent guidance, runbook, evidence, and retrospective. | ||
| - [x] T008 Add deterministic fixtures for all topologies and failure modes. | ||
| - [x] T009 Run 13 local real-agent smoke workers natively on the authorized | ||
| development Mac. | ||
| - [x] T010 Publish protected experimental repository and v0.1.0. | ||
|
hindermath marked this conversation as resolved.
Outdated
|
||
| - [ ] T011 Run Secure CaseTracker Units 00-03 across six MSL repositories | ||
| natively under the explicit, temporary native and GitHub-Billing development | ||
| overrides. | ||
| - [ ] T012 Promote field findings, v0.2.0, standard matrix, and catalog entry. | ||
21 changes: 21 additions & 0 deletions
21
specs/spec-kit-preset-repos/spec-kit-preset-parallel-autonomous-run-governance/LICENSE
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| MIT License | ||
|
|
||
| Copyright (c) 2026 Thorsten Hindermann | ||
|
|
||
| Permission is hereby granted, free of charge, to any person obtaining a copy | ||
| of this software and associated documentation files (the "Software"), to deal | ||
| in the Software without restriction, including without limitation the rights | ||
| to use, copy, modify, merge, publish, distribute, sublicense, and/or sell | ||
| copies of the Software, and to permit persons to whom the Software is | ||
| furnished to do so, subject to the following conditions: | ||
|
|
||
| The above copyright notice and this permission notice shall be included in all | ||
| copies or substantial portions of the Software. | ||
|
|
||
| THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR | ||
| IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, | ||
| FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE | ||
| AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER | ||
| LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, | ||
| OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE | ||
| SOFTWARE. |
86 changes: 86 additions & 0 deletions
86
...c-kit-preset-repos/spec-kit-preset-parallel-autonomous-run-governance/README.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| # Parallel Autonomous Run Governance Preset | ||
|
|
||
| Version: `0.1.2` | ||
|
hindermath marked this conversation as resolved.
Outdated
|
||
| Status: experimental, opt-in | ||
| Priority: `80` | ||
| Requires: Spec Kit `>=0.8.3` and `autonomous-run-governance >=0.2.2` | ||
|
|
||
| ## Purpose / Zweck | ||
|
|
||
| This preset coordinates several isolated autonomous Spec Kit runs. It supports | ||
| replicated targets, independent features, human-selected alternatives, and | ||
| dependency-ordered pipelines. It does not replace the single-run lifecycle and | ||
| does not grant execution or remote authority. | ||
|
|
||
| *Dieses Preset koordiniert mehrere isolierte autonome Spec-Kit-Laeufe. Es | ||
| unterstuetzt gleiche Auftraege in mehreren Zielen, unabhaengige Features, | ||
| menschlich ausgewaehlte Alternativen und abhaengigkeitsgeordnete Pipelines. Es | ||
| ersetzt nicht den Einzelrun-Lebenszyklus und erteilt keine Ausfuehrungs- oder | ||
| Remote-Berechtigung.* | ||
|
|
||
| ## Install | ||
|
hindermath marked this conversation as resolved.
Outdated
|
||
|
|
||
| ```bash | ||
| specify preset add --dev /path/to/parallel-autonomous-run-governance --priority 80 | ||
| specify preset info parallel-autonomous-run-governance | ||
| ``` | ||
|
|
||
| Version `0.1.2` remains opt-in until deterministic tests, real local development | ||
| campaigns, and the Secure CaseTracker Units 00-03 field campaign have passed. | ||
|
hindermath marked this conversation as resolved.
Outdated
|
||
|
|
||
| The 13-worker native macOS smoke passed all four topologies. See | ||
| [`docs/field-evidence/native-macos-smoke-2026-07-18.md`](docs/field-evidence/native-macos-smoke-2026-07-18.md). | ||
|
|
||
| ## Development Validation Override | ||
|
hindermath marked this conversation as resolved.
Outdated
|
||
|
|
||
| The repository owner explicitly authorized the 2026-07-18 smoke and Secure | ||
| CaseTracker field campaigns to run natively on the development Mac. This | ||
| temporary, campaign-specific exception must be recorded in campaign evidence. | ||
| It does not change the workspace Container-First default for normal Secure | ||
| Trader, learner, production, maintenance, or later campaign work. | ||
|
|
||
| *Der Repository-Eigentuemer hat die Smoke- und Secure-CaseTracker-Feldkampagnen | ||
| vom 2026-07-18 ausdruecklich fuer eine native Ausfuehrung auf dem | ||
| Entwicklungs-Mac freigegeben. Diese temporaere, kampagnenspezifische Ausnahme | ||
| muss in der Kampagnenevidenz dokumentiert werden. Sie aendert nicht den | ||
| Container-First-Standard fuer regulaere Secure-Trader-, Lernenden-, Produktions-, | ||
| Wartungs- oder spaetere Kampagnen.* | ||
|
|
||
| ## Coordinator | ||
|
hindermath marked this conversation as resolved.
Outdated
|
||
|
|
||
| ```bash | ||
| bash .specify/presets/parallel-autonomous-run-governance/scripts/orchestrate-parallel-autonomous-runs.sh \ | ||
| -Action Validate \ | ||
| -Manifest specs/NNN-campaign/parallel-campaign.json \ | ||
| -RunnerConfig ~/.config/spec-kit/parallel-runner-profiles.json | ||
| ``` | ||
|
|
||
| ```powershell | ||
| pwsh -NoProfile -File .specify/presets/parallel-autonomous-run-governance/scripts/orchestrate-parallel-autonomous-runs.ps1 ` | ||
| -Action Validate ` | ||
| -Manifest specs/NNN-campaign/parallel-campaign.json ` | ||
| -RunnerConfig ~/.config/spec-kit/parallel-runner-profiles.json | ||
| ``` | ||
|
|
||
| Runner profiles contain executable names and argument arrays, not secrets. | ||
| Arguments are executed directly. Do not use shell expressions in a profile. | ||
| Optional campaign-level `operatorInstructions` are copied verbatim into every | ||
| worker prompt and therefore belong in the reviewed campaign manifest. Use them | ||
| only for explicit, campaign-specific context or authority, never for secrets. | ||
|
|
||
| ## Safety | ||
|
hindermath marked this conversation as resolved.
Outdated
|
||
|
|
||
| - Maximum supported concurrency is three. | ||
| - Every worker owns a separate branch and worktree. | ||
| - Every worker is instructed to remain on its assigned branch. | ||
| - A dependent worker may branch from a validated direct predecessor through | ||
| `baseWorkerId`, preserving sequential feature history without sharing a | ||
| worktree. | ||
| - Stop is cooperative and grants no process-kill authority. | ||
| - Alternative consolidation requires explicit human selection. | ||
| - Merge-and-sync uses an all-ready barrier and stops on the first merge error. | ||
| - Child workers in a `MergeAndSync` campaign stop at `PublishPR`; only the | ||
| coordinator may execute the ordered merge profile after every result is | ||
| ready. | ||
| - Installation grants no remote, merge, bypass, cancellation, secret, or | ||
| provider-administration rights. | ||
13 changes: 13 additions & 0 deletions
13
...l-autonomous-run-governance/commands/speckit.parallel-autonomous-consolidate.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,13 @@ | ||
| --- | ||
| description: Consolidate campaign results under explicit current authority. | ||
| --- | ||
|
|
||
| For `AlternativeSolutions`, require a named human-selected worker and reject | ||
| automatic scoring or merging of several candidates. | ||
|
|
||
| For `MergeAndSync`, require every eligible worker to be `ReadyForMerge` with an | ||
| exact reviewed head, passing required checks, no actionable review thread, and | ||
| current explicit merge authority. Cross the all-ready barrier before the first | ||
| merge. Revalidate immediately before each merge, follow declared order, and | ||
| stop after the first failure. Record already merged and remaining workers; | ||
| never claim cross-repository atomicity. |
9 changes: 9 additions & 0 deletions
9
...rallel-autonomous-run-governance/commands/speckit.parallel-autonomous-resume.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| --- | ||
| description: Resume a stopped or interrupted campaign after complete revalidation. | ||
| --- | ||
|
|
||
| Revalidate campaign manifest hash, repositories, worktrees, branches, current | ||
| authority, runner profile, worker result contracts, autonomous states, | ||
| completed handoffs, and the last trustworthy operation. Reuse verified | ||
| completed work. Retry only an unproven or incomplete operation. Reconcile | ||
| current mandatory governance deltas before scheduling. |
11 changes: 11 additions & 0 deletions
11
...rallel-autonomous-run-governance/commands/speckit.parallel-autonomous-status.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,11 @@ | ||
| --- | ||
| description: Inspect a parallel autonomous campaign without changing it. | ||
| --- | ||
|
|
||
| Read the campaign manifest, state, runtime result files, Git worktrees, and | ||
| referenced autonomous states. Report queued, running, completed, failed, | ||
| blocked, interrupted, and ready workers; observed concurrency; missing or stale | ||
| evidence; stop state; selection state; and the next exact action. | ||
|
|
||
| Status is read-only. A running marker without a trustworthy live process or | ||
| result is `Interrupted`, never success. |
8 changes: 8 additions & 0 deletions
8
...parallel-autonomous-run-governance/commands/speckit.parallel-autonomous-stop.md
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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,8 @@ | ||
| --- | ||
| description: Request a cooperative stop at parallel campaign safe boundaries. | ||
| --- | ||
|
|
||
| Set the campaign stop request after validating identity. Start no new workers. | ||
| Do not kill agent, test, build, provider, or merge processes. Let active workers | ||
| reach their existing autonomous safe boundary, then persist `PausedByUser` or | ||
| `Interrupted` from observed evidence. |
Oops, something went wrong.
Oops, something went wrong.
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.
Uh oh!
There was an error while loading. Please reload this page.