From e90d89b6cc04075d6fae0faa6c28be6a59ebee10 Mon Sep 17 00:00:00 2001 From: Timor Gruber Date: Sat, 15 Aug 2026 16:21:13 +0300 Subject: [PATCH] replace Spec Kit workflow preset Port the preset to the approved RFC-backed lifecycle with\ncommand-aligned artifacts, reviewed task packages, and isolated\npacket execution.\n\nRemove the legacy protocol, analysis surface, and compatibility\npreflight rather than retaining incompatible migration paths. --- .../presets/timors-agentic-workflow/README.md | 199 +++-------- .../commands/speckit.analyze.md | 235 ------------ .../commands/speckit.clarify.md | 31 ++ .../commands/speckit.implement.md | 285 +++------------ .../commands/speckit.plan.md | 98 ++--- .../commands/speckit.specify.md | 67 ++-- .../commands/speckit.tasks.md | 234 ++---------- .../timors-agentic-workflow/preset.yml | 79 ++--- .../references/analysis-and-approval.md | 335 ------------------ .../references/artifact-contracts.md | 31 ++ .../references/artifact-validation.md | 291 --------------- .../references/checkpoint-integration.md | 50 --- .../references/clarification.md | 21 ++ .../references/concurrency-policy.md | 69 ---- .../references/decomposition.md | 80 ----- .../references/documentation-planning.md | 66 ++-- .../references/execution-lifecycle.md | 160 +++------ .../references/feature-definition.md | 25 ++ .../references/human-review.md | 73 ---- .../references/model-and-worker-selection.md | 90 ++--- .../references/planning-grounding.md | 91 +---- .../references/protocol-compatibility.md | 127 ------- .../references/review-lifecycle.md | 35 ++ .../references/rfc-planning.md | 40 +++ .../references/scheduling-policy.md | 21 ++ .../references/task-planning.md | 107 ++++++ .../references/testable-work.md | 64 ++-- .../references/workspace-isolation.md | 90 ++--- .../reviewers/artifact-fidelity.md | 54 --- .../reviewers/component-docs.md | 14 + .../reviewers/decomposition-design.md | 60 ---- .../reviewers/plan-clarity.md | 44 --- .../reviewers/rfc-clarity.md | 14 + .../reviewers/rfc-design.md | 15 + .../reviewers/tasks-executability.md | 18 + .../reviewers/tasks-rfc-fidelity.md | 14 + .../templates/analysis-template.md | 55 --- .../templates/execution-plan-template.md | 221 ------------ .../templates/grounding-notes-template.md | 18 + .../templates/plan-template.md | 75 ++-- .../templates/progress-template.md | 79 ++--- .../templates/research-template.md | 19 + .../templates/review-report-template.md | 58 ++- .../templates/spec-template.md | 43 +++ .../templates/subplan-template.md | 66 ++++ .../templates/tasks-template.md | 123 +++---- .../tests/test_human_review_contract.py | 202 ----------- 47 files changed, 1095 insertions(+), 3191 deletions(-) delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.analyze.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.clarify.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/analysis-and-approval.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-validation.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/checkpoint-integration.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/clarification.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/concurrency-policy.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/decomposition.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/feature-definition.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/human-review.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/protocol-compatibility.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/rfc-planning.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/scheduling-policy.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/references/task-planning.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/reviewers/artifact-fidelity.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/reviewers/component-docs.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/reviewers/decomposition-design.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-clarity.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-design.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-executability.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-rfc-fidelity.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/templates/analysis-template.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/templates/execution-plan-template.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/templates/grounding-notes-template.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/templates/research-template.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/templates/spec-template.md create mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/templates/subplan-template.md delete mode 100644 private_dot_config/specify/presets/timors-agentic-workflow/tests/test_human_review_contract.py diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/README.md b/private_dot_config/specify/presets/timors-agentic-workflow/README.md index 274df476..318ecf91 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/README.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/README.md @@ -1,177 +1,58 @@ # Timor's Agentic Workflow -`timors-agentic-workflow` is a project-installed Spec Kit preset that adds -grounded planning, optional human review, and validated execution artifacts -while preserving upstream requirements and clarification commands. +Preset `0.3.0` supplies one project-installed lifecycle: -- **Preset version**: `0.2.1` -- **Spec Kit compatibility**: `>=0.12.11` -- **Protocol version**: `0.1.0` +`specify` → `clarify` when Draft → `plan` → `tasks` → `implement`. -The installed manifest is the compatibility authority. Every composed or -replaced command completes the installed shared package-integrity gate before -hooks, scripts, dispatch, or writes. The gate fails only for a version below the -minimum, an explicit installed-manifest exclusion, or a missing, malformed, or -incoherent required package contract. A newer untested CLI version does not -produce a warning, prompt, or block. +`spec.md` is the Feature Definition, `plan.md` is the sole normative RFC, +`tasks.md` and `subplans/` are the reviewed execution package, and ignored local +`progress.md` is coordinator runtime evidence. Design Acceptance precedes task +creation; Implementation Authorization precedes mutation. -## Provided Surfaces +## Installation and Refresh -| Surface | Strategy | Installed source | -|---------|----------|------------------| -| `speckit.specify` | Composed (`wrap`) | `commands/speckit.specify.md` | -| `speckit.plan` | Composed (`wrap`) | `commands/speckit.plan.md` | -| `plan-template` | Composed (`wrap`) | `templates/plan-template.md` | -| `speckit.tasks` | Replaced | `commands/speckit.tasks.md` | -| `tasks-template` | Replaced | `templates/tasks-template.md` | -| `speckit.analyze` | Replaced | `commands/speckit.analyze.md` | -| `speckit.implement` | Replaced | `commands/speckit.implement.md` | -| `execution-plan-template` | Replaced | `templates/execution-plan-template.md` | -| `analysis-template` | Replaced | `templates/analysis-template.md` | -| `review-report-template` | Replaced | `templates/review-report-template.md` | -| `progress-template` | Replaced | `templates/progress-template.md` | - -The composed specify command retains active lower-layer specification behavior -and adds optional human review at natural completion. The composed plan retains -active lower-layer planning behavior, adds grounding, and offers the same -optional review at natural completion. Both native `wrap` commands inherit -lower-layer `scripts` and `agent_scripts` metadata. `speckit.clarify` remains -upstream. The task, analysis, and implementation replacements operate on the -preset protocol; analyze does not offer this human-review interaction. - -The review offer is independent for specification and planning: users may take -a guided walkthrough, review the key artifacts independently, or continue -without either. It stores no preference, approval record, or workflow gate. -The shared `references/human-review.md` owns the interaction mechanics, while -the commands name phase-specific conceptual concerns. - -## Install In A Project - -Chezmoi manages the global source package, but it does not activate the preset -for a project. From the project root, initialize Spec Kit if needed, then -install the preset explicitly: +Chezmoi manages the global distribution source but does not activate a project. +From a project root: ```sh specify init --here --integration opencode --ignore-agent-tools specify preset add --dev "$HOME/.config/specify/presets/timors-agentic-workflow" ``` -The direct `specify preset add --dev` command copies the source into the -project's `.specify/presets/timors-agentic-workflow/` and generates the active -integration's command files. The copy is independent of the global source; -global changes take effect in a project only after an explicit refresh. - -Refresh a development install by removing and adding it again when distributing -a changed preset source: +Project copies remain pinned. To distribute a source update, the operator +performs this explicit remove/add refresh: ```sh specify preset remove timors-agentic-workflow specify preset add --dev "$HOME/.config/specify/presets/timors-agentic-workflow" ``` -## Diagnose Installation And Resolution - -Run these commands from the project root: - -```sh -specify preset list -specify preset info timors-agentic-workflow -specify preset resolve plan-template -specify preset resolve tasks-template -specify preset resolve execution-plan-template -specify preset resolve analysis-template -specify preset resolve review-report-template -specify preset resolve progress-template -``` - -All six listed templates should resolve through `timors-agentic-workflow`. -During the non-normative Spec Kit `0.12.11` installation validation, `preset -resolve` accepted templates only, so command names reported as not found rather -than identifying their source. Verify the five installed command surfaces by -checking the generated OpenCode files for project-relative -`.specify/presets/timors-agentic-workflow/` references; those files must never -contain the global source path. `speckit.clarify` remains upstream and outside -this preset. - -## Artifact And State Ownership - -The project tracks the installed preset copy, generated integration commands, -normal Spec Kit design artifacts, `plan.md`, `tasks.md`, -`execution-plan.md`, `reviews/*.md`, and `analysis.md`. Only -`specs/**/progress.md` is ignored: it is local runtime state and can contain -binding, workspace, checkpoint, failure, and test evidence. - -`tasks.md` owns atomic task records and checkboxes. `execution-plan.md` owns -execution groups and orchestration. Role reports own cumulative findings, and -`analysis.md` owns aggregate review state and human approval. `progress.md` -owns local execution state. - -The chezmoi source package is the editable distribution source. The installed -project copy is an informational, refresh-replaceable copy used by command -resolution. Commands read installed preset files but never mutate the installed -copy or its README. - -## Adoption And Lifecycle - -- A project with only `spec.md` follows the normal enhanced flow: run plan, - then tasks, analyze, and implement as applicable. -- A feature with `plan.md` and no `tasks.md` reruns `/speckit.plan` before - task generation. -- A feature with upstream `tasks.md` and no conforming `execution-plan.md` - reruns `/speckit.tasks`. -- A malformed, unsupported, missing, or nonconforming task/execution-plan pair - reruns `/speckit.tasks`; this release defines no migration, repair, or - inferred protocol data. -- A conforming task/execution-plan pair with missing or nonconforming role - reports or `analysis.md` reruns `/speckit.analyze`. Replace an unparseable - report only after explicit human confirmation so cumulative findings and an - existing approval decision are not silently discarded. -- A feature already executing through upstream behavior or another preset must - finish or be explicitly abandoned before adoption. Mixed execution semantics - are rejected. - -Removing the preset is safe before enhanced artifacts exist. For planned work -that has not started execution, revert the enhanced artifacts or retain them as -inert history; do not treat them as core implementation plans. For in-flight -work, finish with the installed preset, pause with the pinned preset and local -state retained, or explicitly abandon back to the recorded execution base. -Never automatically delete branches, worktrees, checkpoint refs, dirty output, -progress, or feature artifacts. - -When changing CLI versions, retain the installed preset unless its shared gate -reports a concrete failure. Refresh a project-installed preset only to -distribute changed preset source, then verify its package and resolution state. -The preset does not require a review or release for each new CLI minor version; -a future manifest may add a constraint only for a known incompatibility. - -## No-Probe Semantics And Limitations - -The preset defines data contracts, not worker provisioning, provider/model -bindings, or runtime-specific behavior. Binding discovery and checks use runtime -metadata and configuration; no suitability probe, calibration task, canary, -sacrificial invocation, or model call occurs before real assigned work. The -first dispatch is the real review or execution assignment. - -Installation and resolution validation prove packaging and materialization, not -semantic compatibility or runtime operation. Operational support requires a -normal feature to complete the required real-work handshake. The preset does -not migrate existing artifacts, does not automatically refresh project copies, -and cannot safely be removed during active execution. - -## Operational Status - -> This is a non-normative installation observation, not a runtime-support or -> binding guarantee. It contains no provider, model, or sensitive binding data. - -- **Installation**: Verified by temporary source-to-target materialization, - project installation, resolution, refresh, and tracking checks. This is - operational history, not a compatibility boundary. -- **Runtime**: Not yet exercised. -- **Preset version**: `0.2.1` -- **Spec Kit version**: `0.12.11` -- **OpenCode version**: `1.17.18` -- **Binding configuration class**: Not exercised. -- **Validation date**: `2026-07-12` - -Installed README copies are informational and refresh-replaceable. Commands -never mutate them. +After installation, manually inspect generated integration files: `specify`, +`clarify`, `plan`, `tasks`, and `implement` must reference the project-relative +installed copy; `analyze` must resolve from a lower layer. This confirmation is +operator-controlled, not a workflow command gate. + +## Execution Boundaries + +Task packages contain provider-neutral tiers and exact skills, not concrete +workers, model IDs, credentials, local workspace paths, or dispatch identities. +Binding is just in time and requires tier, skills, discoverability, invokability, +correct workspace targeting, and attributable results. Project-local candidates +are preferred; ambiguity requires a human choice. Runtime considerations neither +grant access nor alter eligibility. + +Each packet has a dedicated branch and worktree. Workers may commit only there; +the coordinator alone advances the active branch. The approved tracked feature +directory is immutable during execution and is compared at dispatch, result +acceptance, rebase, and integration. Packet branches integrate in topological +order as one repository-policy-compliant commit per packet. Nothing is pushed. + +## Replacement Cautions + +This release performs no migration. It does not interpret old atomic task lists, +old execution or review artifacts, or old local runtime state. A non-executing +old feature starts again at `specify`. Before replacement, finish or explicitly +abandon an in-flight old run while its old installed copy remains available. +Premature replacement has no automatic detection, rollback, or repair: manually +restore the old preset to recover it, or preserve old state and start a fresh +lifecycle. Do not remove an active package expecting this preset to resume it. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.analyze.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.analyze.md deleted file mode 100644 index 68eec45b..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.analyze.md +++ /dev/null @@ -1,235 +0,0 @@ ---- -description: Perform a non-destructive cross-artifact consistency and quality analysis across spec.md, plan.md, and tasks.md after task generation. -scripts: - sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks - ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks - py: scripts/python/check_prerequisites.py --json --require-tasks --include-tasks ---- - -## Package Integrity Gate - -This is the first operational action. Before extension hooks, prerequisite -scripts, artifact writes, progress or workspace mutation, or dispatch, read and -complete the shared gate in -`.specify/presets/timors-agentic-workflow/references/protocol-compatibility.md`. -Do not duplicate, weaken, or partially apply its minimum-version or complete -package-integrity checks. On any failure, report the failed required contract -and stop before continuing. - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## Pre-Execution Checks - -**Check for extension hooks (before analysis)**: -- Check if `.specify/extensions.yml` exists in the project root. -- If it exists, read it and look for entries under the `hooks.before_analyze` key -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Pre-Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Pre-Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - - Wait for the result of the hook command before proceeding to the Goal. - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. -- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Goal - -Coordinate independent, focused, read-only reviews after -`__SPECKIT_COMMAND_TASKS__` has produced `tasks.md` and `execution-plan.md`. -Persist cumulative source reports, a deterministic aggregate, and an explicit -human approval record. Follow -`.specify/presets/timors-agentic-workflow/references/analysis-and-approval.md` -exactly. - -The coordinator performs no semantic review. It MUST NOT replace a missing or -failed fresh-context reviewer with its own judgment, add a broad review pass, -or repair reviewer conclusions. - -## Operating Constraints - -**READ-ONLY PLANNING REVIEW**: Reviewers receive read access only. Do not modify -`spec.md`, `plan.md`, `tasks.md`, `execution-plan.md`, design artifacts, the -constitution, or reviewer packets. The intended writes are only cumulative -`reviews/.md` reports and aggregate `analysis.md`, and only after both -preflights succeed. - -**Constitution Authority**: The project constitution (`/memory/constitution.md`) -is non-negotiable within review scope. A constitution change must occur through -an explicit owning workflow, never through analysis. - -## Execution Steps - -### 1. Initialize Analysis Context - -Run `{SCRIPT}` once from the repository root and parse `FEATURE_DIR` and -`AVAILABLE_DOCS`. Derive `spec.md`, `plan.md`, `tasks.md`, -`execution-plan.md`, `analysis.md`, and `reviews/` paths under `FEATURE_DIR`. -Abort when any required artifact is missing and direct the user to its owning -command. For single quotes in args like "I'm Groot", use escape syntax such as -`'I'\''m Groot'`, or use double quotes when possible. - -### 2. Run Deterministic Shared Validation - -Read and execute the complete protocol in -`.specify/presets/timors-agentic-workflow/references/artifact-validation.md` -against the current artifacts and selected project-role packets. This installed -reference is the sole source for structural invariants; do not copy, infer, -weaken, or repair its rules. Any failure blocks before report writes or reviewer -dispatch and instructs the user to regenerate invalid execution artifacts with -`__SPECKIT_COMMAND_TASKS__`. - -### 3. Establish Or Resume The Analysis Run - -Apply the run, declaration, trigger-union, selected-role, packet, and recovery -rules in `analysis-and-approval.md`. The initial run selects every core and -project role. Later runs require an explicit human declaration. Resume an -incomplete `ARNN`; never start a newer run while it is incomplete. - -Write `analysis.md` with the run marked `Incomplete` before dispatch and retain -the existing Approval Record unchanged. Retain valid applicable rounds. If an -invocation may have started without an attributable result, record -`Recovery required` and do not redispatch until an explicit human recovery -decision clears that state. - -### 4. Resolve Reviewer Bindings Without Invocation - -Resolve each role independently, project-local before global, using explicit -role preference, a unique preferred/default candidate, the sole eligible -candidate, or explicit human choice. Before invocation, verify the planned -tier, concrete model binding, read access to every required input, native fresh -context, invokability, and attributable-result support from runtime metadata or -configuration. Missing or malformed packets and unavailable or ambiguous -bindings block. - -Do not probe, calibrate, canary, or invoke a candidate to test suitability. The -first invocation is the role's real review. Concrete provider, model, candidate, -and dispatch identifiers are transient and MUST NOT enter tracked reports. - -### 5. Dispatch Focused Reviews - -Dispatch only required unfinished roles, each in an independent fresh context -with its role packet, required read-only inputs, current `ARNN`, trigger, prior -report when present, and the report-template contract. A reviewer cannot edit -planning artifacts. Reject missing, malformed, semantically unattributable, or -schema-invalid results; do not reinterpret or complete them in coordinator -context. Retry only when runtime evidence proves no invocation started. - -Each reviewer progressively loads only its packet's required artifacts, builds -the semantic inventory needed for its bounded question, performs that packet's -detection passes, and assigns the protocol severities. This preserves focused, -high-signal analysis without moving semantic inventories, detection, or -severity judgment into the coordinator. - -Append each valid complete current-snapshot round to its cumulative report. -Record only `Yes` attestations for planned tier, fresh context, and attributable -result after observing the underlying transient evidence. - -### 6. Aggregate Deterministically - -Materialize `analysis.md` from the applicable source rounds without semantic -review. Preserve source IDs, group only findings with the same location, -defect, and correction, use the highest source severity, and expose all -disagreements as reviewer conflicts. Project the role-owned requirement -coverage and execution-plan validation rows without creating new semantic -conclusions. Keep the aggregate compact while retaining the complete current -source records in cumulative role reports. Preserve monotonic, non-reused -aggregate, conflict, and deviation IDs and preserve the Approval Record across -reruns. - -Mark the run `Complete` only when exactly one valid applicable round exists for -every selected role. Compute the aggregate verdict and deviation statuses by -the installed reference. Never infer approval from a verdict and never -automatically revoke or reset a recorded human decision. - -### 7. Provide Next Actions And Approval Gate - -Present the aggregate and request an explicit human decision. Record only -`Pending`, `Approved`, `Changes requested`, or `Approved with deviations`, and -only a human may own deviation decisions and rationale. Enforce the exact -authorization matrix in `analysis-and-approval.md`; incomplete or uncovered -blocking states never authorize implementation. - -Route remediation to the owning workflow. Use -`__SPECKIT_COMMAND_SPECIFY__` for requirements, `__SPECKIT_COMMAND_PLAN__` for -design, `__SPECKIT_COMMAND_TASKS__` for tasks or decomposition, and proceed to -`__SPECKIT_COMMAND_IMPLEMENT__` only when the stored aggregate and Approval -Record authorize it. - -### 8. Offer Remediation - -Ask: "Would you like me to suggest concrete remediation edits for the top N -issues?" Do not apply edits automatically. Any follow-up editing command -requires explicit user approval and runs separately through the owning command. - -### 9. Check for extension hooks - -After reporting, check if `.specify/extensions.yml` exists in the project root. -- If it exists, read it and look for entries under the `hooks.after_analyze` key -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. -- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Operating Principles - -- Preserve reviewer ownership: validate and aggregate source conclusions; do - not create semantic findings in coordinator context. -- Fail closed on missing evidence, invalid artifacts, malformed reports, - unavailable bindings, and incomplete or inconsistent state. -- Store no content hashes, artifact fingerprints, concrete model IDs, candidate - IDs, or dispatch IDs. -- Report zero findings gracefully and still require explicit human approval. - -## Context - -{ARGS} diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.clarify.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.clarify.md new file mode 100644 index 00000000..0c5bdfd4 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.clarify.md @@ -0,0 +1,31 @@ +--- +description: Converge a Feature Definition through one-question human dialogue. +--- + +## Authority and Inputs + +Read canonical `spec.md`, `references/artifact-contracts.md`, +`references/feature-definition.md`, `references/clarification.md`, and +`references/review-lifecycle.md`. `spec.md` is the only authority for product +intent. Do not inspect repository reality or make technical design choices. + +## Procedure + +1. Start from Draft or Ready. Proportionally challenge the stated solution versus + underlying need, consequential assumptions, actors, boundaries, constraints, + failure conditions, and adjacent effects. Do not ask a question already settled + in `spec.md`. +2. If a Ready artifact reveals a material question, first persist it, set Draft, + and apply the ordered invalidation before dialogue. A package lock or completion + refuses a material change. +3. Each assistant turn that needs a human answer asks exactly one direct, + highest-impact question. Explanatory text cannot hide another question. When + there are viable choices, give two or three genuine alternatives, concrete + tradeoffs, and a reasoned recommendation; retain human decision ownership. +4. Immediately after each answer, update all affected Feature Definition sections, + remove contradictions and resolved questions, record consequential decision + context, apply invalidation, and rescan the complete Ready predicate. Do not + batch unanswered questions or silently select an answer. +5. Mark Ready only when the complete predicate holds. A pause or declined material + choice remains explicitly recorded and Draft. Report either the one next + question or the Ready handoff to `plan`. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.implement.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.implement.md index 5b6c0749..4e40a8d8 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.implement.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.implement.md @@ -1,241 +1,50 @@ --- -description: Execute the implementation plan by processing and executing all tasks defined in tasks.md -scripts: - sh: scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks - ps: scripts/powershell/check-prerequisites.ps1 -Json -RequireTasks -IncludeTasks - py: scripts/python/check_prerequisites.py --json --require-tasks --include-tasks +description: Execute approved sub-plans in isolated worktrees and integrate packet commits. --- -## Package Integrity Gate - -This is the first operational action. Before extension hooks, prerequisite -scripts, artifact writes, progress or workspace mutation, or dispatch, read and -complete the shared gate in -`.specify/presets/timors-agentic-workflow/references/protocol-compatibility.md`. -Do not duplicate, weaken, or partially apply its minimum-version or complete -package-integrity checks. On any failure, report the failed required contract -and stop before continuing. - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## Mandatory Preset Preflight - -After the Package Integrity Gate passes, but before reading or invoking -extension hooks, running `{SCRIPT}`, creating or updating progress, mutating a -workspace or project file, creating or switching a branch or worktree, or -dispatching a worker: - -1. Read `.specify/presets/timors-agentic-workflow/references/execution-lifecycle.md` and complete its remaining Command-Wide Preflight in order. -2. For its structural validation step, consume the unchanged installed `.specify/presets/timors-agentic-workflow/references/artifact-validation.md` as the shared deterministic validator used by analyze. Do not reproduce its invariants in this command. - -Fail closed before hooks, scripts, writes, workspace operations, or dispatch. The analysis/report/approval checks establish structural consumption safety; do not perform a new semantic review or revoke an authorized result. - -## Pre-Execution Checks - -**Check for extension hooks (before implementation)**: -- Check if `.specify/extensions.yml` exists in the project root. -- If it exists, read it and look for entries under the `hooks.before_implement` key -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Pre-Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Pre-Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - - Wait for the result of the hook command before proceeding to the Outline. - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. -- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Outline - -1. Run `{SCRIPT}` from repo root and parse FEATURE_DIR and AVAILABLE_DOCS list. All paths must be absolute. For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). Confirm the returned feature directory is the exact directory validated by the Mandatory Preset Preflight. If it differs, stop and rerun the complete preflight against the returned directory before any further mutation. - -2. **Check checklists status** (if FEATURE_DIR/checklists/ exists): - - Scan all checklist files in the checklists/ directory - - For each checklist, count: - - Total items: All lines matching `- [ ]` or `- [X]` or `- [x]` - - Completed items: Lines matching `- [X]` or `- [x]` - - Incomplete items: Lines matching `- [ ]` - - Create a status table: - - ```text - | Checklist | Total | Completed | Incomplete | Status | - |-----------|-------|-----------|------------|--------| - | ux.md | 12 | 12 | 0 | ✓ PASS | - | test.md | 8 | 5 | 3 | ✗ FAIL | - | security.md | 6 | 6 | 0 | ✓ PASS | - ``` - - - Calculate overall status: - - **PASS**: All checklists have 0 incomplete items - - **FAIL**: One or more checklists have incomplete items - - - **If any checklist is incomplete**: - - Display the table with incomplete item counts - - **STOP** and ask: "Some checklists are incomplete. Do you want to proceed with implementation anyway? (yes/no)" - - Wait for user response before continuing - - If user says "no" or "wait" or "stop", halt execution - - If user says "yes" or "proceed" or "continue", proceed to step 3 - - - **If all checklists are complete**: - - Display the table showing all checklists passed - - Automatically proceed to step 3 - -3. Load and analyze the implementation context: - - **REQUIRED**: Read tasks.md for the complete task list and execution plan - - **REQUIRED**: Read plan.md for tech stack, architecture, and file structure - - **REQUIRED**: Read execution-plan.md for validated groups, dependencies, ownership, models, skills, capabilities, contracts, tests, acceptance criteria, and verification - - **IF EXISTS**: Read data-model.md for entities and relationships - - **IF EXISTS**: Read contracts/ for API specifications and test requirements - - **IF EXISTS**: Read research.md for technical decisions and constraints - - **IF EXISTS**: Read /memory/constitution.md for governance constraints - - **IF EXISTS**: Read quickstart.md for integration scenarios - -4. **Project Setup Verification**: - - **REQUIRED**: Create/verify ignore files based on actual project setup: - - **Detection & Creation Logic**: - - Check if the following command succeeds to determine if the repository is a git repo (create/verify .gitignore if so): - - ```sh - git rev-parse --git-dir 2>/dev/null - ``` - - - Check if Dockerfile* exists or Docker in plan.md → create/verify .dockerignore - - Check if .eslintrc* exists → create/verify .eslintignore - - Check if eslint.config.* exists → ensure the config's `ignores` entries cover required patterns - - Check if .prettierrc* exists → create/verify .prettierignore - - Check if .npmrc or package.json exists → create/verify .npmignore (if publishing) - - Check if terraform files (*.tf) exists → create/verify .terraformignore - - Check if .helmignore needed (helm charts present) → create/verify .helmignore - - **If ignore file already exists**: Verify it contains essential patterns, append missing critical patterns only - **If ignore file missing**: Create with full pattern set for detected technology - **Progress ignore seam**: Before creating progress, ensure `specs//progress.md` is ignored by an appropriate project ignore mechanism. Never add progress to a checkpoint. - - **Common Patterns by Technology** (from plan.md tech stack): - - **Node.js/JavaScript/TypeScript**: `node_modules/`, `dist/`, `build/`, `*.log`, `.env*` - - **Python**: `__pycache__/`, `*.pyc`, `.venv/`, `venv/`, `dist/`, `*.egg-info/` - - **Java**: `target/`, `*.class`, `*.jar`, `.gradle/`, `build/` - - **C#/.NET**: `bin/`, `obj/`, `*.user`, `*.suo`, `packages/` - - **Go**: `*.exe`, `*.test`, `vendor/`, `*.out` - - **Ruby**: `.bundle/`, `log/`, `tmp/`, `*.gem`, `vendor/bundle/` - - **PHP**: `vendor/`, `*.log`, `*.cache`, `*.env` - - **Rust**: `target/`, `debug/`, `release/`, `*.rs.bk`, `*.rlib`, `*.prof*`, `.idea/`, `*.log`, `.env*` - - **Kotlin**: `build/`, `out/`, `.gradle/`, `.idea/`, `*.class`, `*.jar`, `*.iml`, `*.log`, `.env*` - - **C++**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.so`, `*.a`, `*.exe`, `*.dll`, `.idea/`, `*.log`, `.env*` - - **C**: `build/`, `bin/`, `obj/`, `out/`, `*.o`, `*.a`, `*.so`, `*.exe`, `*.dll`, `autom4te.cache/`, `config.status`, `config.log`, `.idea/`, `*.log`, `.env*` - - **Swift**: `.build/`, `DerivedData/`, `*.swiftpm/`, `Packages/` - - **R**: `.Rproj.user/`, `.Rhistory`, `.RData`, `.Ruserdata`, `*.Rproj`, `packrat/`, `renv/` - - **Universal**: `.DS_Store`, `Thumbs.db`, `*.tmp`, `*.swp`, `.vscode/`, `.idea/` - - **Tool-Specific Patterns**: - - **Docker**: `node_modules/`, `.git/`, `Dockerfile*`, `.dockerignore`, `*.log*`, `.env*`, `coverage/` - - **ESLint**: `node_modules/`, `dist/`, `build/`, `coverage/`, `*.min.js` - - **Prettier**: `node_modules/`, `dist/`, `build/`, `coverage/`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` - - **Terraform**: `.terraform/`, `*.tfstate*`, `*.tfvars`, `.terraform.lock.hcl` - - **Kubernetes/k8s**: `*.secret.yaml`, `secrets/`, `.kube/`, `kubeconfig*`, `*.key`, `*.crt` - -5. Initialize or resume ignored `FEATURE_DIR/progress.md` from `.specify/presets/timors-agentic-workflow/templates/progress-template.md`. Apply the exact resume matrix in `execution-lifecycle.md` before dispatch. Missing local state never causes automatic redispatch. - -6. Parse tasks.md and the validated execution plan without changing either: - - Preserve the canonical task IDs, current checkbox lines, task phases (Setup, Tests, Core, Integration, Polish), and TDD ordering. - - Use only canonical execution groups, explicit dependencies, Execution Order, Concurrency Policy, File Ownership, model tier, exact skills, exact capabilities, contracts, Test Expectation, acceptance criteria, and verification. - - Construct each packet only by the canonical join defined in `execution-lifecycle.md`, including prerequisite outputs through `DFNN` and `CTNN`. - - Never invent, remove, regroup, or revise planned execution data. - -7. Execute implementation by applying, in order: - - `.specify/presets/timors-agentic-workflow/references/execution-lifecycle.md` - - `.specify/presets/timors-agentic-workflow/references/workspace-isolation.md` - - `.specify/presets/timors-agentic-workflow/references/checkpoint-integration.md` - - Run the ready-group gate immediately before each group mutates a workspace, edits, or dispatches. A parallel set starts only after every member passes. Keep tests with the same bound implementation worker. Do not invoke `executing-plans`, provision runtime workers through this preset, or permit child-agent dispatch. - -8. Progress tracking and error handling: - - Report progress after each attributable transition and preserve the exact template sections, tables, columns, and states. - - Halt execution if any non-parallel task fails. - - For policy-permitted parallel groups, continue with successful independent groups only as allowed by the validated dependencies and report failed groups. - - Provide clear error messages with context for debugging. - - Suggest next steps if implementation cannot proceed. - - **IMPORTANT** Mark covered tasks `[X]` only in the completion order defined by `execution-lifecycle.md`, after integration, verification, signed checkpoint creation, and persisted evidence. - -9. Completion validation: - - Verify all required tasks are completed and all execution groups are `done`. - - Check that implemented features match the original specification without changing acceptance criteria. - - Validate that tests pass and planned coverage/evidence requirements are met. - - Confirm the implementation follows the technical plan and validated execution plan. - - Run final verification, retain the signed tip at `refs/agent-checkpoints/`, record the checkpoint range, and prepare the aggregate dirty diff exactly as required by `checkpoint-integration.md`. - -Note: This command assumes a complete task breakdown and protocol-valid execution plan exist. If tasks are incomplete or artifacts fail deterministic validation, suggest running `__SPECKIT_COMMAND_TASKS__` to regenerate the task list and execution artifacts. - -## Mandatory Post-Execution Hooks - -**You MUST complete this section before reporting completion to the user.** - -Check if `.specify/extensions.yml` exists in the project root. -- If it does not exist, or no hooks are registered under `hooks.after_implement`, skip to the Completion Report. -- If it exists, read it and look for entries under the `hooks.after_implement` key. -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue to the Completion Report. -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**: - ``` - ## Extension Hooks - - **Automatic Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - -## Completion Report - -Report final status with summary of completed work, retained checkpoint ref/range, aggregate dirty-diff location, verification, blocked or recovery-required state, and any retained workspaces. - -## Done When - -- [ ] The compatibility, shared artifact-validation, report-consistency, and authorizing Approval Record gates passed before hooks, scripts, mutations, or dispatch -- [ ] All tasks in tasks.md completed and marked `[X]` only after their groups' signed checkpoints and evidence -- [ ] Implementation validated against specification, plan, execution plan, and planned test coverage -- [ ] Final verification passed and the retained checkpoint ref/range plus aggregate dirty diff are recorded -- [ ] Extension hooks dispatched or skipped according to the rules in Mandatory Post-Execution Hooks above -- [ ] Completion reported to user with summary of completed work +## Authority and Inputs + +Require Ready canonical `spec.md`; canonical `plan.md` Design Acceptance Accepted +for its current Revision; a closed, reviewed `tasks.md`; `authorization: approved`; +and a fully clean, named, stable active branch. Read +`references/artifact-contracts.md`, `references/execution-lifecycle.md`, +`references/workspace-isolation.md`, `references/scheduling-policy.md`, +`references/model-and-worker-selection.md`, `references/testable-work.md`, and +`references/documentation-planning.md`. Use `templates/progress-template.md` and, +when required, `reviewers/component-docs.md` with +`templates/review-report-template.md`. + +## Procedure + +1. Perform the concrete phase checks in `references/execution-lifecycle.md`; do + not redesign the approved package. Resolve, pin, and later refresh signing + policy exactly under `references/workspace-isolation.md`. Add the exact local + progress path to `.git/info/exclude` after clean preflight, then create initial + progress from its template. Creation is the lock event and records active branch, + starting commit, complete protected baseline, and policy evidence. +2. For each ready canonical identity, validate closed package structure, selected + tracked regular file, predecessor status and contract evidence, ownership, test + mode/basis, and baseline equality. Bind a worker under + `references/model-and-worker-selection.md`. Create a dedicated branch/worktree, + derive and record its worktree-root-relative locator, and dispatch only the + identity, locator, invocation-specific constraints, prerequisite evidence, + recovery context, and limited result envelope. Do not copy packet prose into + the prompt. +3. Let `references/scheduling-policy.md` control waves. Workers may browse but not + expand authority, modify protected feature files, rewrite history, merge + unrelated work, or push. Validate returned changed paths, commits, verification, + output evidence, runtime outcomes, attribution, clean branch, and baseline at + result acceptance. Follow its narrow retry and recovery rules. +4. Before each rebase, squash, candidate construction, corrective commit, and + integration, refresh signing-policy evidence. Rebase in approved topological + order, recheck the baseline, construct a separately inspectable candidate, + verify tree and applicable signature, then fast-forward exactly one packet + commit. Use Worktrunk only after its required non-mutating capability proof; + otherwise use the plain-Git fallback. Record final commit and contract output + evidence before a consumer is ready. +5. After all packets are done, run aggregate verification and the required + independent component-documentation review. Correct only bounded in-scope work + with a policy-compliant corrective commit, then rerun affected gates. New scope, + design, contract, or acceptance exceptions return to their owning phase. Report + every test mode, verification outcome, runtime condition, alternative, residual + limitation, final commit, blocker, and final status; do not push. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.plan.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.plan.md index 21f4470e..38487c8d 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.plan.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.plan.md @@ -1,65 +1,39 @@ --- -description: Execute the implementation planning workflow using the plan template to generate design artifacts. -handoffs: - - label: Create Tasks - agent: speckit.tasks - prompt: Break the plan into tasks - send: true - - label: Create Checklist - agent: speckit.checklist - prompt: Create a checklist for the following domain... +description: Ground, design, review, and obtain acceptance for the normative RFC. --- -## Package Integrity Gate - -This is the first operational action. Before extension hooks, prerequisite -scripts, artifact writes, progress or workspace mutation, or dispatch, read and -complete the shared gate in -`.specify/presets/timors-agentic-workflow/references/protocol-compatibility.md`. -Do not duplicate, weaken, or partially apply its minimum-version or complete -package-integrity checks. On any failure, report the failed required contract -and stop before continuing. - -## Preset Planning Composition - -Use `.specify/presets/timors-agentic-workflow/references/planning-grounding.md` -as the policy for the four added plan sections and feature reuse. Keep the -upstream planning workflow and artifact ownership intact: decisions belong in -`research.md`; data details belong in `data-model.md` and `contracts/`; and -execution decomposition belongs in `execution-plan.md`, not `plan.md`. - -## Completion Report And Handoff Deferral - -Execute the complete upstream workflow, including artifact generation, -validation, and mandatory post-execution hooks. Do not emit the upstream final -Completion Report or perform its handoffs until the optional human-review step -below has completed or is declined. Defer only final reporting and handoffs. - -{CORE_TEMPLATE} - -## Optional Planning Human Review - -After the upstream planning workflow has generated and validated its artifacts, -apply `.specify/presets/timors-agentic-workflow/references/human-review.md` at -this natural completion point before the final completion reporting and -handoffs. Preserve all upstream planning behavior; this wrapper adds only the -optional review offer. - -Treat the current `spec.md` requirements, scenarios, boundaries, and success -criteria as authoritative inputs. Review only technical/design decisions -introduced or derived during planning. A plan choice that follows directly from -the specification and does not introduce a meaningful planning choice must not -be presented merely to reconfirm the specification. If the plan contradicts the -specification, correct the plan rather than reopen the specification. If -planning discovers a concrete contradiction, infeasibility, or material omission -that cannot be corrected within planning ownership, identify the blocker and -route it to the stock owning workflow; do not relitigate it inside planning -review. - -For a guided walkthrough, use judgment to select consequential conceptual -units. Consider, when consequential: technical approach/research decisions; -current-state/architecture/project fit; interfaces/integration/data/contracts; -constraints/compatibility/constitution; testing/validation; and documentation -impact/unresolved design choices. Keep the interaction mechanics in the shared -protocol rather than turning this into a literal artifact or section -walkthrough. +## Authority and Inputs + +Require canonical `spec.md` with status Ready. Read +`references/artifact-contracts.md`, `references/planning-grounding.md`, +`references/rfc-planning.md`, `references/review-lifecycle.md`, +`references/model-and-worker-selection.md`, and reviewer packets +`reviewers/rfc-design.md` and `reviewers/rfc-clarity.md`. Use +`templates/grounding-notes-template.md`, `templates/research-template.md`, +`templates/plan-template.md`, and `templates/review-report-template.md`. A project +constitution is optional governance input. `plan.md` is the sole normative RFC. + +## Procedure + +1. Gather cheap delegated observations, normalize sources, facts, bounded + inferences, relevance, and unknowns in `grounding-notes.md`, and centrally + verify material claims. Keep recommendations out of that artifact. Use + `research.md` for evidence, genuine alternatives, working decisions, + consequences, and technical questions. +2. Ask one adaptive consequential technical question at a time when human input is + needed; routine implementation detail remains planner-owned. Surface repository + evidence that contradicts intent. Correct only non-semantic metadata or an + unambiguous transcription in `spec.md`; any other correction returns it to + Draft and `clarify` before this command continues. +3. Write a self-contained RFC that restates every durable decision needed by task + planning. Classify changes before writing, apply Revision, acceptance, and + review-pointer transitions exactly as `references/rfc-planning.md` requires, + and refuse a material change after the package lock. +4. Bind, invoke, and record independent design and clarity reviews under + `references/review-lifecycle.md`. Remediate accepted findings. Rerun only + applicable scope; retain unaffected roles only through the stated retained + pointer transition. At review quiescence present one collected blocker + interaction. A started incomplete review uses recovery, never self-review. +5. Request Design Acceptance only when both pointers are current, attributable, + and non-blocking for the current RFC Revision. Record the human decision and + rationale in `plan.md`. Only current Revision Accepted permits `tasks`. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.specify.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.specify.md index f3ea2f75..0b41dd31 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.specify.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.specify.md @@ -1,38 +1,35 @@ --- -description: Create or update the feature specification from a natural language feature description. +description: Create or reconcile a Feature Definition without interactive questions. --- -## Package Integrity Gate - -This is the first operational action. Before extension hooks, prerequisite -scripts, artifact writes, progress or workspace mutation, or dispatch, read and -complete the shared gate in -`.specify/presets/timors-agentic-workflow/references/protocol-compatibility.md`. -Do not duplicate, weaken, or partially apply its minimum-version or complete -package-integrity checks. On any failure, report the failed required contract -and stop before continuing. - -## Completion Report And Handoff Deferral - -Execute the complete upstream workflow, including artifact generation, -validation, and mandatory post-execution hooks. Do not emit the upstream final -Completion Report or perform its handoffs until the optional human-review step -below has completed or is declined. Defer only final reporting and handoffs. - -{CORE_TEMPLATE} - -## Optional Specification Human Review - -After the upstream specification workflow has generated and validated its -artifacts, apply -`.specify/presets/timors-agentic-workflow/references/human-review.md` at this -natural completion point before the final completion reporting and handoffs. -Preserve all upstream specification behavior; this wrapper adds only the -optional review offer. - -For a guided walkthrough, use judgment to select consequential conceptual -units. Consider, when consequential: problem/outcome/scope; -scenarios/priorities; acceptance behavior/edge cases; requirements; -assumptions/dependencies/clarifications; and measurable success criteria. Keep -the interaction mechanics in the shared protocol rather than turning this into -a literal artifact or section walkthrough. +## Authority and Inputs + +Read supplied intent, canonical feature `spec.md` when present, +`references/artifact-contracts.md`, `references/feature-definition.md`, and +`references/review-lifecycle.md`. Render `templates/spec-template.md`. `spec.md` +is the product-intent authority. Do not inspect the repository, ask a question, +choose technical architecture, or supply a default. + +## Procedure + +1. Construct or reconcile the complete Feature Definition from positive supplied + information only. Preserve semantically titled requirements and their inline + acceptance evidence. Include conditional actors, journeys, failures, risks, + accessibility, localization, compatibility, or operations only when relevant. +2. Scan every Ready criterion in `references/feature-definition.md`. When any + criterion is not positively established, record every material unanswered + question in `Material Open Questions`, set `status: Draft`, and do not infer a + resolution. Otherwise set `status: Ready` and state why it satisfies the + predicate. +3. Before a material write, check whether local `progress.md` exists with a locked + in-progress, blocked, or complete package. If so, refuse the change. Before a + permitted material write, make the ordered invalidations in + `references/review-lifecycle.md`; do not erase downstream artifacts or prior + review history. +4. Report the canonical path, status, material questions, invalidated records, and + only the next permitted phase: Draft hands off to `clarify`; Ready may hand off + to `plan`. + +Missing, partial, or contradictory state blocks its consumer when that consumer +reads it. Do not add a package, manifest, installed-inventory, mapping, or version +preflight. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.tasks.md b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.tasks.md index df6615f8..1aee4975 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.tasks.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/commands/speckit.tasks.md @@ -1,198 +1,42 @@ --- -description: Generate an actionable, dependency-ordered tasks.md for the feature based on available design artifacts. -handoffs: - - label: Analyze For Consistency - agent: speckit.analyze - prompt: Run a project analysis for consistency - send: true - - label: Implement Project - agent: speckit.implement - prompt: Start the implementation in phases - send: true -scripts: - sh: scripts/bash/setup-tasks.sh --json - ps: scripts/powershell/setup-tasks.ps1 -Json - py: scripts/python/setup_tasks.py --json +description: Produce, review, and authorize an immutable sub-plan task package. --- -## Package Integrity Gate - -This is the first operational action. Before extension hooks, prerequisite -scripts, artifact writes, progress or workspace mutation, or dispatch, read and -complete the shared gate in -`.specify/presets/timors-agentic-workflow/references/protocol-compatibility.md`. -Do not duplicate, weaken, or partially apply its minimum-version or complete -package-integrity checks. On any failure, report the failed required contract -and stop before continuing. - -## User Input - -```text -$ARGUMENTS -``` - -You **MUST** consider the user input before proceeding (if not empty). - -## Pre-Execution Checks - -**Check for extension hooks (before tasks generation)**: -- Check if `.specify/extensions.yml` exists in the project root. -- If it exists, read it and look for entries under the `hooks.before_tasks` key -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue normally -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Pre-Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - - **Mandatory hook** (`optional: false`): - ``` - ## Extension Hooks - - **Automatic Pre-Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - - Wait for the result of the hook command before proceeding to the Outline. - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. -- If no hooks are registered or `.specify/extensions.yml` does not exist, skip silently - -## Outline - -1. **Setup**: Run `{SCRIPT}` from repo root and parse FEATURE_DIR, TASKS_TEMPLATE, and AVAILABLE_DOCS list. `FEATURE_DIR` and `TASKS_TEMPLATE` must be absolute paths when provided. `AVAILABLE_DOCS` is a list of document names/relative paths available under `FEATURE_DIR` (for example `research.md` or `contracts/`). For single quotes in args like "I'm Groot", use escape syntax: e.g 'I'\''m Groot' (or double-quote if possible: "I'm Groot"). Do not write an artifact until setup succeeds. - -2. **Load inputs progressively**: Read required `plan.md` and `spec.md`, then - available `data-model.md`, `contracts/`, `research.md`, and `quickstart.md` - under FEATURE_DIR. If `/memory/constitution.md` exists, load it for project - principles and governance constraints. Use only available artifacts. - -3. **Load preset policy progressively** from the installed preset: - - Read `.specify/presets/timors-agentic-workflow/references/decomposition.md` - to derive tasks, groups, contracts, and data flows. - - Read `.specify/presets/timors-agentic-workflow/references/testable-work.md` - when assigning test expectations. - - Read `.specify/presets/timors-agentic-workflow/references/concurrency-policy.md` - when deriving the graph and order. - - Read `.specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md` - when selecting semantic model tiers, capabilities, skills, or project - review roles. - - Read `.specify/presets/timors-agentic-workflow/references/documentation-planning.md` - when planning documentation. - - Read `.specify/presets/timors-agentic-workflow/references/artifact-validation.md` - before rendering or validating the artifact pair. This is the - authoritative protocol contract. - -4. **Generate the canonical pair together**: - - Read TASKS_TEMPLATE and use it for `tasks.md`; if TASKS_TEMPLATE is empty, - use `.specify/templates/tasks-template.md`. - - Use `.specify/presets/timors-agentic-workflow/templates/execution-plan-template.md` - for `execution-plan.md`. - - Organize tasks by setup, isolated foundation, priority-ordered user - stories, and final cross-cutting work. Preserve story goals, independent - tests, checkpoints, strict checklist records, and exact file paths. - - Generate tests by default for testable behavior. When no new test task is - practical, record concrete existing-coverage evidence or a concrete - not-applicable reason as required by the templates and policy. - - Keep task descriptions and task-local `[P]` judgments exclusively in - `tasks.md`. Put group ownership, the global DAG, models, capabilities, - contracts, data flow, and execution policy exclusively in - `execution-plan.md`. - - Ask the user before selecting or omitting a project review role when its - applicability remains ambiguous after inspecting repository packets and - change triggers. - -5. **Validate before writing**: Validate the complete in-memory pair against - `.specify/presets/timors-agentic-workflow/references/artifact-validation.md`, - including exact identity, headings, tables, vocabularies, identifiers, task - coverage, graph/order agreement, file ownership, role packets, contract - joins, and identical producer and consumer shapes. Unknown fields are - invalid. Write both files only after the pair passes; do not leave one newly - generated artifact without the other. - -6. **Adopt or regenerate**: Existing upstream `tasks.md` without a conforming - `execution-plan.md`, and any malformed or unsupported pair, must be - regenerated by this command. Do not migrate, repair, normalize, or infer - missing protocol data. - -## Mandatory Post-Execution Hooks - -**You MUST complete this section before reporting completion to the user.** - -Check if `.specify/extensions.yml` exists in the project root. -- If it does not exist, or no hooks are registered under `hooks.after_tasks`, skip to the Completion Report. -- If it exists, read it and look for entries under the `hooks.after_tasks` key. -- If the YAML cannot be parsed or is invalid, skip hook checking silently and continue to the Completion Report. -- Filter out hooks where `enabled` is explicitly `false`. Treat hooks without an `enabled` field as enabled by default. -- For each remaining hook, do **not** attempt to interpret or evaluate hook `condition` expressions: - - If the hook has no `condition` field, or it is null/empty, treat the hook as executable - - If the hook defines a non-empty `condition`, skip the hook and leave condition evaluation to the HookExecutor implementation -- For each executable hook, output the following based on its `optional` flag: - - **Mandatory hook** (`optional: false`) — **You MUST emit `EXECUTE_COMMAND:` for each mandatory hook**: - ``` - ## Extension Hooks - - **Automatic Hook**: {extension} - Executing: `/{command}` - EXECUTE_COMMAND: {command} - ``` - After emitting the block above you MUST actually invoke the hook and wait for it to finish before continuing. Run it the same way you would run the command yourself in this agent/session (the invocation may differ from the literal `{command}` id shown above, e.g. a skills-mode agent runs it as `/skill:speckit-...` or `$speckit-...`). Emitting the block alone does not run the hook. - - **Optional hook** (`optional: true`): - ``` - ## Extension Hooks - - **Optional Hook**: {extension} - Command: `/{command}` - Description: {description} - - Prompt: {prompt} - To execute: `/{command}` - ``` - -## Completion Report - -Report both generated paths, total tasks, task count and independent test per -story, checkpoints, task-local parallel opportunities, execution groups and -order, concurrency decision, model-tier rationale, selected project review -roles, suggested MVP scope, and pair-validation result. Include task-local -parallel execution examples per story without treating them as group -concurrency. Confirm every task has a checkbox, sequential `TNNN`, applicable -story label, and exact path. - -Context for task generation: {ARGS} - -The artifact pair must be immediately usable by cold readers without duplicated -task descriptions or undeclared orchestration. - -## Task Generation Rules - -- Organize work by user story. Isolate shared foundation and final - cross-cutting work only where they cannot belong to one independently - testable story. -- Use `- [ ] TNNN [P?] [Story?] Description with exact path`. IDs begin at - `T001` and increase without gaps. Story labels are required only in story - phases. `[P]` means only that the individual task uses different files and - has no dependency on an incomplete task; it never declares group concurrency. -- Keep tests and the behavior they prove in the same execution group. Tests are - the default for testable behavior; otherwise record the concrete exception. -- `tasks.md` contains no execution-group IDs, global dependency graph, model or - worker assignment, group concurrency, or cross-group contracts. - -## Done When - -- [ ] `tasks.md` and `execution-plan.md` were generated together and pass the - installed artifact-validation contract. -- [ ] Extension hooks were dispatched or skipped according to Mandatory - Post-Execution Hooks. -- [ ] Completion reports task coverage, story tests, execution decomposition, - and protocol validation. +## Authority and Inputs + +Require Ready canonical `spec.md` and canonical `plan.md` with Design Acceptance +Accepted for its current Revision. Read `references/artifact-contracts.md`, +`references/task-planning.md`, `references/scheduling-policy.md`, +`references/testable-work.md`, `references/documentation-planning.md`, +`references/model-and-worker-selection.md`, and `references/review-lifecycle.md`. +Use `templates/tasks-template.md`, `templates/subplan-template.md`, and +`templates/review-report-template.md`; use reviewer packets +`reviewers/tasks-rfc-fidelity.md` and `reviewers/tasks-executability.md`. + +## Procedure + +1. Refuse change if initial local `progress.md` locks or completes the package. + Otherwise create or reconcile `tasks.md` and all indexed sub-plans together. + Do not create atomic tasks, checkboxes, a separate execution artifact, or + provider-specific runtime state. +2. Apply every closed-schema and structural check in `references/task-planning.md`: + canonical identity resolution, ordered path-only DAG, ledger projection, + predecessor-table agreement, ownership and concurrency, four-mode testing, + producer body/frontmatter one-to-one agreement, consumer joins, and handoff. + Missing, unknown, ambiguous, escaping, unmatched, or contradictory data blocks + review and authorization; do not infer or migrate it. +3. Add a final documentation packet only under + `references/documentation-planning.md` conditions. Record the required or + not-applicable component-documentation handoff with paths or substantive reason. +4. Dispatch the two independent reviewers using the shared binding, attribution, + quiescence, selective-rerun, retained-pointer, and started-review-recovery rules + in `references/review-lifecycle.md`. Append complete report rounds and preserve + history. No blocking, pending, recovery, stale, or contradictory pointer may + reach authorization. +5. Request the scalar Implementation Authorization only after both current reviews + permit it. Record human rationale and decision context in the Markdown section; + write only `pending`, `approved`, or `rejected` in frontmatter. Only `approved` + hands off to `implement`. + +Old task artifacts and old runtime state are not migrated, normalized, or inferred. +Report canonical paths, reviews, authorization, and the next permitted action. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/preset.yml b/private_dot_config/specify/presets/timors-agentic-workflow/preset.yml index a0f5d855..8c8d0c06 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/preset.yml +++ b/private_dot_config/specify/presets/timors-agentic-workflow/preset.yml @@ -1,11 +1,10 @@ schema_version: "1.0" -protocol_version: "0.1.0" preset: id: "timors-agentic-workflow" name: "Timor's Agentic Workflow" - version: "0.2.1" - description: "Grounded planning, optional human review, and validated execution artifacts for Spec Kit." + version: "0.3.0" + description: "RFC-backed feature definition, reviewed task packages, and isolated packet execution." author: "Timor Gruber" license: "MIT" @@ -17,75 +16,53 @@ provides: - type: "command" name: "speckit.specify" file: "commands/speckit.specify.md" - description: "Compose optional human review around the upstream specification workflow." - strategy: "wrap" - + description: "Create a ready or draft Feature Definition." + strategy: "replace" + replaces: "speckit.specify" + - type: "command" + name: "speckit.clarify" + file: "commands/speckit.clarify.md" + description: "Converge a Feature Definition through human dialogue." + strategy: "replace" + replaces: "speckit.clarify" - type: "command" name: "speckit.plan" file: "commands/speckit.plan.md" - description: "Compose grounded planning around the upstream plan workflow." - strategy: "wrap" - - - type: "template" - name: "plan-template" - file: "templates/plan-template.md" - description: "Compose grounding sections into the upstream implementation plan." - strategy: "wrap" - + description: "Ground, review, and accept the normative RFC." + strategy: "replace" + replaces: "speckit.plan" - type: "command" name: "speckit.tasks" file: "commands/speckit.tasks.md" - description: "Generate protocol-valid tasks and execution decomposition." + description: "Create and review an immutable execution package." strategy: "replace" replaces: "speckit.tasks" - - - type: "template" - name: "tasks-template" - file: "templates/tasks-template.md" - description: "Provide the protocol task template." - strategy: "replace" - replaces: "tasks-template" - - - type: "command" - name: "speckit.analyze" - file: "commands/speckit.analyze.md" - description: "Analyze protocol artifacts without modifying them." - strategy: "replace" - replaces: "speckit.analyze" - - type: "command" name: "speckit.implement" file: "commands/speckit.implement.md" - description: "Execute only protocol-valid execution plans." + description: "Bind, isolate, integrate, and verify approved packets." strategy: "replace" replaces: "speckit.implement" - - type: "template" - name: "execution-plan-template" - file: "templates/execution-plan-template.md" - description: "Provide the execution-plan protocol template." + name: "spec-template" + file: "templates/spec-template.md" + description: "Feature Definition template." strategy: "replace" - + replaces: "spec-template" - type: "template" - name: "analysis-template" - file: "templates/analysis-template.md" - description: "Provide the analysis report template." - strategy: "replace" - - - type: "template" - name: "review-report-template" - file: "templates/review-report-template.md" - description: "Provide the project review report template." + name: "plan-template" + file: "templates/plan-template.md" + description: "Normative RFC template." strategy: "replace" - + replaces: "plan-template" - type: "template" - name: "progress-template" - file: "templates/progress-template.md" - description: "Provide the execution progress template." + name: "tasks-template" + file: "templates/tasks-template.md" + description: "Task-package index template." strategy: "replace" + replaces: "tasks-template" tags: - "workflow" - "planning" - - "validation" - "spec-kit" diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/analysis-and-approval.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/analysis-and-approval.md deleted file mode 100644 index b5e6b62b..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/analysis-and-approval.md +++ /dev/null @@ -1,335 +0,0 @@ -# Coordinated Analysis And Approval Protocol - -## Authority And Coordinator Boundary - -`/speckit.analyze` is a narrow coordinator. It owns compatibility and shared -structural preflight, role selection, dispatch, report-schema validation, -cumulative report materialization, deterministic source-preserving -aggregation, conflict exposure, verdict computation, and recording explicit -human decisions. Semantic conclusions belong only to selected reviewers in -fresh read-only contexts. The coordinator MUST NOT perform semantic review, -repair reviewer output, add a broad fallback pass, or review in its own context. - -Planning artifacts and packets are read-only during analysis. Intended writes -are `specs//reviews/.md` and `specs//analysis.md`. - -## Preflight Order - -Before extension hooks, prerequisite scripts, dispatch, or writes, complete the -mandatory shared package-integrity gate from `protocol-compatibility.md`. After -the upstream before-hook and prerequisite script seams, but before dispatch or -report writes, read and execute the complete deterministic protocol in -`.specify/presets/timors-agentic-workflow/references/artifact-validation.md`. -That file is the sole source of structural task, execution-plan, and selected -packet invariants. Do not duplicate, infer, normalize, or repair those rules. -Any violation blocks semantic dispatch. - -## Roles And Packets - -The mandatory core roles are: - -| Role ID | Model Tier | Change Triggers | -|---------|------------|-----------------| -| `artifact-fidelity` | Mid-tier | `baseline,tasks,decomposition-design,documentation,all` | -| `decomposition-design` | Most capable | `baseline,tasks,decomposition-design,reviewer-config,all` | -| `plan-clarity` | Mid-tier | `baseline,tasks,decomposition-design,documentation,reviewer-config,all` | - -Every core or selected project packet uses the foundation packet schema: - -```markdown -# Reviewer Role: - -- **Role ID**: -- **Model Tier**: Cheapest | Mid-tier | Most capable -- **Change Triggers**: - -## Scope -## Required Inputs -## Exclusions -## Review Checks -## Output Contract -``` - -The closed trigger vocabulary is `baseline`, `tasks`, -`decomposition-design`, `documentation`, `reviewer-config`, and `all`. -Project packets live at `.specify/reviewers/.md`, cannot replace a -core packet, cannot request edits, and may require inputs only within the -project and feature directory. Their tier must match `execution-plan.md`. -Missing or malformed core or selected project packets block. - -Core role questions, inputs, checks, exclusions, and role-specific output are -normative in the installed packets. Artifact fidelity owns baseline -traceability and `Requirement Coverage`; decomposition design owns technical -execution feasibility and `Execution Plan Validation`; plan clarity owns -cold-reader communication and emits only the common report. - -## Reviewer Binding And Real Dispatch - -The coordinator requires native `subagent-dispatch`. Each reviewer binding -must establish its planned tier, a concrete model selected through the native -runtime mechanism, read access to every required input, fresh-context -isolation, invokability, and attributable structured-result support. - -Resolve each role independently. Project-local eligible bindings take -precedence over global bindings. Within that scope select, in order: - -1. an explicit role-to-candidate preference supplied to `/speckit.analyze`; -2. one uniquely advertised preferred/default eligible reviewer at the tier; -3. the only eligible reviewer at the tier; -4. explicit human choice among equivalent eligible reviewers. - -Use runtime metadata and configuration to verify tier source, concrete model -binding, input access, fresh-context support, and attribution support without -invocation. Never guess provider preference or silently change tier. A missing -binding or unresolved choice blocks. - -There is no probe, canary, calibration task, or sacrificial call. The first -invocation is the real assigned review. Retry only when runtime evidence proves -no invocation started. A started or ambiguous invocation with no attributable -result becomes `Recovery required` and cannot be automatically redispatched. -Concrete provider/model, candidate, and dispatch IDs remain transient. - -## Cumulative Role Reports - -Each selected role owns one tracked cumulative report at -`specs//reviews/.md`. Reruns append rounds and never rewrite -earlier rounds. Identity and round records are exactly: - -```markdown -# Review: - -- **Role ID**: -- **Model Tier**: -- **Latest Round**: RNN -- **Latest Verdict**: Passed | Passed with concerns | Blocking -- **Reviewed At**: - -## Scope - -## Rounds - -### RNN - -- **Analysis Run**: ARNN -- **Trigger**: initial | baseline | tasks | decomposition-design | documentation | reviewer-config | all | explicit | -- **Inputs**: -- **Planned Tier Verified**: Yes -- **Fresh Context Verified**: Yes -- **Attributable Result Verified**: Yes -- **Verdict**: Passed | Passed with concerns | Blocking - -| ID | Category | Severity | Location | Summary | Recommendation | Resolution | -|----|----------|----------|----------|---------|----------------|------------| - -#### Prior Finding Dispositions - -| Prior Finding ID | Disposition | Current Finding ID | Notes | -|------------------|-------------|--------------------|-------| -``` - -All three verification attestations are exactly `Yes` in a valid round and are -written only after the transient evidence is observed. Missing evidence blocks -the round. Every round is a complete current snapshot, not a delta. Its Findings -table contains only current open findings; use `None` when there are none. - -Finding IDs originate as `-RNN-FNNN`, remain stable when retained, and -are never reused. Severity is exactly `CRITICAL`, `HIGH`, `MEDIUM`, or `LOW`; -current finding Resolution is `Open`. Prior Finding Dispositions accounts for -every finding in the preceding round with exactly `Retained`, `Resolved`, or -`Superseded`. A retained row references the same ID, a resolved row references -`None`, and a superseded row references every replacement ID. New findings -need no disposition row. - -Artifact-fidelity rounds add: - -```text -| Requirement | Covered | Task IDs | Notes | -``` - -Decomposition-design rounds add: - -```text -| Check | Status | Evidence / Notes | -``` - -The role-specific output is additive and exhaustive. Omission of a required -table or presentation of another core role's table as the role's semantic -conclusion is invalid. Artifact-fidelity coverage values are `Yes`, `Partial`, -or `No`; decomposition validation values are `Passed`, `Concern`, or -`Blocking`. - -A current `CRITICAL` or `HIGH` finding makes the role verdict `Blocking`. -Only current `MEDIUM` or `LOW` findings make it `Passed with concerns`. No -current findings makes it `Passed`. - -## Change Declarations And Rerun Selection - -The first run uses declaration `initial` and dispatches all three core roles -and every selected project role. Every later run requires an explicit human -declaration. Version-control inspection may suggest but cannot narrow it. -Unknown or uncertain scope becomes `all`; multiple classes use the union. A -human may broaden but not narrow the required union. - -- `baseline`: behavioral or architectural changes to the specification, plan, - design artifacts, quickstart, or constitution; rerun all core roles. -- `tasks`: non-documentation task identity, scope, story mapping, path, test - intent, or checklist text; rerun all core roles. -- `decomposition-design`: groups, dependencies, concurrency, ownership, - contracts, data flow, models, skills, capabilities, acceptance criteria, or - verification; rerun all core roles. -- `documentation`: documentation-impact text or documentation-only task changes - that do not alter behavior, architecture, execution records, dependencies, - ownership, contracts, acceptance criteria, or verification; rerun - artifact fidelity and plan clarity. -- `reviewer-config`: selected roles, packet content, packet tier, or required - inputs; rerun decomposition design, plan clarity, and every added or changed - project role. -- `all`: rerun every core and currently selected project role. - -Documentation-only task changes declare `documentation`, not `tasks`. A -documentation change that also changes an execution-group record declares -`decomposition-design` too. For every declaration, add every currently selected -project role whose packet declares that class or `all`. - -A newly selected role always receives an initial round. A removed role is -excluded from the next aggregate but its historical report is preserved. A -changed packet or tier requires a round under its current contract. A selected -role without a valid current-contract round blocks. Core packet changes require -a protocol release and rerun the changed core role plus the roles selected by -the feature declaration. - -## Runs, Resume, And Recovery - -Analysis run IDs are monotonic feature-local `ARNN`. Before dispatch, write the -aggregate with `Aggregate Verdict: Incomplete` and `Run Status: Incomplete`, -the explicit declaration, selected roles, retained rounds, required reruns, and -the existing Approval Record unchanged. A newer run cannot begin while an -incomplete run exists. - -Resume the same run. Retain valid successful rounds and dispatch only unfinished -or invalid roles not marked `Recovery required`. If inputs change during the -run, the human expands its declaration and every newly affected retained role -is invalidated for this run. Failed, malformed, or interrupted work remains -Incomplete. - -When an invocation may have started but has no attributable result, durably set -that role row to `Recovery required`; do not store its concrete dispatch ID. -Only an explicit human choice may clear it: recover the original invocation, -confirm from runtime evidence that it never started, or accept abandonment risk -and authorize redispatch of the real review. - -A run is Complete only when every currently selected role has exactly one valid -applicable round and the aggregate references exactly those rounds. - -## Aggregate Schema - -`analysis.md` has exactly these required sections and canonical records: - -```markdown -## Review Summary - -- **Aggregate Verdict**: Incomplete | Passed | Passed with concerns | Blocking -- **Analysis Run**: ARNN -- **Run Status**: Incomplete | Complete -- **Change Declaration**: initial | baseline | tasks | decomposition-design | documentation | reviewer-config | all | -- **Selected Roles**: -- **Analyzed At**: - -## Role Verdicts - -| Role ID | Report | Applicable Round | Verdict | Run Status | -|---------|--------|------------------|---------|------------| - -## Findings - -| Aggregate ID | Source Finding IDs | Category | Severity | Location | Summary | Recommendation | Resolution | -|--------------|--------------------|----------|----------|----------|---------|----------------|------------| - -## Reviewer Conflicts - -| ID | Source Finding IDs | Conflict | Required Resolution | Status | -|----|--------------------|----------|---------------------|--------| - -## Requirement Coverage - -| Source Role / Round | Requirement | Covered | Task IDs | Notes | -|---------------------|-------------|---------|----------|-------| - -## Execution Plan Validation - -| Source Role / Round | Check | Status | Evidence / Notes | -|---------------------|-------|--------|------------------| - -## Explicit Deviations - -| ID | Aggregate / Conflict ID | Source Finding IDs | Decision | Status | Rationale | -|----|-------------------------|--------------------|----------|--------|-----------| - -## Approval Record - -- **Decision**: Pending | Approved | Changes requested | Approved with deviations -- **Recorded By**: Human -- **Recorded At**: -- **Rationale**: -``` - -`Aggregate Verdict` is `Incomplete` exactly when Run Status is `Incomplete`. -Completed runs use only `Passed`, `Passed with concerns`, or `Blocking`. Role -Run Status is exactly `Rerun`, `Retained`, `Pending`, `Failed`, or -`Recovery required`. Pending, Failed, and Recovery-required rows use -`Applicable Round: None` and the matching sentinel as Verdict. Complete runs -contain only Rerun or Retained rows with a concrete applicable `RNN` and final -role verdict. - -## Deterministic Aggregation And Conflicts - -The Findings and Reviewer Conflicts tables contain only current records. -Aggregate IDs are monotonic non-reused `AGG-FNNN`; conflict IDs are monotonic -non-reused `CON-FNNN`. Preserve an ID only while the exact source-ID set -represents the same defect or conflict; retire it when resolved or regrouped. - -Deduplicate only findings that identify the same artifact location, defect, and -required correction. Preserve every source finding ID and use the highest -source severity. Any disagreement about severity, diagnosis, or correction is -not deduplicated; create a conflict. Do not resolve semantic disagreements. - -Finding and conflict status is `Open` or `Accepted deviation`. Project the -latter only while a matching active accepted deviation exists. Any open -conflict is blocking. Aggregate severity remains `CRITICAL`, `HIGH`, `MEDIUM`, -or `LOW`. Coverage is `Yes`, `Partial`, or `No`; validation is `Passed`, -`Concern`, or `Blocking`. - -Compute the verdict: - -- `Incomplete` while the run is incomplete; -- `Blocking` when any selected role is Blocking or any conflict is unresolved; -- `Passed with concerns` when none block and at least one role has concerns; -- `Passed` only when every selected role Passed and no conflict is unresolved. - -## Deviations And Human Approval - -Deviation IDs are monotonic non-reused `DEV-FNNN`. Each row points to one -current aggregate finding or conflict and its exact current source-ID set. -Decision is exactly `Accepted` or `Rejected`; Status is exactly `Active`, -`Resolved`, or `Superseded`. Decisions and rationale are human-owned. The -coordinator may only set deterministic lifecycle status: resolved sources make -a deviation Resolved; regrouping or a changed source set makes it Superseded -and requires a new human-owned active deviation. - -`Approval Record / Decision` is the sole authorization field and is exactly -`Pending`, `Approved`, `Changes requested`, or `Approved with deviations`. -Preserve the record across reruns, including incomplete runs. Do not store -hashes or fingerprints and do not automatically revoke or reset approval. - -| Aggregate State | Decision That Authorizes Implementation | -|-----------------|-----------------------------------------| -| Incomplete analysis run | None | -| `Passed` | `Approved` | -| `Passed with concerns` and no blocking finding/conflict | `Approved`, or `Approved with deviations` when at least one active accepted deviation exists | -| `Blocking` with every current blocking finding/conflict covered by an active accepted deviation | `Approved with deviations` | -| `Blocking` with any uncovered blocking finding/conflict | None | - -`Pending` and `Changes requested` never authorize. `Approved with deviations` -requires at least one active accepted deviation. Plain `Approved` never -authorizes Blocking. Incomplete state, uncovered blockers, and uncovered -conflicts never authorize implementation. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md new file mode 100644 index 00000000..d00fe0b0 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-contracts.md @@ -0,0 +1,31 @@ +# Artifact Authorities and Consumer Gates + +| Artifact | Authority | Required consumer state | +|---|---|---| +| `spec.md` | Feature Definition | `status: Ready` before `plan` | +| `plan.md` | Sole normative RFC | current Revision has human Design Acceptance `Accepted` before `tasks` | +| `tasks.md` and indexed `subplans/` | immutable execution package | both current reviews permit and `authorization: approved` before `implement` | +| role reports | cumulative review evidence | pointer resolves to an attributable applicable non-blocking complete round | +| ignored `progress.md` | coordinator-owned runtime evidence | exact durable evidence before resume, integration, or completion | + +The canonical feature directory is the command-resolved directory containing the +canonical `tasks.md`; its `spec.md` and `plan.md` have canonical locations there. +Consumers read concrete fields and invariants needed for their own phase and fail +closed on missing, partial, contradictory, or malformed state. The installed +project copy is runtime policy; commands do not consult the global distribution +source or alter installed files. + +Material Feature Definition writes are forbidden after the initial progress lock +or completion. Before an otherwise permitted material definition write, mark a +current Accepted or Rejected Design Acceptance Stale while preserving decision +provenance; Pending remains Pending. Return authorization to `pending` and make +existing RFC and task review pointers pending with no applicable round. Before a +material accepted RFC write, return authorization to `pending`, apply the same +acceptance transition, and make task review pointers pending. Consumers never +repair a partially written transition by inference. + +No tracked planning artifact carries concrete provider identity, model ID, +credentials, workspace path, runtime locator, dispatch identity, or a field for +runtime compatibility negotiation. Runtime evidence belongs only in ignored +progress. Old artifacts are not converted by a consumer; see the operator +procedure in `README.md`. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-validation.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-validation.md deleted file mode 100644 index 2f3828c9..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/artifact-validation.md +++ /dev/null @@ -1,291 +0,0 @@ -# Deterministic Artifact Validation Protocol - -## Authority And Scope - -This is the single authoritative installed source for execution-artifact -validation in protocol `0.1.0`. `speckit.analyze` and `speckit.implement` MUST -read this file from -`.specify/presets/timors-agentic-workflow/references/artifact-validation.md`. -They MUST fail closed on every violation and MUST NOT repair, normalize, infer, -or accept unknown protocol fields. Regenerate invalid execution artifacts with -`/speckit.tasks`. - -Validation checks required artifacts, headings, tables, canonical columns, -fields, identifiers, controlled vocabulary, and cross-artifact mappings. - -## Artifact And Identity Gate - -1. `execution-plan.md` is required. -2. Its first heading is exactly `# Execution Plan: `, where `` - is nonempty and identifies the planned feature. -3. It contains exactly one protocol line, exactly - `**Preset Protocol Version**: 0.1.0`. -4. A missing, duplicate, malformed, or unsupported protocol version is invalid. -5. `spec.md`, `plan.md`, and `tasks.md` are required Planning Inputs. Every row - marked `Yes` in Planning Inputs names a present, readable artifact at its - project-relative Path. Optional inputs may be marked `No` only when they are - not required for this feature. - -## Required Master Sections - -The execution plan contains each of these `##` headings exactly once: - -1. `## Summary` -2. `## Planning Inputs` -3. `## Execution Groups` -4. `## Dependency Graph` -5. `## Concurrency Policy` -6. `## Execution Order` -7. `## File Ownership` -8. `## Build/Cache Seeding` -9. `## Cross-Group Data Flow` -10. `## Execution Risks` -11. `## Project Review Roles` -12. `## Execution Group Details` -13. `## Post-Execution` - -## Canonical Master Tables - -Each listed section contains exactly one table with the exact canonical header -below. Header spelling, order, and column count are normative; unknown columns -are invalid in protocol `0.1.0`. - -### Planning Inputs - -```text -| Artifact | Path | Required | -``` - -`Artifact` and `Path` are nonempty. `Required` is exactly `Yes` or `No`. - -### Execution Groups - -```text -| ID | Group | Covers | Depends On / Sequenced After | Model | Description | -``` - -`ID` is an `EGNN` identifier. `Group`, `Covers`, `Model`, and `Description` are -nonempty. `Model` is exactly one of `Cheapest`, `Mid-tier`, or `Most capable`. -`Covers` is an explicit comma-separated list of canonical task IDs; it contains -no ranges, phase references, wildcards, or implicit task groups. - -### File Ownership - -```text -| Group | Primary Files | -``` - -`Group` is an existing `EGNN`. `Primary Files` is a nonempty, comma-separated -projection of that group's detail `Primary Files` field. Each project-relative -path appears in exactly one group across the master table. - -### Build/Cache Seeding - -```text -| Relative Path | Applies To | Purpose | Notes | -``` - -All cells are nonempty project-relative or declared execution values. Use one -row per seeded build or cache location. - -### Cross-Group Data Flow - -```text -| Flow ID | Data | Source Group | Producer Contract | Transport | Destination Group | Consumer Contract | -``` - -`Flow ID` is a `DFNN` identifier. `Data`, `Transport`, source, destination, and -contract cells are nonempty. - -### Execution Risks - -```text -| Risk | Impact | Mitigation / Acceptance | -``` - -All cells are nonempty. - -### Project Review Roles - -```text -| Role ID | Packet Path | Model Tier | Applicability Rationale | -``` - -Use `None` as the sole table-body value only when no project review role -applies. Otherwise, every cell is nonempty and follows the role-packet rules. - -## Identifiers And Task Coverage - -- A task ID is exactly `TNNN`: `T` followed by three decimal digits, beginning - with `T001` and increasing sequentially without gaps in `tasks.md` execution - order. -- An execution-group ID is exactly `EGNN`: `EG` followed by two decimal digits. -- A data-flow ID is exactly `DFNN`: `DF` followed by two decimal digits. -- A contract ID is exactly `CTNN`: `CT` followed by two decimal digits. Every - defined contract ID is unique across the execution plan. -- Every task ID is owned by exactly one Execution Groups `Covers` cell. -- Every `Covers` list is explicit comma-separated task IDs only. `T001-T003`, - `Phase 1`, `all setup tasks`, and equivalent shorthand are invalid. - -## Dependency, Graph, And Order Agreement - -Each Execution Groups `Depends On / Sequenced After` cell is exactly `None` or -a comma-separated sequence of these canonical predecessor records: - -```text -EGNN (logical dependency) -EGNN (policy-only sequencing) -``` - -The group must not name itself. The canonical predecessor records in Execution -Groups and Execution Order must agree exactly on predecessor ID and type. - -Dependency Graph contains one strict Mermaid block using `flowchart LR`: - -- every group is declared once with a quoted node label, as `EGNN["EGNN"]`; -- every predecessor is one edge from predecessor to successor; -- every edge is plain `EGNN --> EGNN`, with exactly one edge per predecessor - relation; -- styles, subgraphs, nonstandard edge forms, and edge labels are invalid. - -Predecessor type is recorded only in Execution Groups and Execution Order; it -is not encoded on Mermaid edges. The Mermaid graph contains every group and -relation recorded in Execution Groups and is acyclic. - -Execution Order is an ordered sequence in exactly this shape: - -```text -- **Sequential group N**: EGNN - - **After**: None - -- **Parallel group N**: EGNN, EGNN - - **After**: EGNN (logical dependency), EGNN (policy-only sequencing) -``` - -`N` is the group number. Every `EGNN` appears exactly once in one sequential or -parallel group. Each group is immediately followed by its `After` line. `After` -is exactly `None` or the comma-separated canonical predecessor records above, -and exactly projects the predecessor records for the listed execution groups. -The resulting order is topological for every Mermaid edge; cycles, missing -groups, duplicate groups, unrecorded edges, and order disagreements are invalid. - -## Execution Group Detail Fields - -`## Execution Group Details` contains one `### EGNN: ` section for -master row. Each detail contains these `####` headings exactly once, in this -order: - -1. `#### Objective` -2. `#### Required Skills` -3. `#### Required Capabilities` -4. `#### Execution Model` -5. `#### Prerequisites` -6. `#### Context` -7. `#### Primary Files` -8. `#### Integration Contracts` -9. `#### Design Decisions` -10. `#### Test Expectation` -11. `#### Acceptance Criteria` -12. `#### Verification` - -Within an execution group detail, only `Prerequisites`, `Integration Contracts`, -and `Design Decisions` may be exactly `None`. `Test Expectation` is never bare -`None`; it may use the exact Not applicable form below. Objective, Required -Skills, Required Capabilities, Execution Model, Context, Primary Files, -Acceptance Criteria, and Verification must be substantive and nonempty. - -- `Required Skills` is a nonempty bullet list. Every bullet is one exact skill - identifier, with no prose, alias, or explanatory suffix. -- `Required Capabilities` is a nonempty bullet list whose items are exactly - `read`, `edit`, `shell`, `network`, or `subagent-dispatch`. Every group - includes `read`; a group that changes files includes `edit`. -- The master Execution Groups `Model` field owns the tier and is exactly - `Cheapest`, `Mid-tier`, or `Most capable`. Detail `Execution Model` contains - exactly these two nonempty bold lines, in order: - - ```text - **Model Tier**: - **Rationale**: - ``` - - `` exactly matches that group's master `Model` value. -- `Primary Files` is a nonempty comma-separated list of project-relative paths - and exactly matches that group's File Ownership projection. -- `Test Expectation` is exactly one allowed form: `Tests required`, - `Existing coverage: `, or `Not applicable: `. - The evidence and reason placeholders are substantive and nonempty. - -## Review Role Packets - -Selected core and project reviewer packets use this schema: - -```markdown -# Reviewer Role: - -- **Role ID**: -- **Model Tier**: Cheapest | Mid-tier | Most capable -- **Change Triggers**: - -## Scope -## Required Inputs -## Exclusions -## Review Checks -## Output Contract -``` - -For every selected Project Review Roles row: - -- `Role ID` matches lowercase kebab case: `^[a-z0-9]+(?:-[a-z0-9]+)*$`. -- `Packet Path` is exactly `.specify/reviewers/.md` for that role ID. -- The selected packet's Role ID and Model Tier match the execution-plan row. -- The selected packet contains every required schema field and section above. -- `Change Triggers` is a comma-separated subset of exactly `baseline`, - `tasks`, `decomposition-design`, `documentation`, `reviewer-config`, and - `all`. - -`None` is allowed in Project Review Roles only when no role applies; it is not a -placeholder for a missing or malformed role packet. - -## Integration Contract Tables - -When a group has integration contracts, `#### Integration Contracts` contains -the following canonical records. The record labels may render as -`**Produces**`, `**Consumes**`, and `**Interface Wiring**`. Unknown columns are -invalid. - -**Produces** - -```text -| Contract ID | Flow IDs | Shape / Artifact | Consumers | -``` - -**Consumes** - -```text -| Contract ID | Flow IDs | Source | Expected Shape / Artifact | -``` - -**Interface Wiring** - -```text -| Contract ID | Interface / Boundary | Owner | Wiring | -``` - -`Interface Wiring` may be exactly `None` when no wiring applies. All Contract -IDs and Flow IDs use the canonical forms above. Flow IDs are explicit -comma-separated `DFNN` values; no ranges or shorthand are allowed. - -For every Cross-Group Data Flow row: - -1. Its Flow ID appears exactly once in the source group's Produces table and - exactly once in the destination group's Consumes table. -2. The source and destination group ownership match the master flow row. -3. The source Produces Contract ID matches `Producer Contract`; the destination - Consumes Contract ID matches `Consumer Contract`. -4. The destination group appears in the source Produces `Consumers` cell. -5. The Produces `Shape / Artifact` and Consumes `Expected Shape / Artifact` - strings are identical. -6. `Data` and `Transport` in the master flow row are present and nonempty. - -Duplicate flow membership, mismatched ownership, contract IDs, consumers, or -shape strings are invalid. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/checkpoint-integration.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/checkpoint-integration.md deleted file mode 100644 index d08dad80..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/checkpoint-integration.md +++ /dev/null @@ -1,50 +0,0 @@ -# Checkpoint Integration - -## Integration State - -Record the review branch, execution base, local integration branch, and `refs/agent-checkpoints/` before implementation. Resume only when the branch descends from the execution base and the progress, workspaces, Completed Artifacts, and checkpoint evidence agree. - -Checkpoint commits are local execution plumbing. They follow the project's signing policy and MUST be signed. If signing or signature verification fails, stop; do not create or accept an unsigned substitute. Never push a checkpoint. - -## Integrate A Group - -Only a group in `ready for integration/checkpoint` may enter integration: - -1. inspect the attributable Result and workspace state against planned ownership; -2. integrate only the group's expected files into the local integration branch; -3. verify produced files and shapes against every `DFNN` and producer `CTNN` contract; -4. run the exact post-integration verification; -5. create and verify a signed checkpoint; -6. move `refs/agent-checkpoints/` to the retained checkpoint; -7. persist Test Evidence, Completed Artifacts, Checkpoints, Execution Audit, and verification evidence; -8. update covered task checkboxes; then mark the group `done`. - -Do not satisfy integration tooling by committing, deleting, or moving unrelated dirty files. A conflict, ownership mismatch, contract mismatch, regression, verification failure, or checkpoint failure blocks the group while preserving diagnostic state. Independent groups may continue only when the validated policy permits it. - -Dependent groups start from the retained checkpoint that contains all prerequisite Completed Artifacts. A dirty result is never a completed prerequisite. - -## Checkpoint States - -- `pending`: no accepted signed checkpoint yet. -- `retained`: signed checkpoint and local ref are available for execution or recovery. -- `released`: execution state was explicitly accepted or abandoned and retention is no longer required. -- `missing`: progress requires a checkpoint but its commit/ref/signature evidence is unavailable; recovery blocks execution. - -## Final Verification And Review State - -After every group is `done`: - -1. run full required verification at integration-branch tip; -2. create and verify the final signed checkpoint; -3. retain the tip at `refs/agent-checkpoints/`; -4. record `..` in Execution Context and Final Verification; -5. prepare the review surface with mixed-reset semantics to the execution base, leaving the aggregate implementation as a dirty diff; -6. record the aggregate branch, base, dirty paths, verification, checkpoint ref, and range. - -Switch to the original review branch only when it is still at the execution base and doing so is safe. Otherwise leave the aggregate dirty diff where prepared and report its branch and base. Keep the local checkpoint ref until the user explicitly accepts or abandons the feature. Do not push it. - -## Abandonment And Removal - -An explicit abandonment returns the execution line to the recorded base while retaining enough evidence to account for branches, worktrees, checkpoints, artifacts, and dirty files. Ask for a disposition; never automatically reset, delete, clean, or remove them. - -Preset removal during active execution is unsupported. Planned-but-unstarted removal uses reverted planning or inert history. In-flight work must finish pinned, pause with retained state, or be explicitly abandoned to base. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/clarification.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/clarification.md new file mode 100644 index 00000000..230ef401 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/clarification.md @@ -0,0 +1,21 @@ +# Intent Convergence + +This phase uses only saved Feature Definition content and current human dialogue. +It proportionally challenges consequential assumptions, distinguishes underlying +need from a proposed solution, and explores relevant actors, boundaries, +constraints, failures, and adjacent effects. It stops when further inquiry cannot +materially change intent, scope, requirements, evidence, constraints, or decision +context. It does not inspect repository facts or choose implementation design. + +Each response-requiring assistant turn asks exactly one direct highest-impact +question. Explanation or alternatives may precede it but cannot contain a second +question. When a material choice has viable answers, present two or three genuine +alternatives with concrete tradeoffs and a reasoned recommendation; do not use +straw choices, silently choose, or ask an already answered question. + +After every answer, immediately persist and reconcile every affected section, +remove contradictions and resolved questions, record consequential decision +context, apply the invalidation transition in `references/artifact-contracts.md`, +and rescan the complete Ready predicate. A pause or declined decision remains a +material open question and Draft. A lock or completed package refuses a material +write rather than leaving changed content authorized by an older gate. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/concurrency-policy.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/concurrency-policy.md deleted file mode 100644 index 217bec84..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/concurrency-policy.md +++ /dev/null @@ -1,69 +0,0 @@ -# Execution Concurrency Policy - -## Decision Procedure - -Record exactly one decision: `Linear DAG` or `Parallel allowed`. Logical -independence is not sufficient for parallel execution. Groups may share a -parallel execution-order record only when all of these are verified: - -- no predecessor relation exists between them; -- Primary Files do not overlap; -- isolated execution workspaces are available; and -- generated output, build state, and caches are safe for concurrent access. - -When the plan allows parallel groups but the active runtime cannot verify -isolation or output/cache safety, the runtime may serialize dispatch. That -operational fallback does not change the recorded graph or invent a policy-only -edge. - -## Mandatory Linear DAG Cases - -Use a Linear DAG for these ecosystems unless project documentation or the user -provides a concrete, recorded safe exception: - -- Rust with Cargo; -- C or C++ build systems; -- Swift with Xcode or SwiftPM; -- JVM work when safe independent output/cache behavior is absent; -- .NET work when safe independent output/cache behavior is absent; or -- a concrete project-specific build, output, cache, workspace, or integration - constraint that requires serialization. - -Do not linearize other work conservatively without evidence. When Parallel -allowed is safe, represent its real fork and join rather than flattening it. - -## Canonical Relations - -Every predecessor record is exactly `EGNN (logical dependency)` or -`EGNN (policy-only sequencing)`. Logical dependencies carry required outputs or -ordering inherent in the work. Policy-only sequencing records serialization -required solely by the concurrency policy. Use policy-only edges for each -successive group in a Linear DAG when no logical edge already provides the -required sequence. - -The Mermaid graph uses `flowchart LR`, one `EGNN["EGNN"]` declaration per -group, and one plain `EGNN --> EGNN` edge per predecessor. It contains no edge -labels, styles, or subgraphs. It is an exact, acyclic projection of all master -predecessor records. - -Execution Order lists each group exactly once in a Sequential or Parallel group -record. Its immediately following `After` line exactly projects the canonical -predecessors for every group in that record. Groups sharing a Parallel record -must have the same projected predecessor set and cannot depend on each other. -Use only these record shapes: - -```text -- **Sequential group N**: EGNN - - **After**: None - -- **Parallel group N**: EGNN, EGNN - - **After**: EGNN (logical dependency), EGNN (policy-only sequencing) -``` - -## Build And Cache Evidence - -Record each relevant ignored in-repository build or cache path with its affected -groups, purpose, and seeding or safety notes. Seeding prepares isolated -workspaces; it never makes an unsafe graph parallel. A project with no cache to -seed still records a substantive disposition permitted by the canonical table -rather than omitting the required section. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/decomposition.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/decomposition.md deleted file mode 100644 index 0d76524f..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/decomposition.md +++ /dev/null @@ -1,80 +0,0 @@ -# Execution Decomposition Policy - -## Artifact Ownership - -Generate `tasks.md` and `execution-plan.md` as one validated pair. - -- `tasks.md` exclusively owns task descriptions and checks: phase headings, - story goals, independent tests, checkpoints, sequential `TNNN` records, - story labels, exact paths, checkboxes, and task-local `[P]` markers. -- `execution-plan.md` exclusively owns execution groups, the global dependency - graph and order, model tiers, group capabilities and skills, file ownership, - build/cache seeding, data flows, integration contracts, execution risks, and - project review roles. - -Do not duplicate task descriptions in the execution plan. Do not put group IDs, -a global DAG, worker strategy, model selection, or contracts in `tasks.md`. -`[P]` says only that one task can run alongside another because it touches -different files and has no dependency on incomplete work. It does not imply -that their execution groups may run concurrently. - -## Story-First Hybrid Decomposition - -Start with one independently testable phase and execution group per user story. -Move work out of a story only at a concrete seam: - -- isolate shared foundation that blocks multiple stories; -- isolate necessarily cross-cutting work after the stories it spans; -- split conflicting file ownership so each path has one group owner; -- split at an explicit producer/consumer contract or interface boundary; -- split when materially different required skills or capabilities apply; or -- split when each side has its own observable acceptance and verification. - -Keep tests and the behavior they prove in the same group. Every task belongs to -exactly one group, and every group is delegated as one independently executable -unit with a semantic model tier. Documentation follows the separate policy in -`documentation-planning.md`. - -## Group Records - -Use sequential `EGNN` identifiers. `Covers` lists every owned task explicitly as -comma-separated `TNNN` values; ranges, phases, wildcards, and prose aliases are -invalid. Each group has nonempty Objective, Required Skills, Required -Capabilities, Execution Model rationale, Context, Primary Files, Acceptance -Criteria, and Verification. Only Prerequisites, Integration Contracts, and -Design Decisions may be `None`. - -Required Skills is a nonempty bullet list of exact available skill IDs. Required -Capabilities is a bullet-list subset of `read`, `edit`, `shell`, `network`, and -`subagent-dispatch`. Every group requires `read`; every modifying group also -requires `edit`. Capabilities describe execution needs and do not provision a -runtime worker. - -Primary Files uses project-relative paths and exactly projects to File -Ownership. Every path has one owner. Acceptance Criteria and Verification are -behavioral bullets, never task checkboxes. - -## Cross-Group Contracts And Flows - -Create one `DFNN` master row per cross-group data path. Give each contract a -globally unique `CTNN`. The source group records the flow once in Produces and -the destination group records it once in Consumes. Project these fields exactly: - -- source and destination group ownership; -- Producer Contract and Consumer Contract IDs; -- destination group in Produces Consumers; -- explicit comma-separated Flow IDs; and -- byte-for-byte identical Produces `Shape / Artifact` and Consumes - `Expected Shape / Artifact` strings. - -Use only the canonical Produces, Consumes, and Interface Wiring tables from the -artifact-validation contract. Interface Wiring may be `None` when no wiring -applies. A group with no integration contract uses `None` for the entire field. - -## Adoption - -An existing upstream `tasks.md` is not adopted unless a conforming -`execution-plan.md` forms a valid pair with it. A missing, malformed, or -unsupported execution plan, or any invalid pair, requires rerunning -`/speckit.tasks`. There is no migration, repair, normalization, or inferred -protocol data. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/documentation-planning.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/documentation-planning.md index 5b44af49..4494f987 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/documentation-planning.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/documentation-planning.md @@ -1,43 +1,23 @@ -# Documentation Planning Policy - -## Trigger - -Plan a dedicated documentation execution group when implementation changes -domain terminology or rules, architecture or component boundaries, or an -end-to-end business or operational process. Also create one when `plan.md`'s -Documentation Impact names substantive documentation work that cannot remain -with one story. - -Keep a small, story-specific documentation change in that story's group when it -shares the same ownership and verification seam. Do not create documentation -tasks merely to restate code or preserve planning conversation. - -## Placement And Ownership - -Place a dedicated documentation group after the implementation groups whose -integrated behavior it documents. Give it logical predecessors for concrete -implementation facts it consumes. It owns exact documentation paths and has -its own applicable documentation skill IDs, test expectation, behavioral -acceptance criteria, and verification. - -Document only current, reader-relevant behavior. Include context that affects -the required outcome, a plausible implementation choice, an interface, -verification, or a concrete risk. Omit conversation residue, rejected -alternatives already settled elsewhere, and unrelated non-goals. State a -negative constraint only when naming the plausible competing behavior or risk -that makes the constraint relevant. - -## Documentation Data Flow - -When a documentation group depends on implementation results, record explicit -flows and contracts for the shapes or artifacts it consumes. Do not use a vague -"implementation complete" flow. Name the interface, behavior, schema, or -verified artifact that becomes documentation input, and keep producer and -consumer shape strings identical. - -## Post-Execution - -Post-Execution states how integrated behavior and documentation are checked for -agreement. Include an applicable project documentation reviewer from -`.specify/reviewers/` when its triggers match; ask the user if applicability is -ambiguous. +# Documentation Planning and Final Review + +When accepted design changes documented domain concepts, architecture, or +business/operational processes and relevant project documentation exists, task +planning creates a final most-capable documentation packet. It states exact paths, +stale sections, proportional scope, and documentation skills. Skip it only when no +conceptual documentation exists, no documented concept or flow changes, or only +component-level implementation detail may drift. + +Component documentation is deferred. Execution Handoff records `required` with +relevant paths when existing component documentation describes a modified +component, interface, or behavior; otherwise it records `not-applicable` with a +substantive reason. At completion, the coordinator checks both the handoff and +current repository documentation. A not-applicable handoff contradicted by current +documentation is a planning defect, not a skip. + +After final code exists, bind the independent read-only most-capable +`reviewers/component-docs.md` role. Its result gates completion but creates no +human approval gate. If it finds incomplete work within accepted requirements, +design, task scope, and acceptance, coordinator or bounded delegate may repair it, +append a policy-compliant corrective commit, and rerun the review. New scope, +undefined behavior, contract change, or acceptance exception returns to Feature +Definition, RFC, or task planning ownership. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/execution-lifecycle.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/execution-lifecycle.md index f96aaf3b..958fc3c6 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/execution-lifecycle.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/execution-lifecycle.md @@ -1,101 +1,59 @@ -# Delegated Implementation Lifecycle - -## Authority And Boundaries - -This reference governs `speckit.implement` for preset protocol `0.1.0`. The command executes the validated decomposition; it does not redesign it. Never invent, remove, regroup, or change planned tasks, dependencies, concurrency policy, file ownership, model tier, skills, capabilities, contracts, tests, acceptance criteria, or verification. A needed change is a planning correction and blocks affected execution. - -The command owns coordination directly. It MUST NOT invoke `executing-plans`, provision workers through the preset, or let workers dispatch other workers. Installed preset references are the only preset policy source. - -## Command-Wide Preflight - -Before extension hooks, `{SCRIPT}`, progress creation or update, workspace or branch mutation, project-file mutation, or dispatch: - -1. Complete the shared package-integrity gate in `protocol-compatibility.md`. -2. Resolve the current feature and its installed feature directory read-only, without a setup or prerequisite script. Require readable `spec.md`, `plan.md`, `tasks.md`, and `execution-plan.md`, plus every protocol artifact selected by those files. -3. Read `.specify/presets/timors-agentic-workflow/references/artifact-validation.md` and rerun that complete deterministic validation against the current `tasks.md`, `execution-plan.md`, and every selected reviewer packet. This is the same installed validation source used by `speckit.analyze`; do not copy, abbreviate, or define a second invariant set here. -4. Require the latest analysis report for this exact artifact set to have final status `Complete`. Match the exact selected core and project roles, each role's `Role Verdict`, and every applicable report round. Reject missing, extra, stale, duplicated, or mismatched role/report identities. -5. Verify structural consistency among the final aggregate verdict, findings, conflict dispositions, deviations, and artifact identities. Require an authorizing Approval Record for the exact validated artifact set and report round. - -Fail closed on any missing, malformed, stale, contradictory, or unauthorized evidence. This gate checks structural consumption safety only: it does not repeat semantic review, reassess findings, or revoke an approval because the implementer disagrees with it. Regeneration or correction remains owned by the command that owns the invalid artifact. - -Only after the entire gate passes may before-hooks and `{SCRIPT}` run. If either changes a gated artifact, rerun the entire gate before any prohibited mutation or dispatch. - -## Progress Initialization And Resume - -After the preflight and upstream checklist gate, initialize or resume the ignored `specs//progress.md` from `templates/progress-template.md`. Ensure the project ignore mechanism excludes this file before writing it. Preserve every exact section, column, and controlled state in the template, and update it after each attributable transition. - -Use this resume matrix before dispatch: - -| Observed state | Required action | -|---|---| -| Tasks checked, group `done`, and valid checkpoint plus Completed Artifacts evidence | Trust the completed coverage. | -| Valid result/checkpoint/artifacts with an interrupted progress transition | Finish only the interrupted progress and task-checkbox transition. | -| Task checked but completion evidence missing or invalid | Block; reconstruct evidence or explicitly return it to pending. | -| Task unchecked but group is `done` or has a completion checkpoint | Block the contradiction; do not infer which side is correct. | -| Local progress, workspace, branch, checkpoint, or attributable dispatch/result state is missing | Block and recover explicitly; never redispatch automatically. | - -## Ready-Group Gate - -Bind a group only when it is ready. Future groups need not bind workers or workspaces early. Immediately before a ready group mutates a workspace, edits, or dispatches, verify all of the following for that group: - -- every logical and policy prerequisite and required checkpoint is present; -- every prerequisite output is recorded and matches its producer contract; -- the planned tier resolves to a concrete worker and concrete model; -- every exact required skill is available and invokable at its recorded path; -- required capabilities map to effective permissions, with no undeclared capability; -- worker discovery, selection, binding, and dispatch are available; -- the absolute target workspace and its evidence are recorded; -- dirty-state policy is satisfied; -- concurrent worker capacity and output/build/cache safety are proven; -- the planned Test Expectation and verification commands remain enforceable. - -A parallel set starts only after every member passes. If any member fails, none of that set may mutate or dispatch. `Parallel allowed` groups may be serialized when capacity or safety requires it, but the fallback and reason must be recorded. Never parallelize a `Linear DAG` or remove a dependency. - -## Canonical Worker Packet - -Construct each worker packet without interpretation by joining: - -1. the canonical Execution Groups row; -2. that group's complete Execution Group Details section; -3. the current canonical `tasks.md` lines for exactly its `Covers` task IDs; and -4. prerequisite outputs from Completed Artifacts, joined through the matching `DFNN` flow and `CTNN` producer/consumer contracts. - -Pass absolute workspace targeting and require the Result evidence below. Do not add or change policy, ownership, implementation direction, contracts, tests, acceptance criteria, or verification. A producer result that does not match its planned contract blocks source-group completion and requires planning correction; it is not normalized in progress or in a consumer packet. - -## Provider-Neutral Handshake Evidence - -Record these stages for each binding: - -1. **Discovery**: candidate identity, scope, purpose, planned tier source, concrete model source, exact skill paths, capability-to-permission mapping, and invokability. -2. **Selection**: search project-local candidates before global candidates, then apply explicit configuration. Select only a unique preferred candidate, the sole eligible candidate, or a human decision; ambiguity blocks. -3. **Binding**: selected identity, concrete model, exact skills, and effective permissions. -4. **Workspace**: absolute target and evidence that invocation will execute there. -5. **Dispatch**: attributable invocation ID and start evidence. -6. **Result**: the same attributable identity, terminal status, changed files, tests, verification, and blockers. - -Do not run suitability probes, calibration tasks, canaries, or model-confirmation calls. Feature-local planned tier classification is the only tier evidence; do not infer tier from general reputation or observed output. Reuse only recorded metadata or an explicit operator decision. - -Retry is allowed only with proof that no invocation started. If start is ambiguous or an invocation may have started, retain all state and mark `Recovery required`; never retry automatically. - -## Tests, Results, And Completion - -Tests remain with the implementation worker that owns the group. Enforce the exact planned Test Expectation. Missing evidence is pushed back once to the same binding and workspace; if it remains missing, block rather than substituting a different worker or explanation. - -A successful worker result moves the group to `ready for integration/checkpoint`, not `done`. Complete a group only in this order: - -1. integrate its exact result; -2. run required post-integration verification; -3. create the signed checkpoint; -4. persist checkpoint, handshake, test, verification, and Completed Artifacts evidence; -5. update every covered canonical task checkbox; -6. mark the group `done`. - -Completed Artifacts records the group's `Flow ID`, `Contract ID`, `Files / Outputs`, `Result Summary`, and `Checkpoint`. Use `None` for Flow ID and Contract ID only when output does not cross a group boundary. Dependent groups consume only these checkpointed records. - -## Adoption, Removal, And Unsupported Transitions - -Adoption requires upstream `tasks.md` plus a protocol-valid execution plan. Reject projects with only upstream tasks, no execution plan, or mixed protocol/non-protocol execution state. - -For planned work removed before execution, either revert the planning artifacts or retain inert history; do not execute it. For in-flight removal, finish the pinned work, pause it with all state retained, or explicitly abandon it back to the recorded execution base. Never automatically delete branches, worktrees, checkpoint refs, dirty files, progress, or artifacts. - -Removing this preset while execution is active is unsupported. Pause or complete/abandon execution first. +# Execution Lifecycle and Runtime Progress + +Before progress creation, require Ready `spec.md`; current Revision Accepted +`plan.md`; a closed task package with both current non-blocking reviews; +`authorization: approved`; and fully clean named stable active branch. Pin branch +and starting commit. External checkout, reset, rebase, or unrelated commit blocks +instead of being reconciled automatically. Resolve the exact progress path, add it +to `.git/info/exclude` if absent, then create it from +`templates/progress-template.md`. Successful initial creation is the task-package +lock event. Never change `tasks.md` or a sub-plan after that event. + +Progress has exactly these sections: Execution Context, Packet States, Execution +Audit, Test and Verification Evidence, Runtime Consideration Evidence, Contract +Outputs, Blockers and Recovery, Final Verification. Package status is +`in-progress`, `blocked`, `complete`, or `abandoned`; packet state is exactly +`pending`, `in-progress`, `ready`, `blocked`, or `done`. It records feature +directory, active branch/start commit, protected baseline, signing policy evidence, +canonical identity and derived worktree-root-relative locator for each packet, +worktree/branch attribution, and all durable runtime transitions. + +At lock, pin the complete path set and content of every tracked file beneath the +canonical feature directory. The baseline includes every feature-local artifact, +including spec, RFC, package, sub-plans, reports, grounding, research, and tracked +additions. Progress is excluded. At dispatch, result acceptance, after rebase, and +integration, compare paths, content, tracked additions/deletions/replacements, and +file types to this exact baseline. Any difference rejects dispatch or candidate; +never accept a changed protected path. + +Before dispatch validate canonical identity is a tracked regular file under feature +directory and derive the locator from worktree root plus feature location. It must +remain beneath the directory and resolve to the same selected file. Send identity +and locator, not the packet body. Permit repository browsing but no authority +expansion. For each consumed contract, resolve the exact producer/name, revalidate +its body definition and final-commit evidence, and send only that evidence plus +attributable producer/name reference. The worker reads definition in the producer +sub-plan; neither progress nor prompt reconstructs it. + +Workers may make packet-scoped commits only in their worktree/branch. The +coordinator verifies complete diff, declared ownership, tests, acceptance, output +evidence, result attribution, clean returned branch, policy, and baseline before +marking `ready` or integrating. Contract Outputs has exactly one entry per globally +unique produced name with producer identity, final integrated commit, required +returned evidence, validation outcome, and consumers derived from all consumes. +Missing, extra, duplicate, or contradictory entry blocks dependent readiness. + +An unstarted invocation may retry once only with evidence of no start and no +workspace mutation. Missing result/test evidence gets one request to the same +session. A known-started runtime failure or ambiguous attempt is never automatically +redispatched. Resume or replacement binding first preserves and reconciles branch, +worktree, mutations, invocation, verification, ownership, locator, and baseline +evidence; a same-session resume continues only from clean attributable evidence. +Changed authority or ambiguous mutation requires abandonment and replanning. Never +infer progress from commits. + +Abandonment before completion sets status `abandoned`, archives progress to a unique +ignored timestamped path, retains branches/worktrees unless explicit disposition +allows cleanup, returns authorization to pending, and permits fresh reviewed tasks +against current state. Active-branch commits remain untouched. Completion freezes +the package permanently; later work uses a new feature package. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/feature-definition.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/feature-definition.md new file mode 100644 index 00000000..61f821d6 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/feature-definition.md @@ -0,0 +1,25 @@ +# Feature Definition Contract + +`spec.md` supports bounded product, defect, refactor, infrastructure, +documentation, tooling, and similar work. Its closed core is metadata containing +only status `Draft` or `Ready`; Intent; Scope; semantically titled Requirements +with inline acceptance evidence; Constraints and Dependencies; Consequential +Decision Context; and Material Open Questions. Add actor, journey, entity, +terminology, failure, risk, accessibility, localization, compatibility, or +operational material only when relevant. Downstream artifacts cite section paths +and semantic titles, never serial requirement identifiers. + +The complete Ready predicate is: intent and underlying need are coherent; scope +and boundaries are explicit; requirements and evidence state the desired outcome; +applicable constraints, dependencies, actors, failures, and adjacent effects are +addressed; and no unanswered decision could materially change any of those fields. +Repository feasibility and technical consequences are deliberately outside this +predicate. + +`specify` does not interact: it marks Ready only when supplied intent positively +establishes every criterion without defaults, inference, or unanswered questions. +Otherwise it records material open questions and marks Draft. `clarify` may begin +from either status. When a rescan of Ready discovers a material question, it writes +that question and changes to Draft before dialogue. After every human answer it +reconciles the entire artifact and uses the same predicate. See +`references/review-lifecycle.md` for ordered invalidation and lock handling. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/human-review.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/human-review.md deleted file mode 100644 index 75fa1974..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/human-review.md +++ /dev/null @@ -1,73 +0,0 @@ -# Optional Human Review Protocol - -## Authority And Scope - -This shared protocol governs the optional human-review offer at the natural -completion of `/speckit.specify` and `/speckit.plan`, after that phase has -generated and validated its artifacts. It supplies interaction mechanics only. -Each command supplies its own phase-specific, conceptual review guidance. - -Do not apply this protocol to `/speckit.analyze`, task generation, or -implementation. It does not replace their existing review, approval, or -execution contracts. - -Human review is optional for each phase independently. Offer a guided -walkthrough or independent review, and allow the user to decline both and -continue normal completion. There is no persisted preference, no approval -record, and no workflow gate. Do not advertise later re-entry into a completed -phase or relitigation of an earlier phase. - -## Offer And Independent Review - -After the owning command's normal artifact generation and validation complete, -briefly offer these choices without a roadmap: - -1. **Guided walkthrough** — discuss consequential concerns selected with the - command's phase-specific guidance. -2. **Independent review** — identify the phase's key artifacts for the user to - read independently, encourage that final read, then continue normal - completion reporting and handoffs. - -Independent review does not start a guided walkthrough, wait for an approval, -or change the command's existing report or handoff behavior. - -## Guided Walkthrough Mechanics - -Select only consequential decisions owned or introduced by the current phase, -using judgment, the phase guidance, and the conversation context. Do not provide -an upfront walkthrough roadmap. Inputs and settled decisions from earlier phases -are authoritative baselines for the current phase. Cite them briefly as -constraints, rationale, or traceability context when useful, but they must not -become review units requiring renewed confirmation. - -For qualifying current-phase units, review material requirements and boundaries, -model-selected decisions, meaningful assumptions, tradeoffs or rejected -alternatives, unresolved ambiguity, compatibility or operational consequences, -and risks when they are consequential. Do not limit the walkthrough to -unresolved decisions. - -Use supporting artifacts such as `data-model.md`, `research.md`, or contracts -as evidence sources, not mandatory review stops. Skip mechanical projections or -repetition unless they expose a consequential decision. Do not force a literal -section-by-section or file-by-file walkthrough. - -Each review unit covers one coherent concern and stays cognitively small. Group -only tightly coupled details that require shared reasoning, never merely -because they seem noncontroversial. If the user could accept one item and -reject another, split them. Avoid dense turns and fatigue. For genuine -alternatives, lead with a recommendation and its reasoning; do not invent -options where no meaningful choice exists. - -Pause after each review unit. Once the user settles it, immediately update every -affected artifact owned by the current phase, restore consistency and required -validation, briefly confirm the outcome, then select the next unit using -judgment and conversation context. During an active walkthrough, allow normal -conversational redirection, repetition, or stopping without ceremonial -navigation. - -## Walkthrough Completion - -When the walkthrough is complete, say so. Briefly summarize the resulting -decisions and changes, point only to the key phase artifacts for independent -self-review, encourage that final read, and continue the command's normal -completion reporting and handoffs. Do not imply that self-review is mandatory. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md index f69b522b..524193c0 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/model-and-worker-selection.md @@ -1,65 +1,25 @@ -# Model And Worker Selection Policy - -## Semantic Model Tiers - -Assign every execution group exactly one provider-neutral tier: `Cheapest`, -`Mid-tier`, or `Most capable`. Select conservatively from the work's reasoning -needs, ambiguity, integration risk, and required verification: - -- `Cheapest` for bounded, mechanical work with explicit local patterns and - straightforward verification; -- `Mid-tier` for normal implementation requiring repository reasoning, - contract adherence, or coordinated tests; and -- `Most capable` for unusually ambiguous, high-risk, cross-boundary, or complex - work where a weaker tier materially threatens correctness. - -Do not choose a tier from provider names, availability guesses, or cost alone. -The Execution Groups table owns the tier. Each detail's Execution Model repeats -that tier in its `Model Tier` field and records substantive rationale in its -`Rationale` field. - -## Runtime Boundary - -Every execution group is a delegated unit, but this preset declares data only. -It does not create workers, bind provider models, dispatch agents, or configure -runtime execution. Worker selection and binding remain owned by the active -runtime at implementation time. Required Capabilities declare needs; they do -not grant capabilities. - -## Skills And Capabilities - -List the exact IDs of all skills needed to execute the group. The list is never -empty and contains no descriptions or aliases. List only required capabilities -from `read`, `edit`, `shell`, `network`, and `subagent-dispatch`. Include `read` -for every group and `edit` for every group that modifies files. Do not request -network or subagent dispatch without a concrete need. - -## Project Review Roles - -Inspect `.specify/reviewers/` for applicable project reviewer packets. Use -`None` only when no role applies. If change triggers or project context leave -applicability ambiguous, ask the user rather than silently selecting or -omitting a role. - -Every selected role has a lowercase-kebab-case ID and path exactly -`.specify/reviewers/.md`. Its plan row records the packet's semantic -Model Tier and a concrete applicability rationale. The packet must match this -schema: - -```markdown -# Reviewer Role: - -- **Role ID**: -- **Model Tier**: Cheapest | Mid-tier | Most capable -- **Change Triggers**: - -## Scope -## Required Inputs -## Exclusions -## Review Checks -## Output Contract -``` - -Change Triggers contains only `baseline`, `tasks`, `decomposition-design`, -`documentation`, `reviewer-config`, or `all`. The packet's Role ID and Model -Tier must exactly match its execution-plan row. +# Binding, Runtime Conditions, and Result Attribution + +Tracked reviewers and implementation packets name only a provider-neutral tier and +exact skills. Eligibility requires those exact values plus native discoverability, +invokability, correct workspace targeting, and attributable results. Prefer a +project-local candidate. Select a unique preferred candidate, sole eligible +candidate, or an explicit human choice. Abstract capabilities and permission +breadth are excluded. Zero or ambiguous candidates are collected blockers. Do not +provision a worker or perform a suitability probe; first invocation is real work. + +Runtime Considerations are anticipated network, local tool, nested-dispatch, +cache, or similar conditions. They are planning context only: neither access grants +nor worker requirements or eligibility gates. During real work, attempt a +requirement-preserving in-scope alternative if a condition is unavailable. Return +the condition, whether/how attempted, concrete permission or environment failure, +alternative, and residual verification limitation. Block only when no alternative +can meet packet requirements or acceptance; never retroactively disqualify binding. + +The coordinator’s result envelope has only: status; changed paths; commits; tests +and verification performed; produced contract-output evidence; runtime-condition +outcomes; and blockers. It cannot add or alter scope, outputs, acceptance, +verification, handoff, or semantic contract content. On conflict the selected +sub-plan prevails. An applicable empty runtime-outcome set is explicit. Reviewer +results additionally prove role, reviewed paths, round, verdict, read-only scope, +and attribution; a mutation of reviewed workspace rejects the result. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/planning-grounding.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/planning-grounding.md index f2ae8174..82aaedbf 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/planning-grounding.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/planning-grounding.md @@ -1,74 +1,17 @@ -# Planning Grounding Policy - -## Purpose - -This policy composes repository grounding into `/speckit.plan` while preserving -the active lower-priority planning workflow. It does not replace its research, -data-model, contracts, quickstart, technical-context, or constitution work. - -## Plan Section Contract - -The composed `plan-template` contains these headings exactly once: - -1. `## Current-State Grounding` -2. `## Existing Interfaces And Integration Seams` -3. `## Planning Constraints` -4. `## Documentation Impact` - -Complete each section with observed, project-specific evidence. Use -project-relative paths in documentation and absolute paths only for filesystem -operations, matching the upstream command contract. - -### Current-State Grounding - -Record facts discovered in the repository before proposing work: existing -behavior, relevant modules, tests, configuration, generated artifacts, and -known compatibility boundaries. State the evidence for each fact. Do not place -architecture choices or their rationale in this section. - -### Existing Interfaces And Integration Seams - -Record interfaces that must remain compatible, including public APIs, CLI -inputs/outputs, configuration formats, persistence boundaries, generated files, -callers, consumers, and extension points. Point to `data-model.md` and -`contracts/` for interface and data detail rather than duplicating it here. - -### Planning Constraints - -Record constraints already imposed by the specification, constitution, existing -interfaces, repository conventions, dependencies, platform support, and -backward compatibility. A constraint is evidence, not a design choice. - -### Documentation Impact - -List documentation to create, update, or intentionally leave unchanged. Give a -project-relative path and rationale for each entry. Do not turn this section -into a task list. - -## Artifact Ownership - -Keep artifact responsibilities separate: - -- `research.md` contains decisions, rationale, alternatives, and resolution of - clarifications. -- `data-model.md` and `contracts/` contain data and interface detail. -- `execution-plan.md` contains execution decomposition and coordination. -- `plan.md` contains the upstream implementation plan plus the four grounding - sections; it does not duplicate the other artifacts. - -## Feature Reuse - -When the current feature already has `plan.md` and does not have `tasks.md`, -rerun `/speckit.plan` to refresh the plan and its supporting design artifacts. -Do not skip planning merely because `plan.md` exists. A feature with only -`spec.md` follows the normal upstream planning path. In either case, preserve -the upstream setup script behavior and do not duplicate any of the four added -headings. - -## Command Boundaries - -The command spine stays concise. Detailed execution-plan validation is the -single policy in -`.specify/presets/timors-agentic-workflow/references/artifact-validation.md`. -Compatibility preflight policy is in -`.specify/presets/timors-agentic-workflow/references/protocol-compatibility.md`. +# Planning Grounding + +`plan` grounds repository reality before it designs. Cheap delegated exploration +may collect evidence, but the coordinator normalizes and verifies material claims. +`grounding-notes.md` is an attributed repository-evidence store: Sources, +Observations, bounded Inferences, Relevance, and Unknowns. It records no design +recommendations. `research.md` is tracked but non-normative thematic working space +for verified evidence, real alternatives, working decisions, consequences, and +open design questions. Every decision needed later is restated in `plan.md`. + +Ask one adaptive consequential technical question per human turn. Routine detail +is planner-owned. Surface repository evidence that contradicts Feature Definition +intent. Planning may directly correct only non-semantic factual metadata or an +unambiguous transcription error. Any correction affecting intent, scope, +requirements, acceptance evidence, constraints, dependencies, decision context, +or open questions changes `spec.md` to Draft, invalidates downstream gates, and +returns control to `clarify`; planning resumes only after Ready. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/protocol-compatibility.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/protocol-compatibility.md deleted file mode 100644 index 33bf6be2..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/protocol-compatibility.md +++ /dev/null @@ -1,127 +0,0 @@ -# Preset Protocol Compatibility - -## Authoritative Contract - -`preset.yml` at -`.specify/presets/timors-agentic-workflow/preset.yml` is authoritative for the -preset identity, preset and protocol versions, minimum Spec Kit requirement, -and declared command/template mappings. The current package requires Spec Kit -`>=0.12.11`; it has no upper support boundary. - -- Preset ID: `timors-agentic-workflow` -- Preset version: `0.2.1` -- Execution-plan protocol version: `0.1.0` - -## Shared Minimum-Version And Package-Integrity Gate - -Every composed or replaced command in this preset, including commands added in -later package work, MUST complete this entire gate as its first operational -action. It is atomic: any failure stops the command before an extension hook, -prerequisite script, artifact write, progress or workspace mutation, or -dispatch. Do not substitute a global, dotfiles, or package-manager path for the -installed preset path. - -1. Read and parse the installed `preset.yml`. Require schema version `1.0`, the - identity above, and the exact `0.1.0` protocol version. Require a parseable - `requires.speckit_version` constraint whose current declared minimum is - `>=0.12.11`. -2. Obtain and parse the active semantic version with `specify --version`. It - must meet the minimum and the installed manifest constraint. A later manifest - may record an explicit known incompatibility in its constraint; honor that - declared constraint only. Do not add a known-bad list, infer exclusions, or - warn, prompt, or block merely because a newer version has not been tested. -3. Require every file in the complete inventory below to exist as a readable - regular file at its installed relative path. Treat a missing, malformed, or - incoherent package as one package-level failure; do not continue into a - phase whose own inputs happen to be present. -4. Verify that `preset.yml` declares exactly the command/template mappings and - strategies in the manifest mapping table below, with each declared relative - path present in the inventory. This validates package wiring, not file - contents. -5. Validate the structural coherence rules below. They check declared fields, - headings, protocol values, and installed-preset paths only; they do not - compare full prose or immutable file contents. - -If the manifest, version, constraint, identity, inventory, or mapping is -missing, malformed, or incoherent, report the failed contract and stop. This -gate is structural only: do not compare checksums, hashes, immutable contents, -or exact file contents. - -### Complete Required Package Inventory - -| Category | Required installed relative paths | -|----------|----------------------------------| -| Root files | `LICENSE`; `README.md`; `preset.yml` | -| Commands | `commands/speckit.specify.md`; `commands/speckit.plan.md`; `commands/speckit.tasks.md`; `commands/speckit.analyze.md`; `commands/speckit.implement.md` | -| Templates | `templates/plan-template.md`; `templates/tasks-template.md`; `templates/execution-plan-template.md`; `templates/analysis-template.md`; `templates/review-report-template.md`; `templates/progress-template.md` | -| Reviewer packets | `reviewers/artifact-fidelity.md`; `reviewers/decomposition-design.md`; `reviewers/plan-clarity.md` | -| References | `references/analysis-and-approval.md`; `references/artifact-validation.md`; `references/checkpoint-integration.md`; `references/concurrency-policy.md`; `references/decomposition.md`; `references/documentation-planning.md`; `references/execution-lifecycle.md`; `references/human-review.md`; `references/model-and-worker-selection.md`; `references/planning-grounding.md`; `references/protocol-compatibility.md`; `references/testable-work.md`; `references/workspace-isolation.md` | - -### Manifest Mapping Table - -| Type | Name | File | Strategy | -|------|------|------|----------| -| command | `speckit.specify` | `commands/speckit.specify.md` | `wrap` | -| command | `speckit.plan` | `commands/speckit.plan.md` | `wrap` | -| template | `plan-template` | `templates/plan-template.md` | `wrap` | -| command | `speckit.tasks` | `commands/speckit.tasks.md` | `replace` | -| template | `tasks-template` | `templates/tasks-template.md` | `replace` | -| command | `speckit.analyze` | `commands/speckit.analyze.md` | `replace` | -| command | `speckit.implement` | `commands/speckit.implement.md` | `replace` | -| template | `execution-plan-template` | `templates/execution-plan-template.md` | `replace` | -| template | `analysis-template` | `templates/analysis-template.md` | `replace` | -| template | `review-report-template` | `templates/review-report-template.md` | `replace` | -| template | `progress-template` | `templates/progress-template.md` | `replace` | - -### Structural Coherence Rules - -- The manifest binds the five command source files to exactly - `speckit.specify`, `speckit.plan`, `speckit.tasks`, `speckit.analyze`, and - `speckit.implement`. Each source's first body phase is `## Package Integrity - Gate` and consumes this installed `references/protocol-compatibility.md` - before any command-specific body phase. -- `speckit.specify`, `speckit.plan`, and `plan-template` are the only `wrap` - mappings. The specify and plan sources retain `{CORE_TEMPLATE}` and omit local - `scripts` and `agent_scripts` metadata so native composition inherits those - fields from the active lower-priority command. The `plan-template` retains - its core composition placeholder. -- `speckit.specify` and `speckit.plan` each consume the installed shared - `references/human-review.md` only after their respective upstream artifact - generation and validation complete. The reference governs optional review - mechanics; each command owns phase-specific conceptual guidance. -- `speckit.tasks`, `speckit.analyze`, `speckit.implement`, and - `tasks-template` are `replace` mappings. The task command declares `sh`, - `ps`, and `py` setup variants. -- Analyze and implement each consume the same installed - `references/artifact-validation.md`. No command may substitute or define a - divergent artifact-validation source. -- The reviewer packets declare these exact role/tier pairs: - `artifact-fidelity` / `Mid-tier`, `decomposition-design` / `Most capable`, - and `plan-clarity` / `Mid-tier`. -- `templates/execution-plan-template.md` declares - `**Preset Protocol Version**: 0.1.0`, consistent with the manifest and this - reference. -- Every required installed-preset path named by a command spine resolves to a - required file in the complete inventory. This includes command references to - installed policy references and templates; no command may rely on an - undeclared installed-preset file. - -## Execution-Plan Protocol Gate - -`execution-plan.md` is valid only when its identity line is exactly -`# Execution Plan: ` and its protocol line is exactly -`**Preset Protocol Version**: 0.1.0`. Missing, malformed, or unsupported -versions fail closed. The only recovery is regeneration through -`/speckit.tasks`; analyze and implement do not repair, infer, downgrade, or -silently accept a different protocol. - -The deterministic protocol rules live only in -`.specify/presets/timors-agentic-workflow/references/artifact-validation.md`. -Later `speckit.analyze` and `speckit.implement` command contracts MUST consume -that installed source directly rather than copying or redefining its rules. - -## Package Boundary - -This preset defines no runtime worker, model binding, or agent-dispatch -configuration. Execution capabilities are declared only as data in validated -execution-plan artifacts. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md new file mode 100644 index 00000000..f1131568 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/review-lifecycle.md @@ -0,0 +1,35 @@ +# Independent Review Lifecycle + +Review roles are independent and read-only. Bind only a candidate with requested +tier, exact skills, native discoverability, invokability, correct workspace +targeting, and attributable results; project-local candidates are preferred. +Select a unique preferred candidate, a sole eligible candidate, or an explicit +human choice. Abstract capabilities and permission breadth are not eligibility +inputs. The first invocation is the real review assignment; there is no probe. + +Every role report is cumulative and appends a complete current-state round with +trigger, scope, reviewed paths, binding/invocation/workspace/start/result evidence, +verdict, and semantic blocking or concern findings. A targeted rerun carries +unaffected current findings into its new complete snapshot. Findings have semantic +titles, not opaque identifiers. The review pointer holds only its declared report, +round, revision when applicable, status, and verdict; detailed evidence remains in +the report. + +For an RFC review that may have started without attributable complete result, set +its pointer to unchanged report path, round `None`, revision `None`, status +`Recovery required`, verdict `Pending`. For a task review use unchanged report, +round `null`, status `recovery-required`, verdict `pending`. Do not retain an old +pointer value there. Recover with attributable same-session resume or a newly +selected binding only after confirming reviewed artifact unchanged, workspace +read-only and correctly targeted, and retained evidence reconciled. A recovered +result appends the next complete round and updates the pointer normally. Ambiguous +start, mutation, target, or result stops the producing phase: never self-review, +infer a verdict, request a downstream human gate, or abandon implementation work. + +A producing phase is quiescent only when no pending role can safely dispatch, +resume, or complete without a collected binding or recovery blocker. Then present +one interaction with all current blockers. After a response resume work; a later +quiescent state may present one later batch. Automatic redispatch after known start +is forbidden. Material artifact changes follow their owner’s invalidation and +fresh-review rules; a later invocation may resume recovery only against unchanged +current artifact. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/rfc-planning.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/rfc-planning.md new file mode 100644 index 00000000..4669306a --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/rfc-planning.md @@ -0,0 +1,40 @@ +# RFC Planning and Acceptance + +`plan.md` is the sole normative RFC. It contains verified current state and +constraints; semantically titled decisions aligned locally to Feature Definition; +architecture; applicable contracts and flows; alternatives; risks; verification; +planning handoff; and source references. Its `Revision` is `R0`, `R1`, and onward. + +Design Acceptance has exactly these fields: + +| Field | Contract | +|---|---| +| Status | `Pending`, `Accepted`, `Rejected`, or `Stale` | +| Applies To Revision | current `RNN` for Accepted/Rejected; prior decision revision when Stale; `None` when Pending | +| Recorded By | `Human` for Accepted/Rejected; prior value when Stale; `Pending` when Pending | +| Recorded At | ISO-8601 timestamp for Accepted/Rejected; prior value when Stale; `Pending` when Pending | +| Rationale | substantive context for Accepted/Rejected; prior value when Stale; `Pending` when Pending | + +Only Accepted whose Applies To Revision equals current Revision permits task +planning. A material RFC change increments Revision and, before writing, makes +Accepted or Rejected acceptance Stale; Pending stays Pending. Editorial changes +retain Revision and acceptance. Refuse a material write after the progress lock. + +The Review Record has fixed `rfc_design` and `rfc_clarity` records, each with +report path, round (`RNN` or `None`), RFC revision (`RNN` or `None`), Status +(`Pending`, `Reviewed`, `Retained`, `Recovery required`), and Verdict (`Pending`, +`Passed`, `Passed with concerns`, `Blocking`). A role is current only if Reviewed +or Retained, its round exists in its report, its revision equals current Revision, +and its verdict passes or passes with concerns. See +`references/review-lifecycle.md` for dispatch and recovery. + +First complete RFC review runs both roles. Editorial, evidence repair, or a +finding-specific repair needs no rerun only when it leaves architecture, boundary, +contract, flow, state, compatibility, migration, failure behavior, risk posture, +and cold-reader meaning unchanged. Otherwise rerun affected role scope. Before a +clearly affected write make affected roles Pending with no round/revision and +provisionally mark unaffected roles Retained. After successful material write, +advance an unaffected retained pointer to the new Revision with its old round and +verdict. Ambiguous or large accumulated impact makes potentially affected roles +Pending before a human confirms scope. No acceptance remains valid until each role +is freshly Reviewed or explicitly Retained for current Revision. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/scheduling-policy.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/scheduling-policy.md new file mode 100644 index 00000000..495c1799 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/scheduling-policy.md @@ -0,0 +1,21 @@ +# Scheduling and Integration Order + +The frontmatter predecessor DAG is the only machine-authoritative scheduling +contract. Every `after` entry blocks readiness equally regardless of its human +classification. A packet is ready only after every direct predecessor is `done`. +Do not infer readiness from Mermaid, ledger prose, table reason, consumer prose, +or an undeclared relation. + +Dispatch every eligible ready packet concurrently unless a concrete binding, +harness, machine-resource, or workspace limitation prevents it. Record the +limitation, then serialize only affected otherwise-ready packets in topological +list order without changing the approved graph. A worker finish may occur in any +order, but integration is always the approved topological packet order. A verified +later sibling remains `ready` until earlier integration completes. + +Continue independent ready work after another packet blocks. A wave is quiescent +only when no pending or blocked packet can safely dispatch, resume, verify, or +integrate without resolving collected binding, runtime, verification, or recovery +blockers. Then present one interaction containing all currently unresolved +blockers. After a response resume scheduling; only a later quiescent wave can +produce another batch. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/task-planning.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/task-planning.md new file mode 100644 index 00000000..9c8c0e70 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/task-planning.md @@ -0,0 +1,107 @@ +# Task Package Schema and Planning Rules + +`tasks.md` is immutable after execution begins. It has exactly seven human +sections: Overview, Sub-Plan Ledger, Dependency Graph, Execution Inputs and +Requirements, Review Record, Implementation Authorization, Execution Handoff. It +has no atomic task lines or checkboxes. Mermaid and the ledger are non-authoritative +human projections; frontmatter is the sole machine authority. + +Its complete closed frontmatter envelope is: + +```yaml +kind: task-package +subplans: + - path: subplans/NN-semantic-name.md + after: + - subplans/NN-predecessor.md +reviews: + rfc_fidelity: + report: reviews/tasks-rfc-fidelity.md + round: null + status: pending + verdict: pending + executability: + report: reviews/tasks-executability.md + round: null + status: pending + verdict: pending +authorization: pending +``` + +`subplans` is nonempty and topologically ordered. Each record has exactly `path` +and `after`; all nested records and the top level reject unknown keys. Every path +is the sole globally unique canonical identity, is feature-directory-relative, +stays beneath that directory, and resolves to exactly one tracked regular sub-plan +file. Every predecessor is a distinct identity in the package. Duplicate, missing, +escaping, ambiguous, untracked, non-regular, cyclic, or mismatched identities +block structure, review, authorization, dispatch, and resume. The ordered ledger +must match paths and exact direct-predecessor sets one-to-one, with no missing, +extra, duplicate, reordered, or mismatched rows. + +Each selected sub-plan has exactly these closed fields: + +```yaml +kind: subplan +primary_files: [project/root/relative/path] +execution: + model_tier: cheapest | mid-tier | most-capable + rationale: substantive provider-neutral string + skills: [exact-skill-id] +test: + mode: required | existing-coverage | not-applicable | no-testable-behavior + basis: substantive string +contracts: + produces: [semantic-kebab-case-name] + consumes: + - name: semantic-kebab-case-name + producer: subplans/NN-producer.md +``` + +`primary_files` and skills are nonempty; every nested record is closed. There is +no sub-plan `path`, abstract capability, runtime identity, or producer-side +consumer list. Produces names match `^[a-z0-9]+(?:-[a-z0-9]+)*$`, are globally +unique, and are strings. A consume has exactly name and producer, each resolves to +one producer identity/name pair, and the producer must be a direct predecessor. + +A packet body has exactly Objective; Baseline Context and Constraints; Scope and +Primary Files; Prerequisites and Integration; Runtime Considerations; Acceptance +and Verification; Required Outputs and Handoff. Direct Predecessors is a table +with exactly Path, Classification, Reason and exactly one row per `after` entry. +Each classification is `genuine implementation prerequisite` or `policy-only +serialization`; the latter does not loosen readiness. The empty `after` list has +no rows. Transitive Context is separate non-authoritative background. Concurrent +packets may not overlap primary files. Sequential overlap is valid only when an +ordered predecessor relation and both packet handoffs state the predecessor state. + +For every produced name, Required Outputs and Handoff has exactly one direct child: +`### Produced Contract: ` followed by that exact single-backticked name. Its body +is closed at the next level-three heading or section end and has exactly these +direct level-four headings, once and in order: `#### Description`, `#### Contract`, +`#### Transport`, `#### Invariants and Constraints`, `#### Required Output +Evidence`. Extra level-four peers block; deeper headings are allowed within one +child. Description defines meaning; Contract defines required shape; Transport +states delivery; Invariants lists all constraints or exactly `None`; Required +Output Evidence names worker evidence recorded against final integrated producer +commit. This is the sole semantic definition. Produces and these bodies agree +one-to-one; empty produces has no such headings. Consumer prose may explain use +but cannot repeat, narrow, widen, or override producer definition. + +Every consume must name its direct genuine predecessor, resolve its body exactly, +and receive final-commit evidence at dispatch. Every successor-needed output not +fully embodied and verifiable in integrated repository state requires this join. +Derive consumer coverage by scanning all consumes. Missing, duplicate, ambiguous, +misclassified, or unjoined output blocks; routing never creates an implicit edge. + +Task review pointer round is `null` or `RNN`; status is `pending`, `reviewed`, +`retained`, or `recovery-required`; verdict is `pending`, `passed`, +`passed-with-concerns`, or `blocking`; authorization is `pending`, `approved`, or +`rejected`. Authorization may be approved only when both roles are reviewed or +retained, point to existing rounds, and pass or pass with concerns. Initial review +runs both. Cosmetic or scoped implementation-detail correction needs no rerun by +default. RFC-fidelity reruns when changed scope can affect Feature Definition or +RFC scope, constraints, risks, accepted design, or producer-owned definitions. +Executability reruns when ownership, dependencies, concurrency, routing, body +agreement, producer resolution, output evidence, test mode/basis, acceptance, +verification, or handoff changes. Packet addition/removal, split/merge, boundary, +DAG, or verification-scope change reruns both. Ambiguous impact is surfaced before +review work and large accumulated revision requires human scope confirmation. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/testable-work.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/testable-work.md index 6ed38449..5014cd34 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/testable-work.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/testable-work.md @@ -1,36 +1,28 @@ -# Testable Work Policy - -## Default - -Tests are the default for behavior that can regress. Derive test tasks from user -story independent tests, interface contracts, quickstart scenarios, existing -test conventions, and the observable behavior being changed. Put tests and the -implementation they prove in the same execution group so a delegated group can -reach a verified outcome without another group's uncommitted work. - -When practical, order a test task before its implementation task and require -the test to demonstrate the missing or incorrect behavior before implementation. -Use exact project-relative test paths in `tasks.md`. - -## Exact Test Expectation - -Every execution-group detail uses exactly one of these values: - -- `Tests required` -- `Existing coverage: ` -- `Not applicable: ` - -Use `Tests required` when the group creates or changes testable behavior. Use -Existing coverage only when named current tests or a concrete verification -surface already proves the result and the group does not need a new test task. -Use Not applicable only for work with no meaningful automated test surface, -with a concrete reason tied to that work. Bare `None`, generic claims such as -"docs only", and preference-based omissions are invalid. - -## Behavioral Checks - -Story Independent Test, group Acceptance Criteria, and group Verification must -describe observable behavior or artifacts. Acceptance and Verification are -bullets, not task checkboxes. Commands alone are insufficient unless the -expected result is also stated. A build or lint command does not replace a -behavioral test when behavior changed. +# Test Modes and Evidence + +Every packet has one `test.mode` and a nonempty substantive `basis`; Acceptance +and Verification supplies exact commands/checks and expected outcomes without +changing mode. + +| Mode | Required basis | Worker evidence | +|---|---|---| +| `required` | planned test scope and exact test location, suite, or command | implement changed behavior and tests together; run and report coverage and results | +| `existing-coverage` | exact existing test files, cases, suites, or commands and the acceptance behavior they prove | run cited evidence; if it does not prove changed behavior, add/update owned tests and report the false assumption and correction | +| `not-applicable` | substantial out-of-scope infrastructure or restructuring barrier, why it is substantial, and alternative verification | perform/report alternative verification and preserve named automated-testing gap | +| `no-testable-behavior` | why no behavior is meaningfully automatable and applicable non-test verification | perform/report named non-test verification; do not supply synthetic test evidence | + +Required and existing-coverage packets reserve all test paths needed for planned +coverage or bounded correction. Existing coverage cannot cite generic suite +existence. Preference or inconvenience never justifies not-applicable. If required +or corrected existing coverage cannot produce meaningful coverage within approved +ownership and scope, block the packet and dependents; frozen mode and basis do not +change. Continuing requires explicit abandonment, task replanning, applicable +review, and renewed authorization. Not-applicable means a known gap, not absence of +testable behavior; only no-testable-behavior makes that assertion. + +Progress records each packet’s planned mode/basis, commands/checks, outcomes, and +added or changed tests. It retains a not-applicable barrier and alternative through +completion and records incorrect existing-coverage assumption. Final Verification +and user completion reporting must agree with this evidence and runtime outcomes. +An approved testing gap is reportable and adds no approval gate, but insufficient +resulting verification blocks completion. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/references/workspace-isolation.md b/private_dot_config/specify/presets/timors-agentic-workflow/references/workspace-isolation.md index 27169e0b..b9bd9410 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/references/workspace-isolation.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/references/workspace-isolation.md @@ -1,41 +1,49 @@ -# Workspace Isolation - -## Purpose - -Isolation prevents concurrent groups from sharing a dirty working tree. It does not prove worker capacity, build-output safety, cache correctness, or dependency independence; those are separate ready-group gates in `execution-lifecycle.md`. - -## Workspace Selection - -- Resolve and record an absolute workspace path for every bound group. -- Parallel groups use separate worktrees. A dependent worktree starts only from an integration-branch checkpoint containing every prerequisite output. -- Sequential groups may use the integration workspace unless the plan requires isolation. -- A `Linear DAG` is always serialized. `Parallel allowed` may be serialized when capacity or output/cache safety cannot be proven; record the fallback and reason in progress. -- Never create a dependent workspace from prerequisite output that exists only as dirty files. - -## Dirty-State Preflight - -Immediately before a ready group creates, enters, or mutates a workspace, inspect tracked modifications and untracked non-ignored files in the coordinator and target workspace. Record the exact evidence in Execution Audit. - -If unexpected state exists, stop before workspace mutation, edits, or dispatch. Never stash, delete, commit, copy, ignore, reset, or otherwise relocate dirty state without explicit authorization. If authorization permits proceeding, record the paths, scope, decision, and resulting target status. Unrelated state carried into a worktree still blocks dispatch. - -`progress.md` is a coordinator artifact and must remain ignored. Do not copy progress, plans, reviews, or other coordinator artifacts into worker worktrees. - -## Concurrent Capacity And Output Safety - -Before any member of a parallel set starts, prove that all members can run concurrently and that each has: - -- a distinct absolute worktree; -- an available attributable worker binding; -- nonoverlapping planned file ownership; -- safe generated-output and build directories; and -- a project-documented or verified cache strategy, or an explicit no-reuse result. - -Start none until all pass. Filesystem isolation alone is not evidence that path-sensitive caches or shared generated outputs are safe. - -Prefer project-documented shared caches. Seed only ignored build/cache artifacts when project instructions or targeted verification proves portability between absolute paths. Never seed source, plans, reviews, progress, or checkpoints. If reuse is unsafe or unnecessary, record that it is skipped. If required reuse cannot be proven, block. - -## Workspace Result Retention - -Verify dispatch actually targeted the recorded absolute path. After result return, inspect changed and untracked files against group ownership and the attributable Result. Keep a worktree when dispatch start/result is ambiguous, integration or verification fails, a checkpoint is missing, or recovery is required. - -Never automatically remove a branch or worktree. Release a workspace only after its exact result is integrated and checkpointed, or after explicit abandonment records the disposition of every dirty file and checkpoint. +# Worktree Isolation, Signing Policy, and Integration + +Every packet has a dedicated branch and worktree. Workers may modify and commit +only selected packet-owned implementation or documentation paths outside protected +feature directory. Only the coordinator advances the explicit active target. +Workers never alter protected planning files, rewrite prerequisite history, merge +unrelated work, push, stash, reset, revert, rewrite, or auto-commit unrelated +files. Retain blocked or unresolved branches/worktrees and evidence. + +Before dispatch, resume, result acceptance, rebase, squash, amend, corrective +commit, or integration, resolve signing policy against repository-controlled +instruction files and effective Git configuration for the target repository. +Apply repository instruction scope hierarchy: nearest scoped explicit signing +directive wins; contradictory directives at equal precedence require one human +resolution. Global agent instructions and prompt text are excluded. Without an +applicable directive, normal Git configuration precedence decides whether signing +is enabled. Signed history is evidence, never policy. + +Resolve exactly one mode: `required` when winning repository instruction requires +signatures; `enabled` when no instruction requires/prohibits and effective Git +configuration enables signing; `disabled` when a winning instruction prohibits +signing or no directive applies and configuration does not enable it. Absence of a +directive and enabled configuration is disabled without prompting. Record mode, +every applicable instruction path/content digest, effective signing values and +reported origins, active target observation commit, and human-resolution evidence. +Observation commit is provenance, not a policy-equality input. + +Before each named operation resolve again. Equality compares mode, instruction +paths/digests, effective values/origins, and human resolution, excluding only +observation commit. An unambiguous change automatically audits and repins, +including transition to disabled; reject and recreate any candidate formed under +the old policy. Prompt only for unresolved equal-precedence contradiction. A +candidate that changes repository instruction is governed by pre-integration active +target policy; after advancement resolve, audit, and repin before later work. + +Every worker/coordinator commit and operation recreating a commit applies pinned +mode. Required and enabled create and verify signatures; signing failure blocks +with no unsigned fallback. Disabled does not invoke signing. No workflow default +changes repository policy. + +Before target advancement, rebase packet branch on current active HEAD, recheck +baseline, and construct a separately inspectable squash candidate. Verify candidate +tree, required signature, ownership, and output evidence before a no-new-commit +fast-forward. Worktrunk is preferred only after a non-mutating capability check +proves it can make this candidate, apply pinned mode, and avoid early target +advancement. If not, plain Git creates and verifies the candidate independently. +Resolve only conflict-local mechanics outside the protected baseline; a semantic or +scope choice blocks. Advance active branch by exactly one policy-compliant commit +per packet, record it, then make consumers ready. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/artifact-fidelity.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/artifact-fidelity.md deleted file mode 100644 index d989a949..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/artifact-fidelity.md +++ /dev/null @@ -1,54 +0,0 @@ -# Reviewer Role: Artifact Fidelity - -- **Role ID**: artifact-fidelity -- **Model Tier**: Mid-tier -- **Change Triggers**: baseline,tasks,decomposition-design,documentation,all - -## Scope - -Determine whether the planned work faithfully and completely represents the -approved baseline. Review is read-only and produces a complete current-state -snapshot of open findings. - -## Required Inputs - -- `spec.md` -- `plan.md` -- `tasks.md` -- `execution-plan.md` -- the constitution when present -- every existing design artifact marked required in `Planning Inputs` - -## Exclusions - -Do not judge group-boundary quality, dependency or concurrency feasibility, -model or skill suitability, or packet prose except where wording contradicts -or obscures baseline traceability. Do not redesign the decomposition. - -## Review Checks - -- Trace every requirement, user story, success criterion, edge case, - constitution rule, design decision, and documentation impact to tasks and - orchestration or to an explicit justified omission. -- Detect unsupported work and duplicated work. -- Detect baseline ambiguity that permits incompatible implementations. -- Detect contradictions between the baseline and planned work. - -## Output Contract - -Emit the common identity, scope, round metadata, complete current Findings -snapshot, and Prior Finding Dispositions defined by -`templates/review-report-template.md` and -`references/analysis-and-approval.md`. Use only `CRITICAL`, `HIGH`, `MEDIUM`, -or `LOW`, keep current findings `Open`, and preserve originating IDs in the -form `-RNN-FNNN`. - -Every round MUST also include: - -#### Requirement Coverage - -| Requirement | Covered | Task IDs | Notes | -|-------------|---------|----------|-------| - -`Covered` is exactly `Yes`, `Partial`, or `No`. Do not include Execution Plan -Validation as this role's semantic conclusion. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/component-docs.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/component-docs.md new file mode 100644 index 00000000..428cbc62 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/component-docs.md @@ -0,0 +1,14 @@ +# Component Documentation Review Packet + +- **Tier**: most-capable +- **Required skills**: exact project component-documentation skill identifiers +- **Inputs**: final integrated code, relevant current documentation, Execution Handoff, progress evidence +- **Workspace**: correctly targeted read-only repository view after final code +- **Exclusions**: no mutation, no scope expansion, no authorization decision + +Independently identify existing component documentation that describes a modified +component, interface, or behavior and is stale, incomplete, or contradictory. +Return attributable reviewed paths, scope, semantic findings, and verdict. This +review occurs only after final code and gates completion without a third human +approval. An in-scope repair may be performed or delegated, committed under pinned +repository policy, then reviewed again; new scope returns to planning. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/decomposition-design.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/decomposition-design.md deleted file mode 100644 index 8d075e39..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/decomposition-design.md +++ /dev/null @@ -1,60 +0,0 @@ -# Reviewer Role: Decomposition Design - -- **Role ID**: decomposition-design -- **Model Tier**: Most capable -- **Change Triggers**: baseline,tasks,decomposition-design,reviewer-config,all - -## Scope - -Determine whether the represented work is divided and connected into a -technically sound, feasible execution strategy. Review is read-only and -produces a complete current-state snapshot of open findings. - -## Required Inputs - -- `spec.md` -- `plan.md` -- `tasks.md` -- `execution-plan.md` -- every existing design artifact marked required in `Planning Inputs` -- selected project reviewer packets when the trigger includes `reviewer-config` - -## Exclusions - -Do not re-audit baseline requirement coverage, deterministic structural -invariants owned by `artifact-validation.md`, project-packet prose style, or -cold-reader relevance except when missing information prevents feasibility -judgment. - -## Review Checks - -- Judge story and group cohesion boundaries. -- Judge dependency and sequencing semantics. -- Judge concurrency and ownership safety. -- Judge contract and data-flow compatibility. -- Judge model, skill, and capability suitability. -- Judge workspace, build, and cache strategy. -- Judge test strategy and documentation-work placement. -- Judge acceptance and verification feasibility and deterministic handoff - viability. -- For `reviewer-config`, judge selected-role applicability, tier suitability, - and required-input fit. - -## Output Contract - -Emit the common identity, scope, round metadata, complete current Findings -snapshot, and Prior Finding Dispositions defined by -`templates/review-report-template.md` and -`references/analysis-and-approval.md`. Use only `CRITICAL`, `HIGH`, `MEDIUM`, -or `LOW`, keep current findings `Open`, and preserve originating IDs in the -form `-RNN-FNNN`. - -Every round MUST also include: - -#### Execution Plan Validation - -| Check | Status | Evidence / Notes | -|-------|--------|------------------| - -`Status` is exactly `Passed`, `Concern`, or `Blocking`. Do not include -Requirement Coverage as this role's semantic conclusion. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md deleted file mode 100644 index ec4a7dd1..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/plan-clarity.md +++ /dev/null @@ -1,44 +0,0 @@ -# Reviewer Role: Plan Clarity - -- **Role ID**: plan-clarity -- **Model Tier**: Mid-tier -- **Change Triggers**: baseline,tasks,decomposition-design,documentation,reviewer-config,all - -## Scope - -Determine whether a cold reader can identify the already-chosen work, -constraints, and completion conditions without interpretation. Review is -read-only and produces a complete current-state snapshot of open findings. - -## Required Inputs - -- `tasks.md` -- `execution-plan.md` -- selected project reviewer packets when the trigger includes `reviewer-config` - -## Exclusions - -Do not judge baseline coverage, decomposition merits, technical feasibility, -model or skill suitability, or deterministic schema validity. - -## Review Checks - -- Verify joined task and group packets state settled work and constraints - precisely. -- Verify referents, paths, terminology, and completion conditions are defined - and internally consistent. -- Flag hedging, unresolved options, undefined references, wording - contradictions, and conversation residue. -- Apply cold-reader relevance: flag defensive repetition, unrelated non-goals, - and negative constraints that name no plausible competing behavior or - concrete risk. Prefer omission when an exclusion is irrelevant to execution. - -## Output Contract - -Emit only the common identity, scope, round metadata, complete current Findings -snapshot, and Prior Finding Dispositions defined by -`templates/review-report-template.md` and -`references/analysis-and-approval.md`. Use only `CRITICAL`, `HIGH`, `MEDIUM`, -or `LOW`, keep current findings `Open`, and preserve originating IDs in the -form `-RNN-FNNN`. Do not add Requirement Coverage or Execution Plan -Validation as this role's semantic conclusion. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-clarity.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-clarity.md new file mode 100644 index 00000000..5b17c06d --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-clarity.md @@ -0,0 +1,14 @@ +# RFC Clarity Review Packet + +- **Tier**: mid-tier +- **Required skills**: exact project cold-reader and technical-writing skill identifiers +- **Inputs**: current `spec.md`, `plan.md`, prior role report +- **Workspace**: correctly targeted read-only feature/repository view +- **Exclusions**: no mutation, no design substitution, no human acceptance decision + +Independently determine whether a cold reader can follow current-state evidence, +Feature Definition alignment, decision rationale, interfaces, constraints, risks, +verification, and planning handoff without conflicting or missing authority. +Identify ambiguity, unexplained consequence, or unreviewable handoff as semantic +findings. Return an attributable complete current-state round with reviewed paths, +trigger, scope, blocking/concern findings, and verdict. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-design.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-design.md new file mode 100644 index 00000000..d334a84a --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/rfc-design.md @@ -0,0 +1,15 @@ +# RFC Design Review Packet + +- **Tier**: most-capable +- **Required skills**: exact project RFC and architecture-review skill identifiers +- **Inputs**: current `spec.md`, `plan.md`, relevant grounding/research, prior role report +- **Workspace**: correctly targeted read-only feature/repository view +- **Exclusions**: no mutation, no binding choice, no human acceptance decision + +Independently assess whether the current RFC is technically coherent and complete: +verified current state, architecture, boundaries, contracts, flows, state, +failure behavior, compatibility/migration, risks, verification, and Feature +Definition alignment. Check that durable decisions are in `plan.md`, not only +supporting workspaces. Return an attributable complete current-state round with +reviewed paths, trigger, scope, semantic blocking/concern findings, and verdict. +A passing verdict never implies Design Acceptance. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-executability.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-executability.md new file mode 100644 index 00000000..92c0e0e6 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-executability.md @@ -0,0 +1,18 @@ +# Task Executability Review Packet + +- **Tier**: most-capable +- **Required skills**: exact project decomposition, testing, and execution-review skill identifiers +- **Inputs**: accepted RFC, `tasks.md`, indexed sub-plans, prior report +- **Workspace**: correctly targeted read-only feature/repository view +- **Exclusions**: no mutation, no worker provisioning, no authorization decision + +Independently check all requirements in `references/task-planning.md` and +`references/testable-work.md`: closed fields; canonical identity and ledger; +DAG/direct-predecessor agreement and classifications; ownership/concurrent +overlap; producer heading shape/body agreement; exact consume resolution and +genuine direct-predecessor join; tier/skills; four-mode basis; acceptance, +verification, output evidence, and handoff. Missing, duplicate, extra, escaping, +ambiguous, mismatched, unjoined, or misclassified required data is blocking. So are +unsupported mode, inadequate basis, existing coverage that does not prove +acceptance, or not-applicable without substantial out-of-scope barrier. Return an +attributable complete current-state round with semantic findings and verdict. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-rfc-fidelity.md b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-rfc-fidelity.md new file mode 100644 index 00000000..9f2fe509 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/reviewers/tasks-rfc-fidelity.md @@ -0,0 +1,14 @@ +# Task RFC-Fidelity Review Packet + +- **Tier**: mid-tier +- **Required skills**: exact project RFC-reading and task-review skill identifiers +- **Inputs**: Ready `spec.md`, current accepted `plan.md`, `tasks.md`, indexed sub-plans, prior report +- **Workspace**: correctly targeted read-only feature/repository view +- **Exclusions**: no mutation, no implementation dispatch, no authorization decision + +Independently assess execution package scope, constraints, risks, accepted design, +and producer-owned output definitions against Feature Definition and accepted RFC. +Check that no packet introduces undefined behavior, scope, contract, or acceptance +exception. Return an attributable complete current-state round with reviewed paths, +trigger, scope, semantic blocking/concern findings, and verdict. Unapproved +deviation is blocking. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/analysis-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/analysis-template.md deleted file mode 100644 index 3783fc9b..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/templates/analysis-template.md +++ /dev/null @@ -1,55 +0,0 @@ -# Analysis: [FEATURE] - -## Review Summary - -- **Aggregate Verdict**: Incomplete -- **Analysis Run**: ARNN -- **Run Status**: Incomplete -- **Change Declaration**: initial -- **Selected Roles**: artifact-fidelity, decomposition-design, plan-clarity -- **Analyzed At**: [ISO-8601 timestamp] - -## Role Verdicts - -| Role ID | Report | Applicable Round | Verdict | Run Status | -|---------|--------|------------------|---------|------------| -| artifact-fidelity | reviews/artifact-fidelity.md | None | Pending | Pending | -| decomposition-design | reviews/decomposition-design.md | None | Pending | Pending | -| plan-clarity | reviews/plan-clarity.md | None | Pending | Pending | - -## Findings - -| Aggregate ID | Source Finding IDs | Category | Severity | Location | Summary | Recommendation | Resolution | -|--------------|--------------------|----------|----------|----------|---------|----------------|------------| -| None | None | None | None | None | None | None | None | - -## Reviewer Conflicts - -| ID | Source Finding IDs | Conflict | Required Resolution | Status | -|----|--------------------|----------|---------------------|--------| -| None | None | None | None | None | - -## Requirement Coverage - -| Source Role / Round | Requirement | Covered | Task IDs | Notes | -|---------------------|-------------|---------|----------|-------| -| None | None | None | None | None | - -## Execution Plan Validation - -| Source Role / Round | Check | Status | Evidence / Notes | -|---------------------|-------|--------|------------------| -| None | None | None | None | - -## Explicit Deviations - -| ID | Aggregate / Conflict ID | Source Finding IDs | Decision | Status | Rationale | -|----|-------------------------|--------------------|----------|--------|-----------| -| None | None | None | None | None | None | - -## Approval Record - -- **Decision**: Pending -- **Recorded By**: Human -- **Recorded At**: Pending -- **Rationale**: Pending diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/execution-plan-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/execution-plan-template.md deleted file mode 100644 index 51f08c6f..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/templates/execution-plan-template.md +++ /dev/null @@ -1,221 +0,0 @@ -# Execution Plan: [FEATURE NAME] - -**Preset Protocol Version**: 0.1.0 - -## Summary - -[Describe the feature outcome and decomposition for a cold reader.] - -## Planning Inputs - -| Artifact | Path | Required | -|----------|------|----------| -| Specification | specs/[###-feature-name]/spec.md | Yes | -| Implementation Plan | specs/[###-feature-name]/plan.md | Yes | -| Tasks | specs/[###-feature-name]/tasks.md | Yes | - -## Execution Groups - -| ID | Group | Covers | Depends On / Sequenced After | Model | Description | -|----|-------|--------|--------------------------------|-------|-------------| -| EG01 | [Foundation group name] | T001 | None | Mid-tier | [Distinct foundation outcome] | -| EG02 | [Story group name] | T002 | EG01 (logical dependency) | Mid-tier | [Distinct story outcome] | - -## Dependency Graph - -```mermaid -flowchart LR - EG01["EG01"] - EG02["EG02"] - EG01 --> EG02 -``` - -## Concurrency Policy - -- **Decision**: Linear DAG | Parallel allowed -- **Reason**: -- **Linearization basis**: Rust/Cargo | C/C++ build system | Swift/Xcode/SwiftPM | JVM build system | .NET/MSBuild | project-specific constraint | None -- **Execution impact**: -- **Override**: - -## Execution Order - -- **Sequential group 1**: EG01 - - **After**: None - -- **Sequential group 2**: EG02 - - **After**: EG01 (logical dependency) - -## File Ownership - -| Group | Primary Files | -|-------|---------------| -| EG01 | [foundation/project-relative/path] | -| EG02 | [story/project-relative/path] | - -## Build/Cache Seeding - -| Relative Path | Applies To | Purpose | Notes | -|---------------|------------|---------|-------| -| [project-relative/cache-path] | EG01, EG02 | [Build or test cache purpose] | [Seeding requirement or safe no-seed disposition] | - -## Cross-Group Data Flow - -| Flow ID | Data | Source Group | Producer Contract | Transport | Destination Group | Consumer Contract | -|---------|------|--------------|-------------------|-----------|-------------------|-------------------| -| DF01 | [Transferred data] | EG01 | CT01 | [File, value, interface, or other transport] | EG02 | CT02 | - -## Execution Risks - -| Risk | Impact | Mitigation / Acceptance | -|------|--------|-------------------------| -| [Concrete execution risk] | [Potential effect] | [Mitigation or explicit acceptance] | - -## Project Review Roles - -| Role ID | Packet Path | Model Tier | Applicability Rationale | -|---------|-------------|------------|-------------------------| -| None | | | | - -## Execution Group Details - -### EG01: [Foundation group name] - -#### Objective - -[One independently verifiable execution outcome.] - -#### Required Skills - -- [exact-skill-id] - -#### Required Capabilities - -- read -- edit - -#### Execution Model - -**Model Tier**: Mid-tier -**Rationale**: [Provider-neutral rationale for the semantic tier selected in Execution Groups.] - -#### Prerequisites - -None - -#### Context - -[Feature facts, constraints, and evidence needed by this group.] - -#### Primary Files - -[foundation/project-relative/path] - -#### Integration Contracts - -**Produces** - -| Contract ID | Flow IDs | Shape / Artifact | Consumers | -|-------------|----------|------------------|-----------| -| CT01 | DF01 | [Exact shape or artifact string] | EG02 | - -**Consumes** - -| Contract ID | Flow IDs | Source | Expected Shape / Artifact | -|-------------|----------|--------|---------------------------| - -**Interface Wiring** - -| Contract ID | Interface / Boundary | Owner | Wiring | -|-------------|----------------------|-------|--------| -| CT01 | [Interface or boundary] | EG01 | [Concrete wiring responsibility] | - -#### Design Decisions - -None - -#### Test Expectation - -[Tests required | Existing coverage: evidence expected | Not applicable: reason] - -#### Acceptance Criteria - -- [Observable behavior or artifact outcome] - -#### Verification - -- [Command, inspection, or scenario that proves the acceptance criterion] - -### EG02: [Story group name] - -#### Objective - -[One independently verifiable story outcome.] - -#### Required Skills - -- [exact-skill-id] - -#### Required Capabilities - -- read -- edit - -#### Execution Model - -**Model Tier**: Mid-tier -**Rationale**: [Provider-neutral rationale for the semantic tier selected in Execution Groups.] - -#### Prerequisites - -[Foundation outcome from EG01 available through CT01 and DF01.] - -#### Context - -[Story facts, constraints, and evidence needed by this group.] - -#### Primary Files - -[story/project-relative/path] - -#### Integration Contracts - -**Produces** - -| Contract ID | Flow IDs | Shape / Artifact | Consumers | -|-------------|----------|------------------|-----------| - -**Consumes** - -| Contract ID | Flow IDs | Source | Expected Shape / Artifact | -|-------------|----------|--------|---------------------------| -| CT02 | DF01 | EG01 | [Exact shape or artifact string] | - -**Interface Wiring** - -None - -#### Design Decisions - -None - -#### Test Expectation - -Tests required - -#### Acceptance Criteria - -- [Observable behavior or artifact outcome] - -#### Verification - -- [Command, inspection, or scenario that proves the acceptance criterion] - - - -## Post-Execution - -[State final integrated verification and applicable documentation review.] diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/grounding-notes-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/grounding-notes-template.md new file mode 100644 index 00000000..19b60c87 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/grounding-notes-template.md @@ -0,0 +1,18 @@ +# Grounding Notes: [Feature Name] + +## Sources + +| Source | Observed At | Scope | +|---|---|---| +| [Project-relative path or command result] | [Timestamp] | [Observed area] | + +## Observations + +### [Semantic Observation Title] + +- **Evidence**: [Direct attributable observation] +- **Bounded Inference**: [Clearly limited inference, if any] +- **Relevance**: [Why planning needs this fact] +- **Unknowns**: [What was not established] + +Do not record design recommendations here. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-template.md index cecffc7f..962a21c3 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-template.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/plan-template.md @@ -1,41 +1,58 @@ -{CORE_TEMPLATE} +# RFC: [Feature Name] -## Current-State Grounding +- **Revision**: R0 - +## Feature Definition Alignment -[Current-state facts, evidence, and relevant existing behavior] +[Exact Feature Definition section paths and semantic titles.] -## Existing Interfaces And Integration Seams +## Verified Current State - +[Verified facts, constraints, and source attribution.] -[Existing interfaces, seams, owners, and compatibility considerations] +## Design Decisions -## Planning Constraints +### [Semantic Decision Title] - +[Decision, rationale, consequences, and Feature Definition alignment.] -[Constraints and their evidence] +## Proposed Architecture -## Documentation Impact +[Components, boundaries, state, and integration seams.] - +## Contracts and Flows -[Documentation impact and rationale] +[Interfaces, data, failure behavior, compatibility, and migration.] + +## Alternatives and Risks + +[Genuine alternatives, risks, and mitigations.] + +## Verification Strategy + +[Evidence implementation must produce.] + +## Planning Handoff + +[Execution boundaries, dependencies, documentation impact, and considerations.] + +## Source References + +[Feature-local and project evidence.] + +## Review Record + +| Role | Report | Round | Revision | Status | Verdict | +|---|---|---|---|---|---| +| rfc_design | reviews/rfc-design.md | None | None | Pending | Pending | +| rfc_clarity | reviews/rfc-clarity.md | None | None | Pending | Pending | + +## Design Acceptance + +| Field | Value | +|---|---| +| Status | Pending | +| Applies To Revision | None | +| Recorded By | Pending | +| Recorded At | Pending | +| Rationale | Pending | diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/progress-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/progress-template.md index 915f02bd..8e64b939 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/templates/progress-template.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/progress-template.md @@ -1,71 +1,50 @@ -# Execution Progress: +# Execution Progress: [Feature Name] ## Execution Context -- **Feature Directory**: -- **Started**: -- **Last Updated**: -- **Status**: in-progress | blocked | complete -- **Review Branch**: -- **Execution Base**: -- **Integration Branch**: -- **Concurrency Policy**: Linear DAG | Parallel allowed -- **Final Review Mode**: aggregate dirty diff -- **Checkpoint Range**: .. | Pending -- **Checkpoint Ref**: refs/agent-checkpoints/ | Pending +- **Feature Directory**: [Project-relative canonical directory] +- **Package Status**: in-progress | blocked | complete | abandoned +- **Active Branch**: [Named target branch] +- **Starting Commit**: [Pinned target commit] +- **Protected Baseline**: [Tracked feature-directory inventory and content evidence] +- **Signing Policy**: [Mode, instruction paths/digests, Git values/origins, observation commit, human resolution] -## Execution Groups +## Packet States -| Group | Task IDs | Planned Model | Required Skills | Required Capabilities | Resolved Worker / Model | Workspace | Tests | Implementation | Integration | Status | Notes | -|---|---|---|---|---|---|---|---|---|---|---|---| -| EGNN | TNNN | Cheapest \| Mid-tier \| Most capable | | | pending | pending | pending | pending | pending | pending | | +| Canonical Identity | Locator | Worktree | Branch | Binding | State | Final Commit | +|---|---|---|---|---|---|---| +| subplans/01-semantic-name.md | [worktree-root-relative] | pending | pending | pending | pending | pending | -Group `Status` is exactly `pending`, `binding`, `in progress`, `blocked: `, `ready for integration/checkpoint`, or `done`. `Tests`, `Implementation`, and `Integration` are exactly `pending`, `in progress`, `done`, `skipped: `, or `blocked: `. - -## Current State - - +State is exactly `pending`, `in-progress`, `ready`, `blocked`, or `done`. ## Execution Audit -| Group | Tier Evidence | Skill Evidence | Capability Evidence | Dispatch Evidence | Dirty-State Preflight | Build/Cache Reuse | Checkpoint | Verification | -|---|---|---|---|---|---|---|---|---| -| EGNN | pending | pending | pending | pending | pending | pending | pending | pending | - -## Test Evidence - -| Group | Tests / Exception | Verification | -|---|---|---| -| EGNN | | pending | - -## Completed Artifacts - -| Group | Flow ID | Contract ID | Files / Outputs | Result Summary | Checkpoint | -|---|---|---|---|---|---| -| EGNN | DFNN or None | CTNN or None | | | | +| Event | Packet | Evidence | Outcome | +|---|---|---|---| +| [Policy freshness, pin/repin, dispatch, result, rebase, candidate, integration] | [Identity or package] | [Attributable durable evidence] | [Outcome] | -Use `None` for `Flow ID` and `Contract ID` only when the output does not cross a group boundary. +## Test and Verification Evidence -## Checkpoints +| Packet | Planned Mode and Basis | Commands or Checks | Outcome | Changed Test Paths | +|---|---|---|---|---| -| Group | Commit | Local Ref | State | -|---|---|---|---| -| EGNN | Pending | Pending | pending | +## Runtime Consideration Evidence -Checkpoint `State` is exactly `pending`, `retained`, `released`, or `missing`. +| Packet | Condition | Attempt / Failure | Alternative | Residual Limitation | +|---|---|---|---|---| -## Exceptions / Blockers +Record an explicit empty entry when no listed condition affected a packet. - +## Contract Outputs -## Failures - - +| Name | Producer Identity | Final Commit | Returned Evidence | Coordinator Validation | Consumers | +|---|---|---|---|---|---| -## Regressions +## Blockers and Recovery - +[Collected blocker batches, known-start recovery evidence, abandonment, and decisions.] ## Final Verification - +[Aggregate verification, component-documentation review, every packet’s mode and +outcome, affected runtime conditions, alternatives, residual limits, and result.] diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/research-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/research-template.md new file mode 100644 index 00000000..74debdfe --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/research-template.md @@ -0,0 +1,19 @@ +# Research: [Feature Name] + +## Verified Evidence + +[Evidence with sources.] + +## Alternatives + +### [Alternative] + +[Benefits, costs, constraints, and rejection or selection rationale.] + +## Working Decisions and Consequences + +[Provisional technical choices; durable choices are restated in `plan.md`.] + +## Open Design Questions + +[Questions requiring planning resolution or human decision.] diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-report-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-report-template.md index 1e8a7497..e3afddad 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-report-template.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/review-report-template.md @@ -1,41 +1,29 @@ -# Review: [ROLE NAME] +# Review: [Role] -- **Role ID**: [role-id] -- **Model Tier**: [Cheapest | Mid-tier | Most capable] -- **Latest Round**: RNN -- **Latest Verdict**: [Passed | Passed with concerns | Blocking] -- **Reviewed At**: [ISO-8601 timestamp] - -## Scope - -[The role packet's question boundary and the current review scope] +- **Role**: [Role name] +- **Tier**: mid-tier | most-capable +- **Latest Round**: RNN | None +- **Latest Verdict**: passed | passed-with-concerns | blocking | pending ## Rounds ### RNN -- **Analysis Run**: ARNN -- **Trigger**: [initial | baseline | tasks | decomposition-design | documentation | reviewer-config | all | explicit | comma-separated union] -- **Inputs**: [project-relative artifact paths] -- **Planned Tier Verified**: Yes -- **Fresh Context Verified**: Yes -- **Attributable Result Verified**: Yes -- **Verdict**: [Passed | Passed with concerns | Blocking] - -| ID | Category | Severity | Location | Summary | Recommendation | Resolution | -|----|----------|----------|----------|---------|----------------|------------| -| None | None | None | None | None | None | None | - -#### Prior Finding Dispositions - -| Prior Finding ID | Disposition | Current Finding ID | Notes | -|------------------|-------------|--------------------|-------| -| None | None | None | None | - - +- **Trigger**: initial | targeted change | recovery +- **Scope**: [Complete current-state review scope] +- **Reviewed Paths**: [Project-relative paths] +- **Binding Evidence**: [Candidate, tier/skills, workspace, invocation, start, result] +- **Verdict**: passed | passed-with-concerns | blocking + +#### Current Findings + +### [Semantic Finding Title] + +- **Impact**: blocking | concern +- **Location**: [Semantic artifact location] +- **Evidence**: [Observed condition] +- **Recommendation**: [Concrete remediation] + +Every appended round is a complete current snapshot and carries unaffected current +findings during a targeted rerun. Do not use opaque finding IDs or disposition +matrices. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/spec-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/spec-template.md new file mode 100644 index 00000000..2903fc4e --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/spec-template.md @@ -0,0 +1,43 @@ +--- +kind: feature-definition +status: Draft +--- + +# Feature Definition: [Feature Name] + +## Intent + +[Underlying need, desired outcome, and why it matters.] + +## Scope + +### Included + +[Bounded outcomes and explicit boundaries.] + +### Excluded + +[Work deliberately outside this feature.] + +## Requirements + +### [Semantic Requirement Title] + +[Outcome plus inline acceptance evidence.] + +## Constraints and Dependencies + +[Applicable product constraints and dependencies, or `None`.] + +## Consequential Decision Context + +[Human-owned consequential decisions, alternatives, and rationale, or `None`.] + +## Material Open Questions + +[Questions that could materially change the Feature Definition; `None` only when Ready.] + +## Conditional Context + +[Add only relevant actors, journeys, entities, terminology, failures, risks, +accessibility, localization, compatibility, or operations.] diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/subplan-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/subplan-template.md new file mode 100644 index 00000000..7e4d90a7 --- /dev/null +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/subplan-template.md @@ -0,0 +1,66 @@ +--- +kind: subplan +primary_files: + - project/root/relative/path +execution: + model_tier: mid-tier + rationale: "Substantive provider-neutral tier rationale." + skills: + - exact-skill-id +test: + mode: required + basis: "Planned test scope and exact test location, suite, or command." +contracts: + produces: [] + consumes: [] +--- + +# [Packet Objective] + +## Objective + +[Bounded outcome owned by this packet.] + +## Baseline Context and Constraints + +[Accepted RFC context, constraints, and protected feature-directory boundary.] + +## Scope and Primary Files + +[Exact owned project-root-relative paths and exclusions.] + +## Prerequisites and Integration + +### Direct Predecessors + +| Path | Classification | Reason | +|---|---|---| + + + +### Transitive Context + +[Non-authoritative inherited background, or `None`.] + +## Runtime Considerations + +[Anticipated conditions only; they are not access grants, eligibility rules, or gates.] + +## Acceptance and Verification + +[Exact commands/checks, expected outcomes, and evidence for frozen test mode/basis.] + +## Required Outputs and Handoff + +When produces is empty, add no produced-contract section. For every produced name, +add exactly one direct level-three heading in this form: + +```markdown +### Produced Contract: `semantic-contract-name` +``` + +Under each such heading add exactly once and in order: `#### Description`, +`#### Contract`, `#### Transport`, `#### Invariants and Constraints`, and +`#### Required Output Evidence`. No extra direct level-four peer is allowed. The +last subsection names evidence returned by worker and recorded against final +integrated producer commit. diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/templates/tasks-template.md b/private_dot_config/specify/presets/timors-agentic-workflow/templates/tasks-template.md index 8d05b31c..3d2dc41d 100644 --- a/private_dot_config/specify/presets/timors-agentic-workflow/templates/tasks-template.md +++ b/private_dot_config/specify/presets/timors-agentic-workflow/templates/tasks-template.md @@ -1,100 +1,61 @@ --- - -description: "Task list template for feature implementation" +kind: task-package +subplans: + - path: subplans/01-semantic-name.md + after: [] +reviews: + rfc_fidelity: + report: reviews/tasks-rfc-fidelity.md + round: null + status: pending + verdict: pending + executability: + report: reviews/tasks-executability.md + round: null + status: pending + verdict: pending +authorization: pending --- -# Tasks: [FEATURE NAME] - -**Input**: Design documents from `/specs/[###-feature-name]/` - -**Prerequisites**: plan.md (required), spec.md (required for user stories), research.md, data-model.md, contracts/ - -**Tests**: Generate tests by default for testable behavior. When new tests are -not practical, state either `Existing coverage: ` -or `Not applicable: ` in that phase. - -**Organization**: Tasks are grouped by user story for independent delivery. -Shared foundation and cross-cutting work have dedicated phases only when they -cannot be owned by one story. - -## Format: `[ID] [P?] [Story?] Description with exact path` - -- Every task is `- [ ] TNNN [P?] [Story?] `. -- IDs start at `T001` and increase sequentially without gaps. -- `[P]` is task-local: the task touches different files and does not depend on - an incomplete task. It does not declare execution-group concurrency. -- `[Story]` is required for story tasks and omitted from setup, foundation, and - cross-cutting phases. -- Every task description names its exact project-relative file path. +# Execution Package: [Feature Name] - +## Overview -## Phase 1: Setup - -**Purpose**: [Feature-specific initialization purpose] - -**Test Expectation**: [Tests required | Existing coverage: concrete evidence expected | Not applicable: concrete reason] - -- [ ] T001 [Action] in [exact/project-relative/path] - -**Checkpoint**: [Observable setup state] - ---- +[Accepted RFC scope, package objective, canonical feature directory.] -## Phase 2: Foundation +## Sub-Plan Ledger -**Purpose**: [Shared prerequisite that cannot be owned by one user story] +| Order | Path | Direct Predecessors | Objective | +|---|---|---|---| +| 1 | subplans/01-semantic-name.md | None | [Bounded objective] | -**Test Expectation**: [Tests required | Existing coverage: concrete evidence expected | Not applicable: concrete reason] +Ledger rows, order, paths, and direct predecessor sets exactly project frontmatter. -- [ ] T002 [Action] in [exact/project-relative/path] +## Dependency Graph -**Checkpoint**: [Observable foundation state] +```mermaid +graph TD + P1[01 semantic name] +``` ---- - -## Phase 3: User Story 1 - [Title] (Priority: P1) - -**Goal**: [Behavior or value delivered by this story] - -**Independent Test**: [Observable steps and result proving this story alone] - -**Test Expectation**: [Tests required | Existing coverage: concrete evidence expected | Not applicable: concrete reason] - -### Tests for User Story 1 - -- [ ] T003 [P] [US1] [Test behavior] in [exact/project-relative/test-path] - -### Implementation for User Story 1 - -- [ ] T004 [US1] [Implement behavior] in [exact/project-relative/source-path] - -**Checkpoint**: [Observable, independently testable story result] - ---- +This is a human projection; frontmatter alone schedules. - +## Execution Inputs and Requirements -## Final Phase: Cross-Cutting Concerns +[Aggregate verification, accepted scope, baseline constraints, and requirements.] -**Purpose**: [Work that necessarily spans completed stories] +## Review Record -**Test Expectation**: [Tests required | Existing coverage: concrete evidence expected | Not applicable: concrete reason] +| Role | Report | Round | Status | Verdict | +|---|---|---|---|---| +| rfc_fidelity | reviews/tasks-rfc-fidelity.md | null | pending | pending | +| executability | reviews/tasks-executability.md | null | pending | pending | -- [ ] TNNN [Action] in [exact/project-relative/path] +## Implementation Authorization -**Checkpoint**: [Observable final state and regression result] +[Human rationale and decision context. Only `approved` frontmatter permits execution.] -## Task Checks +## Execution Handoff -- Every task has a sequential `TNNN`, an exact path, and the applicable - story label. -- Every `[P]` marker is justified by that task's files and prerequisites. -- Every story has a goal, independent test, and behavioral checkpoint. -- Every phase records an allowed concrete test expectation. +- **Component Documentation Review**: required | not-applicable +- **Paths or Reason**: [Relevant paths or substantive skip reason.] diff --git a/private_dot_config/specify/presets/timors-agentic-workflow/tests/test_human_review_contract.py b/private_dot_config/specify/presets/timors-agentic-workflow/tests/test_human_review_contract.py deleted file mode 100644 index b9603b95..00000000 --- a/private_dot_config/specify/presets/timors-agentic-workflow/tests/test_human_review_contract.py +++ /dev/null @@ -1,202 +0,0 @@ -#!/usr/bin/env python3 -"""Deterministic contract checks for optional human review projections.""" - -from pathlib import Path - - -PACKAGE = Path(__file__).resolve().parent.parent -MANIFEST = PACKAGE / "preset.yml" -COMPATIBILITY = PACKAGE / "references" / "protocol-compatibility.md" -REVIEW = PACKAGE / "references" / "human-review.md" -EXECUTION_PLAN_TEMPLATE = PACKAGE / "templates" / "execution-plan-template.md" -SPECIFY = PACKAGE / "commands" / "speckit.specify.md" -PLAN = PACKAGE / "commands" / "speckit.plan.md" -ANALYZE = PACKAGE / "commands" / "speckit.analyze.md" -README = PACKAGE / "README.md" - - -def check(condition, message): - if not condition: - raise AssertionError(message) - - -def text(path): - return path.read_text(encoding="utf-8") - - -def test_manifest_inventory_and_command_mappings(): - manifest = text(MANIFEST) - compatibility = text(COMPATIBILITY) - - check(REVIEW.is_file(), "shared human-review reference is missing") - check(SPECIFY.is_file(), "wrapped specify command is missing") - check( - 'name: "speckit.specify"' in manifest - and 'file: "commands/speckit.specify.md"' in manifest - and 'strategy: "wrap"' in manifest, - "manifest does not wrap speckit.specify", - ) - check("optional human review" in manifest, "preset metadata omits human review") - check( - "commands/speckit.specify.md" in compatibility - and "references/human-review.md" in compatibility, - "package inventory omits human-review surfaces", - ) - check( - "speckit.specify" in compatibility and "human-review.md" in compatibility, - "compatibility mapping rules omit the specify review projection", - ) - - -def test_preset_version_boundary_keeps_protocol_stable(): - manifest = text(MANIFEST) - execution_plan_template = text(EXECUTION_PLAN_TEMPLATE) - - check('version: "0.2.1"' in manifest, "preset version is not 0.2.1") - check( - 'protocol_version: "0.1.0"' in manifest, - "execution-plan protocol version is not 0.1.0", - ) - check( - "**Preset Protocol Version**: 0.1.0" in execution_plan_template, - "execution-plan template protocol version is not 0.1.0", - ) - - -def test_execution_model_repeats_the_group_tier_and_rationale(): - execution_plan_template = text(EXECUTION_PLAN_TEMPLATE) - expected_model = ( - "#### Execution Model\n\n" - "**Model Tier**: Mid-tier\n" - "**Rationale**: [Provider-neutral rationale for the semantic tier selected " - "in Execution Groups.]" - ) - - check( - execution_plan_template.count(expected_model) == 2, - "execution-model sections must contain matching model-tier and rationale lines", - ) - - -def test_completion_projections_preserve_upstream_and_exclude_analyze(): - reference = text(REVIEW) - normalized_reference = " ".join(reference.lower().split()) - specify = text(SPECIFY) - plan = text(PLAN) - analyze = text(ANALYZE) - - for command, name in ((specify, "specify"), (plan, "plan")): - deferral = "## Completion Report And Handoff Deferral" - review_heading = "## Optional " + ( - "Specification" if name == "specify" else "Planning" - ) + " Human Review" - check("## Package Integrity Gate" in command, name + " omits package gate") - check("references/human-review.md" in command, name + " omits shared review") - check("{CORE_TEMPLATE}" in command, name + " does not retain upstream composition") - check(deferral in command, name + " omits final-report deferral") - pre_core = command[: command.index("{CORE_TEMPLATE}")] - normalized_pre_core = " ".join(pre_core.split()) - for phrase in ( - "Execute the complete upstream workflow", - "artifact generation", - "validation", - "mandatory post-execution hooks", - "Do not emit the upstream final Completion Report", - "handoffs", - "optional human-review step below has completed or is declined", - ): - check( - " ".join(phrase.split()) in normalized_pre_core, - name + " deferral omits: " + phrase, - ) - check( - command.index(deferral) < command.index("{CORE_TEMPLATE}") < command.index(review_heading), - name + " does not defer reporting before core while retaining post-core review", - ) - check( - "after" in command.lower() and "validated" in command.lower(), - name + " does not place review after validated artifact generation", - ) - check("scripts:" not in command, name + " overrides inherited scripts") - check("agent_scripts:" not in command, name + " overrides inherited agent scripts") - check("references/human-review.md" not in analyze, "analyze advertises human review") - - for phrase in ( - "guided walkthrough", - "independent review", - "optional", - "Pause after each review unit", - "immediately update every", - "affected artifact owned by the current phase", - "no persisted preference", - "no approval record", - "no workflow gate", - "Do not force a literal section-by-section or file-by-file walkthrough", - ): - check( - " ".join(phrase.lower().split()) in normalized_reference, - "review protocol omits: " + phrase, - ) - - -def test_phase_guidance_and_docs_are_present(): - specify = " ".join(text(SPECIFY).lower().split()) - plan = " ".join(text(PLAN).lower().split()) - readme = text(README).lower() - - for phrase in ( - "problem/outcome/scope", - "scenarios/priorities", - "acceptance behavior/edge cases", - "measurable success criteria", - ): - check(" ".join(phrase.split()) in specify, "specify guidance omits: " + phrase) - for phrase in ( - "technical approach/research decisions", - "interfaces/integration/data/contracts", - "testing/validation", - "documentation impact/unresolved design choices", - ): - check(" ".join(phrase.split()) in plan, "plan guidance omits: " + phrase) - check("human review" in readme, "README omits human-review behavior") - - -def test_current_phase_ownership_prevents_specification_reconfirmation(): - reference = " ".join(text(REVIEW).lower().split()) - plan = " ".join(text(PLAN).lower().split()) - - for phrase in ( - "select only consequential decisions owned or introduced by the current phase", - "authoritative baselines for the current phase", - "must not become review units requiring renewed confirmation", - ): - check( - " ".join(phrase.split()) in reference, - "shared review ownership rule omits: " + phrase, - ) - - for phrase in ( - "treat the current `spec.md` requirements, scenarios, boundaries, and success criteria as authoritative inputs", - "review only technical/design decisions introduced or derived during planning", - "does not introduce a meaningful planning choice must not be presented merely to reconfirm the specification", - "correct the plan rather than reopen the specification", - "route it to the stock owning workflow; do not relitigate it inside planning review", - ): - check( - " ".join(phrase.split()) in plan, - "plan ownership guidance omits: " + phrase, - ) - - -def main(): - test_manifest_inventory_and_command_mappings() - test_preset_version_boundary_keeps_protocol_stable() - test_execution_model_repeats_the_group_tier_and_rationale() - test_completion_projections_preserve_upstream_and_exclude_analyze() - test_phase_guidance_and_docs_are_present() - test_current_phase_ownership_prevents_specification_reconfirmation() - print("timors-agentic-workflow human-review contract: all checks passed") - - -if __name__ == "__main__": - main()