From acc4821e0ef9c0169393571b98699130e793994c Mon Sep 17 00:00:00 2001 From: Curry Date: Thu, 2 Jul 2026 01:15:36 +0800 Subject: [PATCH 1/2] docs: promote PIT contract candidate --- .../add-change-stacking-awareness/proposal.md | 2 +- .../specs/change-stacking-workflow/spec.md | 16 ++++-- .../add-change-stacking-awareness/tasks.md | 2 +- .../.openspec.yaml | 3 + .../promote-pit-contract-candidate/README.md | 3 + .../proposal.md | 25 +++++++++ .../specs/planning-contract-promotion/spec.md | 56 +++++++++++++++++++ .../promote-pit-contract-candidate/tasks.md | 15 +++++ 8 files changed, 116 insertions(+), 6 deletions(-) create mode 100644 openspec/changes/promote-pit-contract-candidate/.openspec.yaml create mode 100644 openspec/changes/promote-pit-contract-candidate/README.md create mode 100644 openspec/changes/promote-pit-contract-candidate/proposal.md create mode 100644 openspec/changes/promote-pit-contract-candidate/specs/planning-contract-promotion/spec.md create mode 100644 openspec/changes/promote-pit-contract-candidate/tasks.md diff --git a/openspec/changes/add-change-stacking-awareness/proposal.md b/openspec/changes/add-change-stacking-awareness/proposal.md index 19a9adf97a..7f25e61a5f 100644 --- a/openspec/changes/add-change-stacking-awareness/proposal.md +++ b/openspec/changes/add-change-stacking-awareness/proposal.md @@ -37,7 +37,7 @@ Enhance change validation to detect planning issues early: - missing dependencies - dependency cycles - archive ordering violations (for example, attempting to archive a change before all `dependsOn` predecessors are archived) -- unmatched capability markers (for example, `requires` marker with no provider in active history emits non-blocking warning) +- unmatched capability markers (for example, `requires` marker with no active or archived provider evidence emits non-blocking warning; archived suppression requires explicit change-level provider evidence) - overlap warnings when active changes touch the same capability Validation should fail only for deterministic blockers (for example cycles or missing required dependencies), and keep overlap checks as actionable warnings. diff --git a/openspec/changes/add-change-stacking-awareness/specs/change-stacking-workflow/spec.md b/openspec/changes/add-change-stacking-awareness/specs/change-stacking-workflow/spec.md index 689584ac49..5a6d8fe475 100644 --- a/openspec/changes/add-change-stacking-awareness/specs/change-stacking-workflow/spec.md +++ b/openspec/changes/add-change-stacking-awareness/specs/change-stacking-workflow/spec.md @@ -46,12 +46,20 @@ The system SHALL treat capability markers as validation contracts and `touches` - **THEN** validation SHALL NOT infer an implicit dependency edge - **AND** ordering SHALL continue to be determined solely by explicit `dependsOn` relationships -#### Scenario: Requires marker satisfied by archived history +#### Scenario: Archived provider evidence suppresses missing-provider warning - **WHEN** a change declares a `requires` marker -- **AND** no active change provides that marker -- **AND** at least one archived change in history provides that marker +- **AND** no active change declares the corresponding `provides` marker +- **AND** archived history contains explicit change-level provider evidence for that marker - **THEN** validation SHALL NOT warn solely about missing provider -- **AND** SHALL continue to use explicit `dependsOn` for active ordering +- **AND** the provider evidence SHALL identify the archived change and marker source used for the decision +- **AND** validation SHALL continue to use explicit `dependsOn` for active ordering + +#### Scenario: Ambiguous provider evidence still warns +- **WHEN** a change declares a `requires` marker +- **AND** no active change declares the corresponding `provides` marker +- **AND** archived history has no explicit change-level provider evidence for that marker +- **THEN** validation SHALL emit a non-blocking warning naming the change and missing marker +- **AND** validation SHALL NOT suppress the warning from fuzzy text matches or inferred capability names #### Scenario: Requires marker missing in full history - **WHEN** a change declares a `requires` marker diff --git a/openspec/changes/add-change-stacking-awareness/tasks.md b/openspec/changes/add-change-stacking-awareness/tasks.md index 2273377ca9..93ea52e5e5 100644 --- a/openspec/changes/add-change-stacking-awareness/tasks.md +++ b/openspec/changes/add-change-stacking-awareness/tasks.md @@ -9,7 +9,7 @@ - [ ] 2.1 Detect dependency cycles and fail validation with deterministic errors - [ ] 2.2 Detect missing `dependsOn` targets (referenced change ID does not exist) and detect changes transitively blocked by unresolved/cyclic dependency paths - [ ] 2.3 Add overlap warnings for active changes that touch the same capability/spec areas -- [ ] 2.4 Emit advisory warnings for unmatched `requires` markers when no provider exists in active history +- [ ] 2.4 Emit advisory warnings for unmatched `requires` markers when no active or archived provider evidence exists; require explicit change-level evidence before archived providers suppress the warning - [ ] 2.5 Add tests for cycle, missing dependency, overlap warning, and unmatched `requires` cases ## 3. Sequencing Commands diff --git a/openspec/changes/promote-pit-contract-candidate/.openspec.yaml b/openspec/changes/promote-pit-contract-candidate/.openspec.yaml new file mode 100644 index 0000000000..50aafe1719 --- /dev/null +++ b/openspec/changes/promote-pit-contract-candidate/.openspec.yaml @@ -0,0 +1,3 @@ +schema: spec-driven +created: 2026-07-01 +goal: Trial-run the phase workflow on a small PIT contract promotion task. diff --git a/openspec/changes/promote-pit-contract-candidate/README.md b/openspec/changes/promote-pit-contract-candidate/README.md new file mode 100644 index 0000000000..d4ba9ff196 --- /dev/null +++ b/openspec/changes/promote-pit-contract-candidate/README.md @@ -0,0 +1,3 @@ +# promote-pit-contract-candidate + +Promote a recurring planning insight into a reviewable contract candidate. diff --git a/openspec/changes/promote-pit-contract-candidate/proposal.md b/openspec/changes/promote-pit-contract-candidate/proposal.md new file mode 100644 index 0000000000..63216d36a3 --- /dev/null +++ b/openspec/changes/promote-pit-contract-candidate/proposal.md @@ -0,0 +1,25 @@ +## Why + +Research and spec documents often contain governance decisions before they are ready to become canonical product requirements. A useful promotion path cannot just write down the insight; it must show that source material can be distilled into an executable contract candidate and tied to a concrete test or evidence gate. + +This change is a deliberately small PIT contract promotion trial. It promotes one recurring planning insight into an explicit contract-candidate record that names the source, contract shape, ownership boundary, and validation gate. + +## What Changes + +- Add a `planning-contract-promotion` capability delta defining how research/spec material becomes eligible for contract-candidate review. +- Require promoted candidates to cite the source document and the exact source claim being promoted. +- Require each candidate to map the promoted contract to either an automated test, a documented evidence gate, or an explicit reason no executable gate exists yet. +- Record candidate source `openspec/explorations/workspace-user-journeys.md`, where shared behavior promotion is described as a future long-lived contract concern. +- Keep this trial as reviewable OpenSpec artifact work only; no runtime behavior changes are proposed here. + +## Capabilities + +### New Capabilities + +- `planning-contract-promotion`: Review path for promoting research/spec insights into executable contract candidates and evidence gates. + +## Impact + +- Documentation/spec artifact only. +- No runtime behavior, schema, command, or generated output changes. +- Follow-up implementation can use the contract to add validation, tests, or release evidence gates. \ No newline at end of file diff --git a/openspec/changes/promote-pit-contract-candidate/specs/planning-contract-promotion/spec.md b/openspec/changes/promote-pit-contract-candidate/specs/planning-contract-promotion/spec.md new file mode 100644 index 0000000000..6f2fb38bab --- /dev/null +++ b/openspec/changes/promote-pit-contract-candidate/specs/planning-contract-promotion/spec.md @@ -0,0 +1,56 @@ +## ADDED Requirements + +### Requirement: Research Source Extraction +The promotion workflow SHALL extract contract candidates from explicit research or spec source material before treating them as reviewable product contracts. + +#### Scenario: Source claim is promoted from research or spec material +- **GIVEN** a research or spec document contains a recurring governance or behavior claim +- **WHEN** the claim starts guiding implementation, review, or sequencing decisions +- **THEN** the promotion artifact SHALL cite the source document path +- **AND** the artifact SHALL identify the specific source claim being promoted +- **AND** the artifact SHALL explain why the claim is mature enough for contract-candidate review + +#### Scenario: Promotion source remains auditable +- **GIVEN** a contract-candidate artifact cites a source document +- **WHEN** reviewers inspect the promotion +- **THEN** the cited source SHALL be sufficient to recover the original research/spec context +- **AND** the promotion SHALL NOT rely on uncited conversation memory as its only evidence + +### Requirement: Contract Candidate Promotion Record +Exploration notes that repeatedly describe shared behavior SHALL be promoted into an explicit contract-candidate record before they become canonical requirements. + +#### Scenario: Repeated planning insight gets a reviewable candidate +- **GIVEN** an exploration note describes shared behavior that may become a long-lived contract +- **WHEN** the same behavior starts guiding implementation or review decisions +- **THEN** the team SHALL create a contract-candidate change artifact +- **AND** the artifact SHALL cite the source exploration note +- **AND** the artifact SHALL state whether it changes product behavior or only records planning intent + +#### Scenario: Candidate does not become canonical automatically +- **GIVEN** a contract-candidate artifact exists +- **WHEN** reviewers have not assigned ownership for the shared behavior +- **THEN** the candidate SHALL NOT be treated as a canonical product spec +- **AND** follow-up work SHOULD either assign ownership or leave the candidate as exploratory planning context + +### Requirement: Evidence Gate Mapping +A promoted contract candidate SHALL map to an automated test or documented evidence gate before it is considered ready for implementation or archival. + +#### Scenario: Candidate maps to executable validation +- **GIVEN** a contract-candidate artifact defines expected behavior +- **WHEN** the behavior can be validated automatically +- **THEN** the artifact SHALL name the automated test or validation command that should prove the contract +- **AND** the artifact SHALL define the observable pass condition + +#### Scenario: Candidate maps to documented evidence when automation is not ready +- **GIVEN** a contract-candidate artifact defines expected behavior +- **AND** no automated test exists yet +- **WHEN** reviewers evaluate the candidate +- **THEN** the artifact SHALL name the documented evidence gate instead +- **AND** the evidence gate SHALL specify the artifact, transcript, checklist, or review record required to prove the contract +- **AND** the artifact SHALL state what future work would convert the evidence gate into an automated test + +#### Scenario: Candidate without evidence gate remains exploratory +- **GIVEN** a contract-candidate artifact has no automated test and no documented evidence gate +- **WHEN** validation or review summarizes the candidate +- **THEN** the candidate SHALL remain exploratory planning context +- **AND** the candidate SHALL NOT be presented as ready for implementation or archival \ No newline at end of file diff --git a/openspec/changes/promote-pit-contract-candidate/tasks.md b/openspec/changes/promote-pit-contract-candidate/tasks.md new file mode 100644 index 0000000000..9eef97670e --- /dev/null +++ b/openspec/changes/promote-pit-contract-candidate/tasks.md @@ -0,0 +1,15 @@ +## 1. Source Extraction +- [x] 1.1 Identify the research/spec source for the PIT promotion trial +- [x] 1.2 Capture the promoted source claim in proposal/spec language + +## 2. Contract Candidate +- [x] 2.1 Define the promoted contract candidate as OpenSpec requirement scenarios +- [x] 2.2 Preserve the ownership boundary: the candidate does not become canonical automatically + +## 3. Evidence Gate +- [x] 3.1 Require each candidate to map to an automated test or documented evidence gate +- [x] 3.2 Define fallback evidence requirements when automation is not ready +- [x] 3.3 Keep ungated candidates exploratory, not implementation-ready + +## 4. Verification +- [x] 4.1 Validate change `openspec validate promote-pit-contract-candidate --json` \ No newline at end of file From 194de25cbd0eb0798cbed490f8fc364972194899 Mon Sep 17 00:00:00 2001 From: Curry Date: Thu, 2 Jul 2026 01:28:49 +0800 Subject: [PATCH 2/2] docs: add pull request template --- .github/PULL_REQUEST_TEMPLATE.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000000..279fa91114 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,17 @@ +## Summary + + + +## Why + + + +## Validation + + + +- [ ] Relevant tests passed, or non-applicability is documented. + +## AI Assistance + + \ No newline at end of file