@antoneeo/agentic-sdlc-skill 1.49.0 → 1.50.0

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.50.0] - 2026-10-31
+
+### What's new
+
+**You approve the design before any code is written.** On significant work, once the independent design review passes, the agent stops and shows you a short summary of the design: what the change does, for whom and through which surfaces, which files it touches, the risks and how they are handled, and what the review found. The work starts only after your yes, which the agent records in the unit's request record. A "go ahead" given before you saw the design does not count, and in a session with nobody to answer the unit waits for you. A design that is right but not what you meant is cheapest to fix before the code exists. If you work with devPNT, your acceptance of the design proposal there is this approval, and nothing else is asked.
+
+**The npm page tells you what is new.** This section, at the top of the package page, now summarizes each version for the people who install it.
+
+**From 1.49.0, published without notes:**
+- **Fewer regressions on significant changes.** When an analysis states what must not break, the agent is reminded of it just before it edits that file, not only at the start of the work, and the reviewer has the list to check. It is a reminder and never blocks the work; for now it works on Claude Code.
+- **The process checks can no longer be bypassed by accident.** Quoting a work level inside a sentence no longer counts as declaring it, and protected parts of the project stay protected when the agent changes folder.
+- **You know what the project memory has not read yet.** The agent can tell how much of the project it has never examined (automatically in projects with a corpus, on request otherwise).
+- **Defects found after the merge can be recorded** without distorting the review statistics.
+
+#### What to do
+
+**1. Update (everyone).** The changes arrive only with the update.
+1. Run `npm install -g @antoneeo/agentic-sdlc-skill@latest`, then `agentic-sdlc-install-skill`.
+2. Close and reopen your agent sessions: the new version loads only at startup.
+
+To check: `npm ls -g @antoneeo/agentic-sdlc-skill` shows 1.50.0.
+
+If you do not want the constraint reminder (Claude Code only, from 1.49.0): remove the entry that contains `constraints --hook` from `~/.claude/settings.json`. Later updates will not put it back.
+
+**2. Approving the design (significant units).**
+- **This concerns you if** you use the skill for significant (L3) work. Nothing to configure: after the design review passes, the agent asks whether to proceed. Answer yes to start the code, or say what to change; the design is then revised and, where the change touches what the review judged, reviewed again before you are asked again.
+- **A unit already in progress.** Units started before 2026-10-31 are not affected. If a unit started on or after 2026-10-31 with an earlier version is already in progress or finished, `sdlc_check.py validate` shows a `[note]` saying it has `no design approval in its request record`. Why: the earlier version never asked you. To clear it, tell the agent that you approve the design as it was implemented; it records your words under a label that begins `design approved` (for example `design approved after implementation`). The note never fails a check, so you can also leave it.
+- **To check:** on your next significant unit, the agent stops after the design review and asks you before any code starts.
+
+**3. Protected folders in a repository with several `ai_docs/` (only if you use them; from 1.49.0).**
+- **This concerns you if** your agent settings contain `gate --hook --protected` and the repository has more than one `ai_docs/` folder, for example a package with its own.
+- **Why:** protected paths are now read from the `ai_docs/` nearest to the edited file. A path written from the repository root, such as `packages/api/src/auth`, no longer matches the files inside `packages/api`, so the agent could change them without an analysis.
+- **Steps:** rewrite those paths from the package: `packages/api/src/auth` becomes `src/auth`. Note that `src/auth` then protects the folder with that name in every project that has its own `ai_docs/`.
+- **To check:** in a session with no open analysis, ask the agent for a small change to a protected file. It must be refused.
+
+### Changed
+- After the design review's final PASS, an L3 unit stops: the agent presents a short summary of the design (what it does, for whom and through which surfaces, what it touches, threats, the review's verdict) and asks the owner whether to proceed. Only a yes, recorded in the request record under a label that begins `design approved`, moves the ANALYSIS to `IN_PROGRESS`. An instruction given before the design was shown is not an approval; unattended, the unit is `BLOCKED on the user`; in Hybrid the approval in devPNT counts. The rule is in `review.md`; `SKILL.md`, `elicitation.md` and `templates.md` point at it (F-087).
+- The shared validator: `validate` notes an L3 ANALYSIS in implementation, started on or after 2026-10-31, whose request record holds no entry whose label begins `design approved`. It is a `[note]`: `--strict` exits as before. The `gate` refusal message adds that at L3 the ANALYSIS goes `IN_PROGRESS` only after the owner's design approval; its exit codes are unchanged (F-087).
+- The package's npm page (its README) gains a "What's new in <version>" section right after the introduction, written for the people who install the package and linking the full CHANGELOG. It appears from the first version that carries one; each version's notes are the `### What's new` at the top of its CHANGELOG section (F-070). The "Shared project memory" section moves from the top of the page to just after the features, unchanged.
+
 ## [1.49.0] - 2026-10-27
 
 ### Added

package/README.md

@@ -1,22 +1,44 @@
 # Agentic SDLC Skill for Claude Code, Gemini CLI, Google Antigravity & Codex
 
-## Shared project memory
+`agentic-sdlc` is a Documentation-First SDLC protocol for AI coding agents. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, Cursor/Windsurf-style project instructions, and optional devPNT governance.
 
-All four lenses include project memory by default; install the lens you need,
-not a second skill just for recall. `index` registers guides, decisions and plans
-in the docs root's `memory/INDEX.md`, linking originals without copying them.
-`recall "onboarding"` finds related metadata across domains; optional
-`topics: [onboarding]` links documents by subject. Read the originals for authority,
-status and evidence: discovery is not approval or proof of implementation.
+<!-- whats-new:begin -->
+<!-- generated by scripts/whats_new.js from CHANGELOG.md: edit the CHANGELOG, then run node scripts/whats_new.js --write -->
+## What's new in 1.50.0
 
-Registration happens at `index`/documentation closure, not through a background
-watcher. Existing projects acquire the catalog on their next `index`; `recall`
-also sees live metadata. The KB lens remains the specialist for ingestion and
-taxonomy. Marketing retains its numerical validators. See the skill's `memory.md`.
-Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.py`.
+**You approve the design before any code is written.** On significant work, once the independent design review passes, the agent stops and shows you a short summary of the design: what the change does, for whom and through which surfaces, which files it touches, the risks and how they are handled, and what the review found. The work starts only after your yes, which the agent records in the unit's request record. A "go ahead" given before you saw the design does not count, and in a session with nobody to answer the unit waits for you. A design that is right but not what you meant is cheapest to fix before the code exists. If you work with devPNT, your acceptance of the design proposal there is this approval, and nothing else is asked.
 
+**The npm page tells you what is new.** This section, at the top of the package page, now summarizes each version for the people who install it.
 
-`agentic-sdlc` is a Documentation-First SDLC protocol for AI coding agents. It supports Claude Code, Codex, Gemini CLI, Google Antigravity 2.0, Cursor/Windsurf-style project instructions, and optional devPNT governance.
+**From 1.49.0, published without notes:**
+- **Fewer regressions on significant changes.** When an analysis states what must not break, the agent is reminded of it just before it edits that file, not only at the start of the work, and the reviewer has the list to check. It is a reminder and never blocks the work; for now it works on Claude Code.
+- **The process checks can no longer be bypassed by accident.** Quoting a work level inside a sentence no longer counts as declaring it, and protected parts of the project stay protected when the agent changes folder.
+- **You know what the project memory has not read yet.** The agent can tell how much of the project it has never examined (automatically in projects with a corpus, on request otherwise).
+- **Defects found after the merge can be recorded** without distorting the review statistics.
+
+#### What to do
+
+**1. Update (everyone).** The changes arrive only with the update.
+1. Run `npm install -g @antoneeo/agentic-sdlc-skill@latest`, then `agentic-sdlc-install-skill`.
+2. Close and reopen your agent sessions: the new version loads only at startup.
+
+To check: `npm ls -g @antoneeo/agentic-sdlc-skill` shows 1.50.0.
+
+If you do not want the constraint reminder (Claude Code only, from 1.49.0): remove the entry that contains `constraints --hook` from `~/.claude/settings.json`. Later updates will not put it back.
+
+**2. Approving the design (significant units).**
+- **This concerns you if** you use the skill for significant (L3) work. Nothing to configure: after the design review passes, the agent asks whether to proceed. Answer yes to start the code, or say what to change; the design is then revised and, where the change touches what the review judged, reviewed again before you are asked again.
+- **A unit already in progress.** Units started before 2026-10-31 are not affected. If a unit started on or after 2026-10-31 with an earlier version is already in progress or finished, `sdlc_check.py validate` shows a `[note]` saying it has `no design approval in its request record`. Why: the earlier version never asked you. To clear it, tell the agent that you approve the design as it was implemented; it records your words under a label that begins `design approved` (for example `design approved after implementation`). The note never fails a check, so you can also leave it.
+- **To check:** on your next significant unit, the agent stops after the design review and asks you before any code starts.
+
+**3. Protected folders in a repository with several `ai_docs/` (only if you use them; from 1.49.0).**
+- **This concerns you if** your agent settings contain `gate --hook --protected` and the repository has more than one `ai_docs/` folder, for example a package with its own.
+- **Why:** protected paths are now read from the `ai_docs/` nearest to the edited file. A path written from the repository root, such as `packages/api/src/auth`, no longer matches the files inside `packages/api`, so the agent could change them without an analysis.
+- **Steps:** rewrite those paths from the package: `packages/api/src/auth` becomes `src/auth`. Note that `src/auth` then protects the folder with that name in every project that has its own `ai_docs/`.
+- **To check:** in a session with no open analysis, ask the agent for a small change to a protected file. It must be refused.
+
+Full history: [CHANGELOG](https://github.com/Antoneeo/agentic-sdlc-skill/blob/main/CHANGELOG.md)
+<!-- whats-new:end -->
 
 ## Key Features
 
@@ -33,12 +55,27 @@ Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.
 - **Self-activating**: a SessionStart hook emits repo-sourced orientation; a deterministic self-eval battery guards the skill's own doctrine as the release gate.
 - **Standalone complete**: works fully with local `ai_docs/` without requiring devPNT.
 - **devPNT symbiosis**: when devPNT is available, Master Plan, Action Plan, M-VISION, and governed artifacts become the authoritative planning layer, and every governed artifact passes an independent agent review before it is proposed; devPNT itself performs no review — it is where you review and approve.
-- **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author, who receives the whole review mandate in a fixed block copied verbatim, never a paraphrase of it. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when no higher rung is usable: absent, or permission-gated and declined — a gated rung is asked about, never silently skipped, and the log says which), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied.
+- **Independent review, twice**: the design is reviewed before it is implemented and the diff before the work is declared done — by somebody other than its author, who receives the whole review mandate in a fixed block copied verbatim, never a paraphrase of it. Three rungs of independence (fresh-context subagent > one-shot run > a declared self-pass, legal only when no higher rung is usable: absent, or permission-gated and declined — a gated rung is asked about, never silently skipped, and the log says which), capped at 3 rounds, one log line per review, and a PASS is invalid on "found nothing" — it must state where each constraint is satisfied. After the design review passes, the owner approves the design before any code is written.
 - **Question discipline**: a real doubt is asked when it emerges, before its answer is written into any document — grouped, with the pros and cons of each option. A choice whose pros clearly win is taken without asking, and the weighing is written next to it; a fact is settled by evidence or asked, never weighed. A question is legal only when the agent searched first, names the search with its result, and names the decision it unblocks — never a stream of "shall I proceed?".
 - **Installed support files**: Claude, Codex, Gemini, and Google Antigravity receive the full skill folder, including `templates.md`, `architect.md`, `guides.md`, `vision.md`, `tdd.md`, `debugging.md`, `elicitation.md`, `review.md`, `dispatch.md`, `routing.md`, `hybrid.md`, `ENFORCEMENT.md`, `memory.md`, and the validator's three files, `scripts/sdlc_check.py` + `scripts/sdlc_core.py` + `scripts/knowledge.py` — plus the docs site generator `scripts/docs_site.py` and its page `docs_site/`, and the `LICENSE` and `NOTICE` it ships under.
 - **Docs site** (`scripts/docs_site.py --root <project> [--open] [--zip <file>]`): a static, offline, read-only website of what the agent reads in the project — reading guide, Vision, rules, documents, open work with each next step, analyses and, with a knowledge base, the topic map, each fact with its exact source passage, and the source documents. Written to `.docs-site/` (added to `.gitignore` on the first run), outside `ai_docs/`; nothing is ranked or recommended.
 - **Mechanical checks**: optional validator for document structure, generated feature history, stale audit areas, and protected-path gates — `check`, `validate`, `index`, `stale`, `mark`, `benefit`, `gate`, `plan`, `orient`, `migrate`, `review-map` (code lens: classes the files of a change for the merge review brief), `constraints` (code lens: a unit's constraints, or those binding a file). `benefit` reports what the review gates have already caught, beside what the doctrine costs to read — it always exits 0 and carries no verdict, because a measurement that can fail a build becomes a target.
 
+## Shared project memory
+
+All four lenses include project memory by default; install the lens you need,
+not a second skill just for recall. `index` registers guides, decisions and plans
+in the docs root's `memory/INDEX.md`, linking originals without copying them.
+`recall "onboarding"` finds related metadata across domains; optional
+`topics: [onboarding]` links documents by subject. Read the originals for authority,
+status and evidence: discovery is not approval or proof of implementation.
+
+Registration happens at `index`/documentation closure, not through a background
+watcher. Existing projects acquire the catalog on their next `index`; `recall`
+also sees live metadata. The KB lens remains the specialist for ingestion and
+taxonomy. Marketing retains its numerical validators. See the skill's `memory.md`.
+Vendoring requires all three files: the entry point, `sdlc_core.py`, `knowledge.py`.
+
 ## Installation
 
 ### Via npm

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.49.0",
+  "version": "1.50.0",
   "description": "Documentation-First SDLC protocol with triage, Vision governance and optional devPNT integration.",
   "author": "Antonio Pinto (https://github.com/Antoneeo)"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@antoneeo/agentic-sdlc-skill",
-  "version": "1.49.0",
+  "version": "1.50.0",
   "description": "Documentation-First SDLC protocol for Claude Code, Gemini CLI, Google Antigravity and Codex with risk triage, Vision governance, installed support files and optional devPNT integration.",
   "keywords": [
     "claude-code",

package/scripts/init.js

@@ -203,16 +203,16 @@ in the skill's \`routing.md\`: it decides which lens's method and validation rul
 that unit. L1 never reaches it. Never refer to a document whose meaning differs by lens
 ("threat model", "vision", \`principles.md\`, \`handoff.md\`) by its bare name.
 
-Select the owning lens by the unit's purpose, then apply only its risk scale.
-The project's always-on pointer stays intact: consult the selected skill rather than
-merging multiple mandatory ladders. All lenses already carry shared project memory
-(\`memory.md\`); another installation is not needed for cross-domain recall.
+Select the owning lens by the unit's purpose, then apply only its risk scale.
+The project's always-on pointer stays intact: consult the selected skill rather than
+merging multiple mandatory ladders. All lenses already carry shared project memory
+(\`memory.md\`); another installation is not needed for cross-domain recall.
 This file is NOT auto-loaded by any client: it is a note for you, deliberately additive.
-Delete this note once the routing pointer is integrated.
+Delete this note once the routing pointer is integrated.
 `, 'multi-lens routing note');
   if (wrote && protocolPreexisting) {
     console.log('   ⚠️  A protocol pointer already existed and was NOT overwritten.');
-    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
+    console.log('       Integrate the routing pointer from AGENTIC_MULTI_LENS.md; keep one risk scale per unit.');
   }
 }
 

package/skills/agentic-sdlc-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.49.0
+version: 1.50.0
 description: Documentation-First SDLC protocol with risk-proportional triage, Vision as a guide, a complete Standalone mode and optional symbiosis with devPNT. Use for features, significant bugs, refactors, audits and documented maintenance.
 author: Antonio Pinto (https://github.com/Antoneeo)
 copyright: (c) 2026 Antonio Pinto
@@ -195,7 +195,7 @@ Standalone L3:
 - Build the Impact/solution **on** the Vision, the use-cases/user-needs and the Security & Threat Model — read and trace to them first, and state the trace (which actor / use-case / threat / benefit each part serves) so the closure review (`review.md`) can verify conformance. Do not draft the Impact in isolation.
 - For a feature known to span multiple milestones, also create `ai_docs/vision/features/VISION_[feature].md`; the retroactive case (extract it when the SECOND `ANALYSIS_*` on a theme appears) is in Write Triggers.
 
-**Design review gate — the design is reviewed BEFORE any code (L3).** Close Phase 3 by handing the finished ANALYSIS to an *independent* reviewer: the procedure, the independence ladder, the round cap and the log row are `review.md` §When a review is due, moment 1 — follow it there, it is not restated here. Why the moment exists: the closure review can prove the code matches the design, never that the design was right, and the author is structurally blind to what their own design omitted. In Hybrid the same review runs on the `E-ISP`/`E-TDD`, by the client's agent, and its PASS precedes the proposal to devPNT, where the human reviews — `review.md` §When a review is due owns the order.
+**Design review gate — the design is reviewed BEFORE any code (L3).** Close Phase 3 by handing the finished ANALYSIS to an *independent* reviewer: the procedure, the independence ladder, the round cap and the log row are `review.md` §When a review is due, moment 1 — follow it there, it is not restated here. Why the moment exists: the closure review can prove the code matches the design, never that the design was right, and the author is structurally blind to what their own design omitted. In Hybrid the same review runs on the `E-ISP`/`E-TDD`, by the client's agent, and its PASS precedes the proposal to devPNT, where the human reviews — `review.md` §When a review is due owns the order. In Standalone the final PASS is followed by the owner's approval of the design, asked and recorded before any code (same section).
 
 Hybrid L3:
 - Restore the Master Plan, Action Plan and linked documents.
@@ -206,7 +206,7 @@ Hybrid L3:
 
 ### 4. Development and Testing
 
-- Implement only after the documentation gate required by the level. **Flip the ANALYSIS frontmatter `PLANNED` → `IN_PROGRESS` when implementation starts** — that flip is what `gate` and the handoff registry key on, and nothing else performs it.
+- Implement only after the documentation gate required by the level; at L3 it ends with the owner's design approval (`review.md` §When a review is due). **Flip the ANALYSIS frontmatter `PLANNED` → `IN_PROGRESS` when implementation starts** — that flip is what `gate` and the handoff registry key on, and nothing else performs it.
 - Isolate the work: run an L3 change on its own branch. In Hybrid, prefer a git worktree from the start — a running devPNT server locks `.devpnt/*.db` and blocks in-place branch switches/merges in the primary worktree. A session that may run while another session uses the same checkout works in its **own git worktree**, and never switches branch, stashes, resets or runs `index` in a checkout another session may be using. Parallel work also shares ids: choose a new unit's id **after fetching**, as the first id free on every branch and tag the checkout can see (`check` names a collision while the unit is open).
 - Modify surgically, consistently with the plan.
 - Implementation work follows the TDD discipline in `tdd.md` (RED/GREEN/REFACTOR — the L2/L3 default; record the reason when it does not apply).

package/skills/agentic-sdlc-skill/debugging.md

@@ -34,11 +34,11 @@ proof that it caused this incident.
    Do not repeat an invalidated hypothesis unless new evidence reopens it.
 
 3. **Test and trace the mechanism.** Reproduce and isolate the smallest faithful
-   failing case when feasible; bisect inputs, paths or changes when informative.
-   Skip a reproduction already known to omit the incident's causal conditions;
-   choose a faithful alternative or disclose the gap. Stop diagnostic checks when
-   further results cannot change the causal or fix decision; this does not replace
-   the regression and recovery verification in step 5.
+   failing case when feasible; bisect inputs, paths or changes when informative.
+   Skip a reproduction already known to omit the incident's causal conditions;
+   choose a faithful alternative or disclose the gap. Stop diagnostic checks when
+   further results cannot change the causal or fix decision; this does not replace
+   the regression and recovery verification in step 5.
    If the incident is intermittent or inaccessible, use captured traces and
    targeted diagnostic observations instead of declaring investigation impossible.
    Add minimal instrumentation when evidence is insufficient. Prefer read-only

package/skills/agentic-sdlc-skill/elicitation.md

@@ -126,8 +126,8 @@ Never legal:
 
 What questions are FOR — what the user uniquely owns: the benefit, priorities
 between conflicting goods, non-goals, acceptance, and the approvals doctrine
-reserves to them (Vision promotion and amendment, scope changes, proposal
-acceptance, merge decisions). Facts about intent come from the user; facts about
+reserves to them (Vision promotion and amendment, design approval at L3, scope
+changes, proposal acceptance, merge decisions). Facts about intent come from the user; facts about
 the system come from search.
 
 **Precedence, because both halves can fire at once:** this paragraph wins over

package/skills/agentic-sdlc-skill/review.md

@@ -198,6 +198,34 @@ is a belief: the row would say a gate ran and never whether it could do its job,
 the correlation with `revise_rounds` and `findings_real` — the only evidence the
 policy pays — could not be drawn.
 
+**The owner approves the design before the work starts (L3).** The reviewer judges
+whether the design holds and serves the Vision; only the owner can say whether it is
+what they meant beyond what the Vision wrote, and an intent error costs least before
+the work exists. So the final design PASS — final once any scoped re-review it owed
+has passed (§Review-driven corrections) — does not start the work: the agent
+presents the design and asks the owner whether to proceed, in the form
+`elicitation.md` §The form of a question gives a reserved approval. The presentation
+is a short summary — what the change does (the Functional Spec, or the lens's
+equivalent), for whom and through which surfaces (use cases, contract), what it
+touches (Impact), the threats and their mitigations, the review's verdict with any
+open findings — and the path of the full design. At the round cap, the hand-over the
+cap prescribes, followed by this one question, takes the place of the form, and the
+owner's answer settles both. An approval is recorded verbatim in the request record
+under a label that begins `design approved`; a no or a correction takes its own
+label, and the design goes back — where the revision changes what the review judged,
+moment 1 runs again on that part first (the delta rule above). Only after the
+approval does the ANALYSIS go `PLANNED` → `IN_PROGRESS` and the work start: code,
+drafting or production, by lens. An instruction given before the design was shown
+("carry on", "do the whole unit") does not approve it. Where a lens's own phases
+already have the owner approve the design — the marketing lens's strategy USER GATE
+— that gate is this approval, never a second question, and the lens's own unattended
+path applies. Otherwise, unattended, the unit is `BLOCKED on the user`
+(`elicitation.md` Unattended path), never approved by assumption; a late arrival
+(moment 1b) asks before any further work. Hybrid: the owner's approval of the
+`E-ISP`/`E-TDD` proposal in devPNT, under devPNT's own authorization rules, is this
+approval. In Standalone, `validate` notes an L3 ANALYSIS in implementation, started
+on or after 2026-10-31, whose request record holds no `design approved` entry.
+
 **One schema for both modes**, meaning one required CORE plus each mode's own
 **mode-specific** realization columns. The core is what both modes actually share: `date`, `doc_key`,
 `tier`, `model`, `findings_raised`, `findings_real`, `verdict`, `revise_rounds`.

package/skills/agentic-sdlc-skill/scripts/sdlc_core.py

@@ -100,6 +100,10 @@ CHRONOLOGY_EPOCH = "2026-10-18"
 # filled '## Guide check'. The day AFTER the rule was written, so the analyses
 # opened that day by parallel units (which never saw the template) stay quiet.
 GUIDE_CHECK_EPOCH = "2026-10-24"
+# Owner design approval (F-087): an L3 started on/after this date owes a request-
+# record entry labelled `design approved` before implementation. The day AFTER the
+# rule was written, like GUIDE_CHECK_EPOCH.
+DESIGN_APPROVAL_EPOCH = "2026-10-31"
 NEXT_MAX_CHARS = 240        # this repository's longest `next:` was 214 at the epoch
 ID_SCAN_MAX_REFS = 300      # A3 is skipped above it (one advisory says so, T9)
 ID_SCAN_REFS_PER_CALL = 50  # keeps one git command line far below 32k chars
@@ -1479,17 +1483,50 @@ def id_advisories(root):
     return out
 
 
-def design_review_due(meta):
-    """True when an L3 ANALYSIS owes a design-review row (review.md moment 1):
-    implementation has started or finished, and it began on/after the gate
-    shipped. PLANNED is exempt -- the review is due at the END of Phase 3, so an
-    analysis still being drafted is not late."""
+def _l3_in_work_since(meta, epoch):
+    """True when an L3 ANALYSIS is in implementation or done and began on/after
+    `epoch` (an ISO date string)."""
     if meta.get("level", "").upper() != "L3":
         return False
     if meta.get("status") not in ("IN_PROGRESS", "COMPLETED"):
         return False
     started = parse_iso((meta.get("start_date") or "").strip().strip("'\""))
-    return started is not None and started >= parse_iso(DESIGN_REVIEW_EPOCH)
+    return started is not None and started >= parse_iso(epoch)
+
+
+def design_review_due(meta):
+    """True when an L3 ANALYSIS owes a design-review row (review.md moment 1):
+    implementation has started or finished, and it began on/after the gate
+    shipped. PLANNED is exempt -- the review is due at the END of Phase 3, so an
+    analysis still being drafted is not late."""
+    return _l3_in_work_since(meta, DESIGN_REVIEW_EPOCH)
+
+
+def design_approval_due(meta):
+    """True when an L3 ANALYSIS owes the owner's design approval (review.md
+    section When a review is due): in implementation or done, begun on/after
+    DESIGN_APPROVAL_EPOCH. PLANNED is exempt -- the question comes after the PASS."""
+    return _l3_in_work_since(meta, DESIGN_APPROVAL_EPOCH)
+
+
+def requests_naming(root, analysis_name):
+    """The request records whose `analysis:` field names this ANALYSIS file."""
+    req = ai_path(root, "audit", "requests")
+    if not req.is_dir():
+        return []
+    return [r for r in sorted(req.glob("REQUEST_*.md"))
+            if str(load_frontmatter(read_text(r).splitlines()).get("analysis") or "")
+            .strip().strip("'\"`") == analysis_name]
+
+
+def design_approval_logged(root, analysis_name):
+    """True when a request record naming this ANALYSIS has an entry whose LABEL
+    begins `design approved` (case-insensitive). Only the label is read, never
+    the quoted words: a quotation is data, and a 'design approved?' inside a
+    refusal approves nothing."""
+    return any(label.lower().startswith("design approved")
+               for r in requests_naming(root, analysis_name)
+               for _, _, label, _ in request_entries(read_text(r))[0])
 
 
 def review_logged(root, analysis_name):
@@ -1801,6 +1838,12 @@ def cmd_validate(root, strict=False, hybrid=False):
             advisories.append(f"{rel}: L3 in implementation with no design-review row in "
                               f"{review_log_rel()} -- the design was reviewed by nobody but its "
                               "author before code was written (review.md moment 1)")
+        if (not hybrid and design_approval_due(meta)
+                and not design_approval_logged(root, p.name)):
+            advisories.append(f"{rel}: L3 in implementation with no design approval in its "
+                              "request record (no entry whose label begins 'design approved') -- the "
+                              "owner never said the design was what they meant before the "
+                              "work started (review.md, When a review is due)")
         if ledger_due(meta) and not has_ledger_heading(text):
             advisories.append(f"{rel}: L3 without '## Capability Ledger' -- the architect pass "
                               "left no record (architect.md); run it before the Impact")
@@ -2562,7 +2605,8 @@ def cmd_gate(args):
     sys.stderr.write(
         f"[sdlc gate] '{rel}' is on a protected path but no ANALYSIS_*.md is IN_PROGRESS. "
         "If your analysis already exists, set its frontmatter to 'status: IN_PROGRESS' "
-        "(that flip is what opens the gate); otherwise write it first (Phase 3).\n")
+        "(that flip is what opens the gate; at L3, only after the owner's design approval, "
+        "review.md); otherwise write it first (Phase 3).\n")
     return 2
 
 
@@ -3063,13 +3107,9 @@ def _unit_documents(root, p):
     reading or writing any of them is working on the unit."""
     slug = p.stem[len("ANALYSIS_"):]
     docs = {p, ai_path(root, "audit", f"HANDOFF_{slug}.md")}
-    req = ai_path(root, "audit", "requests")
-    if req.is_dir():
-        for r in req.glob("REQUEST_*.md"):
-            meta = load_frontmatter(read_text(r).splitlines())
-            if str(meta.get("analysis") or "").strip().strip("'\"`") == p.name:
-                docs.add(r)
-                docs.add(ai_path(root, "audit", f"HANDOFF_{r.stem[len('REQUEST_'):]}.md"))
+    for r in requests_naming(root, p.name):
+        docs.add(r)
+        docs.add(ai_path(root, "audit", f"HANDOFF_{r.stem[len('REQUEST_'):]}.md"))
     return {_norm_rel(d.resolve().as_posix()) for d in docs}
 
 

package/skills/agentic-sdlc-skill/templates.md

@@ -377,7 +377,7 @@ checks: [marketing.funnel]      # optional — extra portable checks to run on t
      the responsibility-level flow that deliver them; it NAMES the components in
      the flow, never their mechanism or file-level design (that is the Impact's
      vocabulary). After
-     design approval, changing a contracted surface, flow or feedback is a scope
+     the owner's design approval (`review.md`), changing a contracted surface, flow or feedback is a scope
      change the USER approves: the solution may propose it, never enact it
      silently. Every contracted flow is covered by ## Test Strategy. -->
 
@@ -549,6 +549,9 @@ Context (agent): "the question it answered, quoted"
   entered only as `[NOT VERBATIM — from <source>]`, never as a quote.
 - **Unattended**: R1 quotes the trigger that started the unit, labelled as such.
   Declared assumptions are not owner statements and never enter the record.
+- **Design approval** (L3): the owner's approval of the design is an entry whose
+  label begins `design approved`; a no or a correction takes its own label
+  (`review.md` §When a review is due).
 - **Hybrid**: always on the filesystem; governed artifacts cite entries too; an
   approval given in devPNT is named by its proposal, not quoted.