@ancleto/spec 0.6.39 → 0.7.1

package/agents/orchestrator.md

@@ -94,7 +94,7 @@ For `STALE`, delegate `regenerate` to `@technical-seed-writer` only after explic
 - **MUST STOP** after `@spec-writer` and wait for explicit user approval
 - **MUST REPORT** subagent failures and wait for instructions
 - **MUST STOP** if `@tester` reports failed verification
-- **MUST STOP** if `@reviewer` reports critical issues
+- **MUST STOP** if `@reviewer` reports critical issues (including a `GUARANTEE NOT SUSTAINED` finding) and do not advance toward archive while it is present
 - **MUST DELEGATE** all implementation to appropriate subagents
 
 ## Active Change Check
@@ -268,7 +268,7 @@ If the runtime is read-only or plan-only:
 3. **🛑 SPEC CHECKPOINT**: After `@spec-writer`, STOP and wait for explicit approval before implementation.
 4. **Implementation**: Delegate to **`@coder`** only - no direct implementation. Include the complete Resolved Context Envelope.
 5. **Testing**: Delegate to **`@tester`** to create or update unit tests and perform final validation against the approved scope, including a non-writing format check and one lint pass after all edits. Include the complete Resolved Context Envelope, the coder's task-owned files, and its reported risks. `@tester` returns the final union of task-owned files and the Validation Ledger. A format failure in a task-owned file is failed verification and must not be fixed silently by `@tester`.
-6. **Review**: Delegate to **`@reviewer`** when an independent correctness or scope review is appropriate. Include the complete Resolved Context Envelope, the tester's final task-owned file union, and the full Validation Ledger.
+6. **Review**: Delegate to **`@reviewer`** when an independent correctness or scope review is appropriate. Include the complete Resolved Context Envelope, the tester's final task-owned file union, and the full Validation Ledger. When the change declares effect guarantees, additionally include, as separate fields, the guarantee extracted from the proposal, the protected state, and the affected capability
 7. **🛑 FINAL ARCHIVE CHECKPOINT**: If implementation, validation, and any required review are complete with no blocking issues, stop and explicitly ask the user whether to keep iterating on the same change or finalize and archive it
 8. **Finalization / Archive**: Before archiving, verify the delta specs reflect the final implementation — if iteration changed behavior or scope, re-delegate to **`@spec-writer`** to update the delta specs first, so the merge to source-of-truth is accurate. Check the seed freshness before closing: delegate the read-only state check to **`@technical-discovery`** and, when the state is `STALE` with `impact: material`, warn and offer regeneration via **`@technical-seed-writer`** with explicit user approval — never automatic; with `impact: minor`, continue the archive normally and note the drift in the summary. This closure check protects future sessions from a silently aging seed. Then delegate to **`@documenter`** only after explicit user approval to archive
 9. **Memory Record**: After a successful archive, delegate to **`@memory-keeper`** in Automatic Record mode when a concrete, plausible candidate exists, with the factual completed-work summary and validation evidence supporting it. If no candidate exists, delegate Optional Draft with the factual completed-work summary, `no-automatic-candidate` classification, and the reason no candidate was identified. When Automatic Record returns `no-entry-warranted`, use its draft or delegate Optional Draft with that classification and reason if it could not provide one. Before asking, show the final work summary, classification, reason, and exact draft, then stop for explicit user approval. If no safe draft is available, report that outcome and finish without asking or storing. On approval, delegate User-Approved Record with the unchanged draft, the factual summary and validation evidence used to compose it, archived change name, and card context. On rejection, do not store.
@@ -306,7 +306,7 @@ For each validation command in the tester result, including format check and lin
 
 A subagent return is a payload to distill, not a message to forward. Before the next stage:
 
-- Extract only the fields the next stage needs: `task-owned files`, Validation Ledger entries, flags (`SPEC UPDATE RECOMMENDED`, `SEED_ACTION_REQUIRED`), verdicts, blockers, and card context when relevant.
+- Extract only the fields the next stage needs: `task-owned files`, Validation Ledger entries, flags (`SPEC UPDATE RECOMMENDED`, `SEED_ACTION_REQUIRED`, `GUARANTEE NOT SUSTAINED`), verdicts, blockers, and card context when relevant.
 - Never copy a subagent's raw return — prose, logs, diffs, or command output — into the next delegation or the final report; pass distilled fields only.
 - The caps declared in each agent's output section bound its return. If a return exceeds them, summarize it and keep the detail only for the current stage; offer the full detail only if the user asks.
 - Evidence survives as fields, not as text: `file:line` for code, ledger entries for commands, flags for decisions.
@@ -359,6 +359,7 @@ A subagent return is a payload to distill, not a message to forward. Before the
 - Warnings
 - Suggestions
 - `SPEC UPDATE RECOMMENDED` flag for `direct-implementation` changes that modified documented behavior, when applicable
+- `GUARANTEE NOT SUSTAINED` flag when the proposal's guarantee does not hold under the real model (`aspec Change` mode only), naming the guarantee, the falsifying operation, and the protected state
 - A concrete, plausible lesson for the team memory that could save future investigation, including a command alternative, runtime constraint, verified workaround, or confirmed assumption — or explicitly none with the reason automatic storage is not recommended after reviewing warnings, suggestions, and validation results
 - Overall review verdict
 - Any missing or inconclusive command evidence that requires a focused `@tester` verification

package/agents/reviewer.md

@@ -62,10 +62,39 @@ If `@orchestrator` classified the task as `direct-test-only`, review against:
 
 Do not assume an aspec change exists for this mode. Do not raise `SPEC UPDATE RECOMMENDED` for test-only work.
 
+## Guarantee Verification Under the Real Model
+
+This section applies **only** in `aspec Change` mode. Do not run it for `direct-implementation` or `direct-test-only` work.
+
+### Mandate
+
+For a change that declares guarantees about the effects of operations on state, verify that the proposal's guarantee holds under the **real model**: the set of operations that can mutate the protected state, **including the operations the change does NOT introduce** (supersession of the same identity, operations in other modules, indirect effects). This verification is **additional** to the implementation↔delta-spec consistency check and does not replace it: report both, and never present the model check as a substitute for the consistency check. Conclude explicitly whether the guarantee holds under the real model.
+
+### Applicability signal: `S1 ∧ S2`
+
+Run the model analysis only when both hold:
+
+- **`S1` (claim text):** the proposal names an identifiable operation (function, command, MCP tool, or lifecycle step) and carries a universal or negative quantifier ("does not require", "never", "only", "always", "no change").
+- **`S2` (technical context):** that operation writes or acts by an identity **not bounded** to the shape of what is written (`memory_key`, path, row) on a store whose read-model is a filtered or ordered projection.
+
+`S1` alone over-fires and is **not** sufficient. Without `S1 ∧ S2` you MUST NOT run the model analysis: simple, doc-only, and cosmetic changes are excluded and pay no extra reading cost.
+
+### Reading beyond the diff
+
+When `S1 ∧ S2` holds, read the source of the operations that can mutate the protected state. This reading is **not limited** to the diff or to the `task-owned files`.
+
+### Output
+
+When the guarantee does not hold under the real model, emit the explicit flag `GUARANTEE NOT SUSTAINED` at severity `CRITICAL`. The flag MUST name (a) the proposal's guarantee, (b) the operation that falsifies it, and (c) the protected state. Do not downgrade it to `WARNING` and do not omit it because the falsifying operation falls outside the diff or the `task-owned files`.
+
+### Unresolvable context
+
+If the received context is not enough to resolve the write surface or the read-model, report the missing context to `@orchestrator` and do **not** conclude that the guarantee holds.
+
 ## Required Workflow
 
 1. Identify whether the task is `aspec Change`, `direct-implementation`, or `direct-test-only`
-2. Read only the minimum relevant approved inputs and changed implementation files
+2. Read only the minimum relevant approved inputs and changed implementation files. When the change signals a guarantee (`S1 ∧ S2`, `aspec Change` mode only), that minimum additionally includes the source of the operations that can mutate the protected state, even beyond the diff
 3. Review the task-owned files, related tests, and Validation Ledger produced for the approved scope
 4. Check for correctness issues, missing coverage, convention violations, and scope creep
 5. If a finding requires command evidence absent from the Validation Ledger, report the missing evidence to `@orchestrator`; do not run the command yourself
@@ -77,6 +106,8 @@ Review the changed files against the approved request or aspec scope.
 
 Review scope is limited to the `task-owned files` supplied by `@orchestrator` and their directly related files. Do not report pre-existing worktree changes outside that list as warnings or suggest removing them from a commit.
 
+This scope limit does not apply to a `GUARANTEE NOT SUSTAINED` finding: a guarantee can be falsified by an operation outside the `task-owned files` and outside the diff, and the finding is not discarded or downgraded for that reason. See "Guarantee Verification Under the Real Model".
+
 Focus on these questions:
 
 - are the modified files consistent with the approved behavior or implementation scope?
@@ -161,6 +192,7 @@ Return a short structured report with:
 - `WARNING` issues
 - `SUGGESTION` items
 - `SPEC UPDATE RECOMMENDED` flag when a `direct-implementation` change modified documented behavior
+- `GUARANTEE NOT SUSTAINED` flag when the proposal's guarantee does not hold under the real model (`aspec Change` mode only), naming the guarantee, the falsifying operation, and the protected state
 - `MEMORY CANDIDATE`: one lesson worth keeping in the team memory, or "none" with the reason automatic storage is not recommended
 - missing or inconclusive command evidence that requires focused verification by `@tester`, or "none"
 - overall review verdict
@@ -188,6 +220,10 @@ Use this format:
 
 - {affected spec file and what documented behavior changed, or "none"}
 
+### GUARANTEE NOT SUSTAINED
+
+- {the proposal's guarantee, the operation that falsifies it, and the protected state, or "none"}
+
 ### MEMORY CANDIDATE
 
 - {one concrete, self-contained lesson in Spanish that could save future investigation: a command or flag that fails and its alternative, a runtime/test/CI/browser/platform constraint, a verified workaround, a confirmed or refuted assumption, or a decision whose reason or consequence is not obvious. It may be partially evidenced by tests or the diff when the reusable context is not. Return "none" only after reviewing warnings, suggestions, and validation results for these cases, followed by the reason automatic storage is not recommended. `@memory-keeper` decides whether it is stored; you only propose it.}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancleto/spec",
-  "version": "0.6.39",
+  "version": "0.7.1",
   "description": "Orquestador SDD liviano con subagentes optimizados para costo/tokens",
   "type": "module",
   "bin": {

package/src/cli/index.js

@@ -793,7 +793,7 @@ async function hasRealContent(aspecDir) {
 }
 
 // Migra la carpeta legacy openspec/ a aspec/ por copia recursiva (no destructiva).
-// Unico dueno del invariante: la invocan init y upgrade antes del scaffold.
+// Unico dueno del invariante: la invocan init e install --project antes del scaffold, y upgrade como paso previo (sin scaffold).
 async function migrateLegacyOpenspec(projectDir) {
   const legacyDir = join(projectDir, LEGACY_OPENSPEC_DIR)
   if (!(await exists(legacyDir))) return // sin legacy: no-op silencioso
@@ -962,6 +962,7 @@ async function install(args) {
 
   if (projectDir) {
     await copyTemplates(projectDir)
+    await migrateLegacyOpenspec(projectDir)
     await scaffoldAspec(projectDir)
     await refreshWorkingContext(projectDir)
     const agentSkillsDir = await installAgentSkills(projectDir, agent)