@ancleto/spec 0.13.1 → 0.13.2

package/agents/memory-keeper.md

@@ -18,6 +18,8 @@ tools:
 
 You are the single owner of the repository's memory (`.ancleto/memory.db`, SQLite + FTS5). No other agent reads or writes it. You have four modes, and `@orchestrator` tells you which one.
 
+At close, `@orchestrator` may delegate you **in parallel** with `@documenter`: you write only `.ancleto/memory.db`, never the archive, and you never need the archive's output — the change name you record arrives in the delegation, so you do not wait on that stage.
+
 The memory is shared across sessions: what you write, someone else recalls months later, in another change, without today's context. A wrong or noisy entry is worse than no entry, because it is retrieved as precedent.
 
 **Boundary:** the repository memory (yours) is distinct from any *agent/session* memory service the runtime may expose (e.g. engram). Repo rules and decisions live here, never duplicated there; transient, personal session notes belong to that other service, not here. When in doubt, it goes here — this is the one that outlives the repo and is shared with the team. The frontier is documented for projects in `AGENTS.md`.
@@ -54,7 +56,7 @@ Do **not** run a recall before writing. Deduplication is the engine's job, not y
 
 ## Mode 3 — Optional Draft
 
-Called when no automatic candidate exists, or when Automatic Record declined one. The delegation includes the factual completed-work summary, any relevant validation findings, and one classification:
+Called only when the user explicitly requests an optional draft. It is never the automatic continuation of Automatic Record: with no candidate, the close finishes without storing and does not invoke this mode. The delegation includes the factual completed-work summary, any relevant validation findings, and one classification:
 
 - `no-automatic-candidate` — no concrete candidate was identified, so Automatic Record was not invoked.
 - `no-entry-warranted` — Automatic Record assessed a candidate and declined to store it.
@@ -65,7 +67,7 @@ Called when no automatic candidate exists, or when Automatic Record declined one
 
 ## Mode 4 — User-Approved Record
 
-Called only after the user explicitly approved the exact draft shown by `@orchestrator`. The delegation must include that unchanged draft plus the factual completed-work summary and validation evidence used to compose it; include card context when available.
+Called only when the user explicitly asks to store a specific memory text (or approves a draft they requested). It is never an automatic closure step. The delegation must include that exact text plus the factual completed-work summary and validation evidence used to compose it; include card context when available.
 
 1. Do not reassess the automatic usefulness bar and do not rewrite the approved text.
 2. Verify the approved text against the supplied factual evidence. It must not contain workflow metadata or invented facts. If it does, report the blocker and do not call any memory tool.

package/agents/orchestrator.md

@@ -137,7 +137,7 @@ Resolve the working language for artifact content once per session:
 - Pass the resolved `language` in the Resolved Context Envelope to every subagent that writes artifacts.
 - Artifact content uses the resolved language; keywords (`Requirement`, `Scenario`, `SHALL`, `WHEN`/`THEN`/`AND`, `ADDED/MODIFIED/REMOVED/RENAMED Requirements`) and file/directory names stay literal English.
 
-Pass each tramo only the envelope fields that tramo needs (the distillation contract lives in `### Handling subagent returns`): `@coder` receives the implementation scope; `@tester` receives that scope plus the coder's task-owned files and risks; `@reviewer` receives that plus the task-owned files and the Validation Ledger. Never re-send the whole envelope verbatim. Preserve always: the five control artifacts (`task-owned files`, `Validation Ledger`, `SPEC UPDATE RECOMMENDED`, `SEED_ACTION_REQUIRED`, `GUARANTEE NOT SUSTAINED`) and evidence as `file:line`. Do not omit numbered requirements, paths, commands, acceptance criteria, or explicit exclusions. Only `@context-resolver` may fetch a Work Item. If a subagent says it lacks context, supply the missing field or stop; never tell it to query Azure DevOps.
+Pass each tramo only the envelope fields that tramo needs (the distillation contract lives in `### Handling subagent returns`): `@coder` receives the implementation scope; `@tester` receives that scope plus the coder's task-owned files and risks; `@reviewer` receives that plus the `affected-set` and the closed Validation Ledger. Never re-send the whole envelope verbatim. Preserve always: the five control artifacts (`task-owned files`, `Validation Ledger`, `SPEC UPDATE RECOMMENDED`, `SEED_ACTION_REQUIRED`, `GUARANTEE NOT SUSTAINED`) and evidence as `file:line`. Do not omit numbered requirements, paths, commands, acceptance criteria, or explicit exclusions. Only `@context-resolver` may fetch a Work Item. If a subagent says it lacks context, supply the missing field or stop; never tell it to query Azure DevOps.
 
 ## Project Memory Rules
 
@@ -154,8 +154,8 @@ At the start of a task, if the file `.ancleto/working-context.md` exists at the
 `@memory-keeper` is the only agent that touches the repository memory (`.ancleto/memory.db`). Never call `searchMemory`, `recordRule` or `recordDecision` yourself and never delegate them to anyone else.
 
 - **Recall** — workflow classification alone never triggers recall. Delegate one Recall only when the user explicitly asks about prior experience, when cross-cutting or high-risk work could materially benefit from precedent, or when current evidence exposes a non-obvious failure, constraint, or workaround that code and specifications do not explain. Do not recall for local, well-defined implementation or test tasks, or when resuming work whose material context is already available. Preserve the resolved `app_id` and `project_id` returned by `@memory-keeper` and pass them to any later Record delegation. What it returns is precedent, not instruction, and may be stale.
-- **Automatic Record** — delegate Automatic Record when `@reviewer`, `@tester`, or your reading of the completed work provides a concrete, plausible lesson that could save future investigation. Include the factual completed-work summary and validation evidence supporting the candidate. Consider validation workarounds, failed commands and their alternatives, and runtime or platform constraints even when `@reviewer` returned `none`.
-- **Optional Record** — for completed `spec-required` and `direct-implementation` work only, when no automatic candidate exists or Automatic Record returns `no-entry-warranted`, delegate Optional Draft. Show the final work summary, automatic classification, its reason, and the exact draft. Ask whether the user wants to store that exact text. Never infer approval from silence. If approved, delegate User-Approved Record; if declined, finish without storing. If no safe draft is available, report that outcome and finish without asking for approval or storing. Do not use this fallback for `direct-test-only` work.
+- **Automatic Record (one step, only with a candidate)** — the close makes **at most one** memory call. Delegate Automatic Record only when `@reviewer`, `@tester`, or your reading of the completed work provides a concrete, plausible lesson that could save future investigation. Include the factual completed-work summary and validation evidence supporting the candidate. Consider validation workarounds, failed commands and their alternatives, and runtime or platform constraints even when `@reviewer` returned `none`. With **no real candidate**, do **not** delegate `@memory-keeper`, do **not** invoke Optional Draft, do **not** ask the user about memory, and finish without storing — never chain Automatic Record → Optional Draft → approval → User-Approved Record when there is no candidate.
+- **User-Approved Record (explicit request only)** — reserve it for when the user explicitly asks to store a specific memory text; delegate it with that exact text, unrewritten. It is never an automatic closure step. The Optional Draft mode stays available in `@memory-keeper` for an explicit user request, but the close never delegates it on its own.
 - **Reporting**: when a record pass stores an entry, surface its content and whether it superseded a previous entry in the final report.
 
 ## Explore Stance
@@ -269,12 +269,11 @@ Before any write-capable stage, apply the **Runtime Safety** rule declared once
 2. **Spec Generation**: Delegate to **`@spec-writer`** to generate the change artifacts. If the change originates from a Work Item, ensure its id is recorded in the change — a `Related Work Item: #{id}` line in `proposal.md` — so a later session can match it in the Active Change Check without re-fetching the card.
 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. When the change declares effect guarantees, additionally include, as separate fields, the guarantee extracted from the proposal, the protected state, and the affected capability
+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, the deterministic `affected-set` (dependents included), and a **complete and closed Validation Ledger** for the review scope. A format failure in a task-owned file is failed verification and must not be fixed silently by `@tester`.
+6. **Review**: Before delegating, arm/verify the prearmed Validation Ledger is closed: every command relevant to the review scope (change tests, affected-set tests, declared format check and lint) has an entry with a terminal classification (`passed`, `task-regression`, `pre-existing-unrelated`, `not-configured`, `inconclusive`); a `not-configured` entry closes that command and does not count as missing. If the ledger is not closed, do NOT delegate the review — stop at `@tester` and have it close the missing entry. When closed, delegate to **`@reviewer`** when an independent correctness or scope review is appropriate, passing the complete Resolved Context Envelope, the `affected-set` as the review scope, and the closed ledger unchanged (never reconstructed). 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, following the canonical rule in the `LOCKED: seed-freshness` block of `AGENTS.md`: delegate the read-only state check to **`@technical-discovery`** and regenerate only with explicit user approval, never automatically. 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.
-10. **Report**: Return final status or blocking findings to the user after automatic storage, an explicit decline, or User-Approved Record completes.
+8. **Finalization / Archive ∥ Memory Record (in parallel)**: 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, following the canonical rule in the `LOCKED: seed-freshness` block of `AGENTS.md`: delegate the read-only state check to **`@technical-discovery`** and regenerate only with explicit user approval, never automatically. This closure check protects future sessions from a silently aging seed. Then, after explicit user approval to archive, start **`@documenter`** and — only when a concrete, plausible memory candidate exists — **`@memory-keeper`** (Automatic Record) **in parallel**: they write disjoint surfaces (`aspec/` for `@documenter`, `.ancleto/memory.db` for `@memory-keeper`) and neither needs the other's output — the change name the record needs is known before the archive — so do not wait for one to finish before starting the other. With no real candidate, delegate only `@documenter`: do not delegate `@memory-keeper`, do not invoke Optional Draft, and do not ask the user about memory (one memory call maximum). If the record would need the archive result, do not parallelize and report the blocker. Collect and report the state of both stages.
+9. **Report**: Return final status or blocking findings to the user once both finalization stages settle, or after the archive alone when there was no memory candidate.
 
 ### Path B: Direct-Implementation Changes
 
@@ -282,17 +281,17 @@ Before any write-capable stage, apply the **Runtime Safety** rule declared once
 2. **WAIT**: Do not delegate to `@coder` until the user responds explicitly
 3. **NO IMPLIED CONFIRMATION**: Do not assume approval from silence, delay, or lack of objection
 4. **Implementation**: Delegate to **`@coder`** only after explicit user confirmation of the direct path. Include the complete Resolved Context Envelope.
-5. **Validation**: Delegate to **`@tester`** with the complete Resolved Context Envelope, the coder's task-owned files, and its reported risks. Require a non-writing format check and one lint pass after all edits. Preserve the tester's final task-owned file union and Validation Ledger. A format failure in a task-owned file is failed verification and must not be fixed silently by `@tester`. Delegate to **`@reviewer`** when the completed direct change modifies user-visible behavior or user-facing content that may already be documented in a source-of-truth spec. For internal changes without observable behavior impact, independent review remains optional. Include the complete envelope, final file union, and full ledger. `@reviewer` remains the only agent responsible for checking whether an existing source-of-truth spec requires an update.
+5. **Validation**: Delegate to **`@tester`** with the complete Resolved Context Envelope, the coder's task-owned files, and its reported risks. Require a non-writing format check and one lint pass after all edits. Preserve the tester's final task-owned file union, its deterministic `affected-set` (dependents included), and its closed Validation Ledger. A format failure in a task-owned file is failed verification and must not be fixed silently by `@tester`. Delegate to **`@reviewer`** when the completed direct change modifies user-visible behavior or user-facing content that may already be documented in a source-of-truth spec. For internal changes without observable behavior impact, independent review remains optional. Include the complete envelope, the `affected-set` as the review scope, and the closed ledger. `@reviewer` remains the only agent responsible for checking whether an existing source-of-truth spec requires an update.
 6. **🛑 SPEC DOCUMENTATION CHECKPOINT**: If `@reviewer` raised a `SPEC UPDATE RECOMMENDED` flag, STOP and ask the user whether to update the affected source-of-truth spec. Do not assume approval from silence, delay, or lack of objection
 7. **Spec Documentation**: Only after explicit user approval, delegate to **`@documenter`** in `Standalone Source-of-Truth Update` mode to update `aspec/specs/{capability}/spec.md`
-8. **Memory Record**: 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. Otherwise 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, and available card context. On rejection, do not store.
-9. **Report**: Return final status or blocking findings to the user after automatic storage, an explicit decline, or User-Approved Record completes. When a source-of-truth spec was updated, explicitly highlight in the summary that documentation was left for this direct change, naming the updated spec file
+8. **Memory Record (one step, only with a candidate)**: Make at most **one** memory call. Delegate to **`@memory-keeper`** in Automatic Record mode only when a concrete, plausible candidate exists, with the factual completed-work summary and validation evidence supporting it. With no real candidate, do not delegate `@memory-keeper`, do not invoke Optional Draft, do not ask the user about memory, and finish without storing. Reserve User-Approved Record for an explicit user request to store a specific text.
+9. **Report**: Return final status or blocking findings to the user after automatic storage or after finishing without storing. When a source-of-truth spec was updated, explicitly highlight in the summary that documentation was left for this direct change, naming the updated spec file
 
 ### Path C: Direct-Test-Only Changes
 
-1. **Testing Work**: Delegate to **`@tester`** only, with the complete Resolved Context Envelope. Preserve its final task-owned file union and Validation Ledger.
+1. **Testing Work**: Delegate to **`@tester`** only, with the complete Resolved Context Envelope. Preserve its final task-owned file union, its `affected-set`, and its Validation Ledger.
 2. **Escalation Check**: If `@tester` discovers that the request actually requires product-code changes or broader scope, stop and reclassify through the orchestrator
-3. **Review**: Delegate to **`@reviewer`** only when an independent review is useful, with the complete envelope, final task-owned file union, and Validation Ledger
+3. **Review**: Delegate to **`@reviewer`** only when an independent review is useful, with the complete envelope, the `affected-set` as the review scope, and the Validation Ledger
 4. **Memory Record**: Only when a concrete, plausible candidate lesson exists, delegate to **`@memory-keeper`** in Automatic Record mode with that candidate, its factual completed-work summary, validation evidence, and available card context. If it returns `no-entry-warranted`, report that result and do not offer the optional fallback.
 5. **Report**: Return final status or blocking findings to the user
 
@@ -300,9 +299,9 @@ Before any write-capable stage, apply the **Runtime Safety** rule declared once
 
 Before advancing to the next stage, verify that each subagent returned a usable result.
 
-`@tester` returns the final `task-owned files` union: the coder's files plus any tests it modified. They are the only worktree files considered for scope review unless a directly related file is required to investigate a finding. Do not treat pre-existing changes outside this set as task findings.
+`@tester` returns the final `task-owned files` union (the coder's files plus any tests it modified) and the deterministic `affected-set`: the closure of dependents on the import graph, seeded by those files, plus the files themselves. The `affected-set` is the scope of review — it includes the dependents, not only the changed files. Do not treat pre-existing changes outside that set as task findings.
 
-For each validation command in the tester result, including format check and lint, preserve a Validation Ledger entry with: command, outcome (`passed`, `task-regression`, `pre-existing-unrelated`, or `inconclusive`), and related files when it failed. Pass it unchanged to `@reviewer`. A confirmed `pre-existing-unrelated` result is reported once in the final status as a non-blocking residual limitation; do not stop, re-run it, or request a correction unless a later relevant change invalidates that classification.
+For each validation command in the tester result, including format check and lint, preserve a Validation Ledger entry with: command, outcome (`passed`, `task-regression`, `pre-existing-unrelated`, `not-configured`, or `inconclusive`), and related files when it failed. A `not-configured` entry (the project declares no formatter, or no such command) is a terminal non-failure that closes the ledger for that command: it is not a missing entry and does not block the review. Verify every scope command has a terminal entry before delegating the review, then pass the closed ledger unchanged to `@reviewer`. A confirmed `pre-existing-unrelated` result is reported once in the final status as a non-blocking residual limitation; do not stop, re-run it, or request a correction unless a later relevant change invalidates that classification.
 
 ### Handling subagent returns
 

package/agents/reviewer.md

@@ -95,16 +95,16 @@ If the received context is not enough to resolve the write surface or the read-m
 
 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. 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
+3. Review the `affected-set` and its tests against the prearmed, closed Validation Ledger supplied 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
+5. Treat the prearmed Validation Ledger as evidence: consume it without reconstructing or re-running anything. Do not request a re-delegation to `@tester` for command evidence that is missing or inconclusive **within the covered scope** — a ledger that does not cover a scope command is an orchestrator precondition failure, not a reviewer request. You still report missing **context** (not command evidence) needed for the guarantee verification. You do not have Bash and must not run commands yourself
 6. Return a short structured review report
 
 ## Scope Review Rules
 
 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.
+Review scope is the `affected-set` supplied by `@orchestrator` — the deterministically propagated closure of dependents, including the `task-owned files` themselves — not just the changed files. Do not report pre-existing worktree changes outside that set 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".
 
@@ -167,7 +167,7 @@ Do not block on minor style nits when the change is otherwise correct.
 
 ## Validation Evidence
 
-Treat the tester's Validation Ledger as evidence. A `pre-existing-unrelated` entry is a non-blocking residual limitation: do not elevate it to a warning unless the review finds evidence that it affects task-owned files. When evidence is missing or inconclusive, report exactly what `@tester` would need to verify. You do not have Bash and must not run commands or external requests.
+The tester's prearmed Validation Ledger is the authoritative evidence for the covered scope: consume it as-is, and do not reconstruct or summarize it. A `pre-existing-unrelated` entry is a non-blocking residual limitation: do not elevate it to a warning unless the review finds evidence that it affects task-owned files. A `not-configured` entry is a registered non-failure (the project declares no such command): it closes the ledger for that command and is not missing evidence. When the ledger covers a scope command as `inconclusive`, treat it as evidence and do not request a re-delegation to `@tester` within the covered scope. Report missing **context** (not command evidence) needed to resolve the guarantee verification. You do not have Bash and must not run commands or external requests.
 
 ## Memory Candidate Review
 
@@ -194,7 +194,7 @@ Return a short structured report with:
 - `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"
+- missing **context** for the guarantee verification (not command evidence; the prearmed ledger covers the review scope), or "none"
 - overall review verdict
 
 **Output cap**: at most 5 findings per severity (`CRITICAL`, `WARNING`, `SUGGESTION`); if more exist, keep the 5 highest-impact and state the count of the rest, offering detail on request. `Summary` max 5 lines. Cite `file:line`; never paste diffs or code.

package/agents/tester.md

@@ -67,7 +67,8 @@ When reporting results:
 - state whether they passed or failed
 - summarize any failures or gaps that remain
 - clearly separate verified behavior from unverified assumptions
-- classify every command in the Validation Ledger as `passed`, `task-regression`, `pre-existing-unrelated`, or `inconclusive`
+- classify every command in the Validation Ledger as `passed`, `task-regression`, `pre-existing-unrelated`, `not-configured`, or `inconclusive`
+- return a **complete and closed** Validation Ledger for the review scope: every command relevant to it —the change's tests, the tests of the affected set, and the declared format check and lint— has an entry with a terminal classification. A `not-configured` entry (the project declares no formatter, or no such command) is a registered non-failure that closes that command, consistent with the `LOCKED: validation-commands` policy; it is not a missing entry and does not block the review
 
 ## Input Modes
 
@@ -130,6 +131,8 @@ Prefer the smallest command that proves the change AND catches regressions in th
 
 Being economical means running the affected set, not the whole repo — it does NOT mean narrowing to only the changed files. Collateral breakage in dependent code is a real risk and must be caught, not skipped as "out of scope".
 
+The affected set is the deterministic `affected-set`: the transitive closure of **dependents** on the project's import graph, seeded by the task-owned files, plus those files themselves. Compute it with the mechanism the project declares in `PRODUCT.md` → `## Project Commands`; when the project declares none, use the read-only CLI `ancleto affected [--cwd <dir>] [--json] <file...>`. Its import graph covers the static forms `import`, `import … from`, `export … from`, `require(...)` and `import(...)` over `.js/.mjs/.cjs/.ts/.tsx`, respects the project's ignores, and is reproducible: the same repository state plus the same seed yields the same set. Report the computed `affected-set` as your verification target. Non-relative specifiers (npm packages, Node builtins, and path aliases) are **external by construction**: they never generate a dependency edge and are never `inconclusive`; the read-only surface reports a **count** of them as data, not as a warning. The graph scans only the call forms `import(` and `require(` and classifies each **by its argument**, not by its content: when the argument —after spaces and comments— is a **pure string literal followed by `)`**, the call is static (category 1 if the literal is a resolvable relative, category 2 if it is non-relative); **any other argument** —a bare expression, a **literal prefix followed by an expression** (`'./x' + y`), a template with an expression, a parenthesized argument, etc.— is `inconclusive`. The classifier is **conservative by design**: when in doubt it reports `inconclusive`, never silence, and it promises nothing about dynamics it does not scan. An **unresolved relative** specifier is also `inconclusive`; do not assume any `inconclusive` case covered. To cover path aliases, the project must declare its own affected mechanism in `PRODUCT.md` → `## Project Commands`.
+
 Run each command at most once after the last relevant edit. Do not rerun a passed command or a confirmed pre-existing failure unless the files relevant to it changed. Run the project's declared format check (if any) without `--write`, then the declared lint once against the combined task-owned file set; if the project declares no formatter, the format check is `not-configured`. Do not format production files silently, and do not check paths excluded by the repository configuration.
 
 ## Test Structure Rules
@@ -161,7 +164,8 @@ After validation, return a short structured summary including:
 - tests created or updated
 - `task-owned test files`: the exact tests modified during this delegation
 - `final task-owned files`: the coder's task-owned files plus tests modified during this delegation
-- `Validation Ledger`: each command, outcome classification, and related files when it failed
+- `affected-set`: the deterministic closure of dependents (plus the files themselves) used as the verification target, together with the count of non-relative (external) specifiers reported as data and the inconclusive cases (`import(...)` / `require(...)` calls whose argument is not a pure string literal, and unresolved relatives) reported as `unresolved`
+- `Validation Ledger`: complete and closed for the review scope — each command, outcome classification (including `not-configured`), and related files when it failed
 - verification result
 - whether reclassification was required
 - failed verification items, if any

package/package.json

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

package/src/cli/index.js

@@ -14,6 +14,7 @@ import { writeWorkingContext, writeWorkingContextBlock, renderWorkingContextBloc
 import { memoryDoctor } from '../core/memory/doctor.js'
 import { serveMemoryMcp } from '../core/memory/mcp-server.js'
 import { writeDiscoveryMap } from '../core/discovery.js'
+import { computeAffectedSet } from '../core/affected-set.js'
 import { readProjectTier, buildRepomixArgs, tierTokenBudget } from '../core/repomix-tier.js'
 import { showBanner, selectOption, selectMultiple, stopBanner } from './ui.js'
 import { tierModels, gratisModel, envGratisModel, isKnownGratisModel, MUSE_SPARK_MODEL, GRATIS_FALLBACK_MODEL } from '../core/tier-models.js'
@@ -59,6 +60,10 @@ Uso:
   ancleto specs check [--change <name>] [--json]
                                    Valida keywords canonicos (### Requirement:, WHEN, THEN)
                                    en aspec/specs y, con --change, en los deltas del change
+  ancleto affected [--cwd <dir>] [--json] <archivo...>
+                                   Computa el affected-set (clausura de dependientes por el grafo
+                                   de imports) sembrado por los archivos dados (read-only; reporta
+                                   el conteo de specifiers externos no relativos como dato)
   ancleto stats [--all] [--limit N] [--since YYYY-MM-DD] [--session <id>] [--json]
                                    Tokens por sesion de opencode (entrada/salida/razonamiento/cache),
                                    con rollup de subagentes y desglose por agente con --session
@@ -2598,6 +2603,50 @@ async function specsCheckCommand(args) {
   process.exit(ok ? 0 : 1)
 }
 
+// Read-only: computa el affected-set (dependientes incluidos) sin escribir nada.
+async function affectedCommand(args) {
+  const asJson = args.includes('--json')
+  const ci = args.indexOf('--cwd')
+  if (ci >= 0 && ci + 1 >= args.length) {
+    console.error('ancleto: uso: ancleto affected [--cwd <dir>] [--json] <archivo...>')
+    process.exit(1)
+  }
+  const cwd = ci >= 0 ? resolve(args[ci + 1]) : process.cwd()
+  const seeds = []
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]
+    if (a === '--json') continue
+    if (a === '--cwd') {
+      i += 1
+      continue
+    }
+    seeds.push(a)
+  }
+  if (seeds.length === 0) {
+    console.error('ancleto: uso: ancleto affected [--cwd <dir>] [--json] <archivo...>')
+    process.exit(1)
+  }
+  const { seeds: normalizedSeeds, affected, unresolved, externalCount } = computeAffectedSet({
+    rootDir: cwd,
+    seeds
+  })
+  if (asJson) {
+    console.log(JSON.stringify({ seeds: normalizedSeeds, affected, unresolved, externalCount }, null, 2))
+    return
+  }
+  for (const f of affected) console.log(f)
+  // Dato informativo (no warning ni error): cuantos specifiers no relativos se
+  // trataron como externos. Va a stderr para no ensuciar la lista de stdout y
+  // se omite cuando el conteo es 0 (el campo `externalCount` sigue en --json).
+  if (externalCount > 0) {
+    console.error(`ancleto: affected: ${externalCount} specifier(s) externos (no relativos; dato informativo)`)
+  }
+  if (unresolved.length > 0) {
+    console.error(`ancleto: affected: ${unresolved.length} import(s) no resueltos (inconclusos)`)
+    for (const u of unresolved) console.error(`  ? ${u.file}: ${u.specifier}`)
+  }
+}
+
 function opencodeDbPath() {
   return process.env.ANCLETO_OPENCODE_DB || join(homedir(), '.local', 'share', 'opencode', 'opencode.db')
 }
@@ -3101,6 +3150,9 @@ switch (cmd) {
   case 'specs':
     await specsCheckCommand(rest)
     break
+  case 'affected':
+    await affectedCommand(rest)
+    break
   case 'stats':
     await statsCommand(rest)
     break

package/src/core/affected-set.js

@@ -0,0 +1,288 @@
+import { readFileSync, readdirSync } from 'node:fs'
+import { dirname, join, relative, resolve } from 'node:path'
+import { TOPOLOGY_IGNORED_DIRS } from './discovery.js'
+
+// Mecanismo del affected-set: clausura transitiva de DEPENDIENTES sobre el grafo
+// de imports del proyecto, sembrada por los archivos tocados. Zero-dep y
+// determinista (mismo estado + misma semilla => mismo conjunto).
+//
+// Cobertura: formas estáticas de `import`, `import ... from`, `export ... from`
+// y las llamadas `import(...)` / `require(...)` cuyo argumento es un literal
+// puro (string o template sin expresiones), sobre .js/.mjs/.cjs/.ts/.tsx.
+// Alcance escaneado: sólo las formas de llamada `import(` / `require(`. Otras
+// formas de invocar un import/require dinámico (`require?.(…)`, `(require)(…)`,
+// el acceso computed `obj['require'](…)`) NO se escanean ni se reportan: se
+// delegan al mecanismo declarado por el proyecto. El acceso por miembro
+// `obj.require(…)` sí se matchea léxicamente (`\brequire\b` sin lookbehind):
+// sobre-inclusión conservadora, en la dirección segura, nunca un hueco.
+// Acotación por diseño, no un hueco.
+// Clasificación conservadora por ARGUMENTO, no por contenido de la llamada:
+// sólo una llamada con literal puro —tras espacios y comentarios— seguido de
+// `)` se trata como estática; cualquier otro argumento (expresión pelada,
+// `'./x' + y`, template con `${}`, paréntesis, etc.) se reporta como inconcluso
+// (`unresolved`), nunca en silencio. Los especificadores NO relativos (paquetes,
+// builtins, alias de paths) son externos al grafo y no se resuelven; se cuentan
+// como dato (`externalCount`) para hacer visible la frontera, sin tratarlos como
+// warning ni error. Los relativos que no resuelven también se reportan como
+// inconclusos.
+
+export const SOURCE_EXTENSIONS = ['.js', '.mjs', '.cjs', '.ts', '.tsx']
+
+// Formas estáticas con specifier literal inline (no son llamadas): el argumento
+// de las llamadas `import(...)` / `require(...)` se clasifica aparte.
+const SPECIFIER_PATTERNS = [
+  /\bimport\s+[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g,
+  /\bimport\s*['"]([^'"]+)['"]/g,
+  /\bexport\s+[^'"]*?\bfrom\s*['"]([^'"]+)['"]/g
+]
+
+// Únicas palabras de llamada escaneadas: `import` y `require`. El hueco entre la
+// palabra y el `(` se recorre con skipTrivia (espacios + comentarios), de modo que
+// `require/*c*/('x')` e `import/*c*/('x')` también entran al clasificador. No son
+// llamadas —y se ignoran— `import.meta`, el `import` estático y `require.resolve(`,
+// porque tras la palabra (saltando trivia) el próximo carácter significativo no es `(`.
+const CALL_FORMS = [
+  { re: /\bimport\b/g, kind: 'import' },
+  { re: /\brequire\b/g, kind: 'require' }
+]
+
+const toPosix = (p) => String(p).replace(/\\/g, '/')
+
+export function isSourceFile(name) {
+  return SOURCE_EXTENSIONS.some((ext) => name.endsWith(ext))
+}
+
+// Recorre rootDir juntando archivos fuente, respetando los ignores del proyecto
+// (los mismos que usa el discovery map).
+export function collectSourceFiles(rootDir, ignored = TOPOLOGY_IGNORED_DIRS) {
+  const ignoredSet = new Set(ignored)
+  const out = []
+  const walk = (dir) => {
+    let entries
+    try {
+      entries = readdirSync(dir, { withFileTypes: true })
+    } catch {
+      return
+    }
+    for (const e of entries) {
+      if (e.isDirectory()) {
+        if (ignoredSet.has(e.name)) continue
+        walk(join(dir, e.name))
+      } else if (e.isFile() && isSourceFile(e.name)) {
+        out.push(join(dir, e.name))
+      }
+    }
+  }
+  walk(rootDir)
+  out.sort()
+  return out
+}
+
+const isSpace = (c) => c === ' ' || c === '\t' || c === '\n' || c === '\r' || c === '\f' || c === '\v'
+
+// Avanza sobre espacios y comentarios (`/* */` y `//`). Devuelve el índice del
+// próximo carácter significativo, o null si un comentario de bloque no cierra.
+function skipTrivia(content, i) {
+  let j = i
+  while (j < content.length) {
+    const c = content[j]
+    if (isSpace(c)) {
+      j += 1
+      continue
+    }
+    if (c === '/' && content[j + 1] === '*') {
+      const end = content.indexOf('*/', j + 2)
+      if (end === -1) return null
+      j = end + 2
+      continue
+    }
+    if (c === '/' && content[j + 1] === '/') {
+      const end = content.indexOf('\n', j + 2)
+      j = end === -1 ? content.length : end + 1
+      continue
+    }
+    break
+  }
+  return j
+}
+
+// Lee un string literal de comilla simple o doble desde su apertura; null si no
+// cierra.
+function readQuoted(content, i, quote) {
+  let value = ''
+  let j = i + 1
+  while (j < content.length) {
+    const c = content[j]
+    if (c === '\\') {
+      value += content[j + 1] ?? ''
+      j += 2
+      continue
+    }
+    if (c === quote) return { value, next: j + 1 }
+    value += c
+    j += 1
+  }
+  return null
+}
+
+// Lee un template literal; null si no cierra o si contiene una expresión `${}`.
+function readTemplate(content, i) {
+  let value = ''
+  let j = i + 1
+  while (j < content.length) {
+    const c = content[j]
+    if (c === '\\') {
+      value += content[j + 1] ?? ''
+      j += 2
+      continue
+    }
+    if (c === '`') return { value, next: j + 1 }
+    if (c === '$' && content[j + 1] === '{') return null
+    value += c
+    j += 1
+  }
+  return null
+}
+
+// Clasifica el argumento de una llamada cuyo `(` está en openParen. Devuelve el
+// specifier si —tras espacios y comentarios— el argumento es un string o
+// template sin expresión seguido de `)`; null en cualquier otro caso (argumento
+// no literal), de modo que el caso se reporte como inconcluso.
+function staticCallSpecifier(content, openParen) {
+  const start = skipTrivia(content, openParen + 1)
+  if (start === null || start >= content.length) return null
+  const quote = content[start]
+  let literal = null
+  if (quote === "'" || quote === '"') literal = readQuoted(content, start, quote)
+  else if (quote === '`') literal = readTemplate(content, start)
+  if (literal === null) return null
+  const closing = skipTrivia(content, literal.next)
+  if (closing === null || content[closing] !== ')') return null
+  return literal.value
+}
+
+// Devuelve los especificadores estáticos hallados (import/export … from,
+// `import '…'` y las llamadas `import(...)` / `require(...)` con literal puro) y
+// el conteo de llamadas con argumento no literal, por forma.
+export function extractSpecifiers(content) {
+  const specifiers = []
+  for (const pattern of SPECIFIER_PATTERNS) {
+    pattern.lastIndex = 0
+    let m
+    while ((m = pattern.exec(content)) !== null) {
+      specifiers.push(m[1])
+    }
+  }
+  let dynamicUnresolved = 0
+  let dynamicRequireUnresolved = 0
+  for (const { re, kind } of CALL_FORMS) {
+    re.lastIndex = 0
+    let m
+    while ((m = re.exec(content)) !== null) {
+      // Cierra el hueco palabra→`(` saltando espacios y comentarios: una palabra
+      // `import`/`require` sólo es una llamada si el próximo carácter significativo
+      // es `(`; si no (`.`, `{`, `'`, EOF…), no es una llamada y se ignora.
+      const openParen = skipTrivia(content, m.index + m[0].length)
+      if (openParen === null || content[openParen] !== '(') continue
+      const specifier = staticCallSpecifier(content, openParen)
+      if (specifier !== null) {
+        specifiers.push(specifier)
+      } else if (kind === 'import') {
+        dynamicUnresolved += 1
+      } else {
+        dynamicRequireUnresolved += 1
+      }
+    }
+  }
+  return { specifiers, dynamicUnresolved, dynamicRequireUnresolved }
+}
+
+function resolveRelative(fromFile, spec, fileSet) {
+  if (!spec.startsWith('./') && !spec.startsWith('../')) return null
+  const base = join(dirname(fromFile), spec)
+  const candidates = [base]
+  for (const ext of SOURCE_EXTENSIONS) candidates.push(base + ext)
+  for (const ext of SOURCE_EXTENSIONS) candidates.push(join(base, 'index' + ext))
+  for (const c of candidates) {
+    if (fileSet.has(c)) return c
+  }
+  return null
+}
+
+// Grafo de imports: aristas src -> deps (relativas, posix) y lista de casos
+// inconclusos. `sources` son los nodos del grafo.
+export function buildImportGraph(rootDir, ignored = TOPOLOGY_IGNORED_DIRS) {
+  const files = collectSourceFiles(rootDir, ignored)
+  const fileSet = new Set(files)
+  const edges = new Map()
+  const unresolved = []
+  let externalCount = 0
+  for (const abs of files) {
+    const rel = toPosix(relative(rootDir, abs))
+    const deps = new Set()
+    let content
+    try {
+      content = readFileSync(abs, 'utf8')
+    } catch {
+      edges.set(rel, deps)
+      continue
+    }
+    const { specifiers, dynamicUnresolved, dynamicRequireUnresolved } = extractSpecifiers(content)
+    for (const spec of specifiers) {
+      const resolved = resolveRelative(abs, spec, fileSet)
+      if (resolved) deps.add(toPosix(relative(rootDir, resolved)))
+      else if (spec.startsWith('./') || spec.startsWith('../')) {
+        unresolved.push({ file: rel, specifier: spec })
+      } else {
+        // No relativo no resuelto => externo (paquete/builtin/alias): fuera del
+        // grafo. Se cuenta como dato, no se resuelve ni se reporta inconcluso.
+        externalCount += 1
+      }
+    }
+    if (dynamicUnresolved > 0) {
+      unresolved.push({ file: rel, specifier: 'import(<dynamic>)' })
+    }
+    if (dynamicRequireUnresolved > 0) {
+      unresolved.push({ file: rel, specifier: 'require(<dynamic>)' })
+    }
+    edges.set(rel, deps)
+  }
+  return { edges, sources: new Set(edges.keys()), unresolved, externalCount }
+}
+
+function normalizeSeed(rootDir, seed) {
+  return toPosix(relative(rootDir, resolve(rootDir, seed)))
+}
+
+// affected-set = semilla + clausura transitiva de dependientes. Incluye siempre
+// los archivos sembrados, aunque no sean nodos del grafo (p. ej. un cambio que
+// sólo toca documentación).
+export function computeAffectedSet({ rootDir, seeds, ignored = TOPOLOGY_IGNORED_DIRS }) {
+  const { edges, unresolved, externalCount } = buildImportGraph(rootDir, ignored)
+  const dependents = new Map()
+  for (const [file, deps] of edges) {
+    for (const dep of deps) {
+      if (!dependents.has(dep)) dependents.set(dep, new Set())
+      dependents.get(dep).add(file)
+    }
+  }
+  const seedSet = new Set(seeds.map((s) => normalizeSeed(rootDir, s)))
+  const affected = new Set(seedSet)
+  const queue = [...seedSet]
+  while (queue.length > 0) {
+    const cur = queue.shift()
+    for (const dep of dependents.get(cur) || []) {
+      if (!affected.has(dep)) {
+        affected.add(dep)
+        queue.push(dep)
+      }
+    }
+  }
+  unresolved.sort((a, b) => a.file.localeCompare(b.file) || a.specifier.localeCompare(b.specifier))
+  return {
+    seeds: [...seedSet].sort(),
+    affected: [...affected].sort(),
+    unresolved,
+    externalCount
+  }
+}