Fission-AI · 2233admin · Jul 1, 2026 · Jul 1, 2026
@@ -0,0 +1,17 @@
+## Summary
+
+<!-- Briefly describe the change. -->
+
+## Why
+
+<!-- Explain project/user value. Link an OpenSpec change proposal for larger changes. -->
+
+## Validation
+
+<!-- List commands, checks, or review evidence. -->
+
+- [ ] Relevant tests passed, or non-applicability is documented.
+
+## AI Assistance
+
+<!-- If AI assisted, name the agent and model. Example: Generated with Codex using GPT-5.5. -->
@@ -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.

@@ -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

@@ -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

@@ -0,0 +1,3 @@
+schema: spec-driven
+created: 2026-07-01
+goal: Trial-run the phase workflow on a small PIT contract promotion task.
@@ -0,0 +1,3 @@
+# promote-pit-contract-candidate
+
+Promote a recurring planning insight into a reviewable contract candidate.
@@ -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.
@@ -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
@@ -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`
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		# promote-pit-contract-candidate

		Promote a recurring planning insight into a reviewable contract candidate.