@antoneeo/agentic-sdlc-skill 1.24.0 → 1.26.0

package/CHANGELOG.md

@@ -2,6 +2,66 @@
 
 Tutte le modifiche significative a questa skill saranno documentate in questo file.
 
+## [1.26.0 / kb 1.4.6 / mkt 0.4.6] - 2026-08-06
+
+### Added
+- **Execution Integrity — Tranche A (F-034).** Three observed/irreversible gaps close as
+  wording in existing owners, from a firsthand comparative study of Superpowers 6.2.0 (MIT;
+  concepts reimplemented, no text copied, no dependency) gated by the standing weight
+  criterion: (1) **claim-to-evidence** — every completion claim binds to a proof run AFTER
+  the final relevant edit; a narrower check never supports a broader claim; delegated work is
+  verified on the diff, never on the subagent's report; unavailable proof is reported, never
+  claimed (observed failure: a closure artifact claimed "check clean" while the gate was NOT
+  CLEAN — REVIEW_LOG F-033). (2) **Scoped re-review of review-driven corrections**
+  (`review.md`, shared spine — ACTIVE in kb/mkt too): a fix is unreviewed work; per-finding
+  verdicts ADDRESSED/NOT ADDRESSED/CONTESTED, correction-only scope, new breakage in the fix
+  joins the findings, two rounds are the norm inside the existing cap of 3, one logical
+  review = one REVIEW_LOG row. (3) **Destructive guards** — integration is the user's choice;
+  discard only on explicit request naming branch/commits/worktree; no unauthorized
+  force-push; no foreign-worktree cleanup; project guides own the specific commands.
+- **Enforcement-writing technique** on the touched rules: a triage rationalization table
+  (`Excuse | Reality`) in Rule Zero and red-flag stop-words in the verification rule — the
+  study's key finding was that Superpowers' asset is HOW it writes rules (pre-refuting the
+  escape thought), not any mechanism.
+- **Reviewer output honesty:** `CANNOT VERIFY` is a first-class reviewer output (a claim not
+  checkable from the provided inputs is reported, not silently passed); pre-judging findings
+  in a review request ("don't flag X") is forbidden. Companion change in the devPNT reviewer
+  agents ships in that repo.
+  Tranche B (tdd/debugging) rides the next admitted touch of those overlays; Tranche C
+  (dispatch ledger machinery) stays frozen until an observed failure reopens it. Rationale:
+  `ai_docs/architecture/ADR_2026-08-06_execution_integrity_tranche_a.md`.
+
+## [1.25.0 / kb 1.4.5 / mkt 0.4.5] - 2026-08-06
+
+### Added
+- **Functional Spec — the readable WHAT (code lens, F-033).** A conditional `## Functional
+  Spec` ANALYSIS section between the Use Cases and the Interface Contract: the complete
+  observable behavior — rules, cases (normal/edge/error/state-dependent), acceptance
+  criteria — **component-free by construction**, the one object a person reads to answer
+  "is this what we want?" and the AI reads as the behavior contract the design and closure
+  review conform to. Authority split: Use Cases own WHY, the Functional Spec owns WHAT, the
+  Interface Contract owns THROUGH-WHAT (its authority line now cedes behavior semantics),
+  the Impact owns HOW. Fires on behavior change; internal refactor exempt with one line.
+  The shared `review.md` gains the enforcement clause (absence on behavior change,
+  Solution-leakage inside the spec, uncovered cases, acceptance criteria without tests,
+  UC↔FS↔IC coverage — inert in kb/mkt). Rationale + rejected alternatives:
+  `ai_docs/architecture/ADR_2026-08-06_functional_spec_layer.md`; admission: rulings r17.
+- **The strategic pass is ONE search with four open buffers.** SKILL.md §3 now states the
+  owner's model: find how the Actors (defined in the Vision) obtain from the components
+  what the Vision prescribes — risks mitigated in-loop, architecture and patterns
+  respected, quality/maintainability the objective, Poka-Yoke and DRY the selection
+  criteria between hypotheses. Use Cases / Functional Spec / Interface Contract / Threat
+  Model are open buffers — every thought is captured immediately where it belongs; the
+  order UC → FS → IC → TM binds only finalization and reading. Vision divergence halts
+  the pass.
+
+### Changed
+- **Hybrid section updated to post-M47 reality.** The Interface Contract is devPNT's
+  governed `D-IC` (the "lives in the E-ISP" line was stale); the strategy artifacts
+  (`D-UC`/`D-IC`/`P-TM`) are authored as one bundle pass and approved per-document
+  (devPNT doctrine §4.2 owns the procedure); the Functional Spec rides in the `E-ISP`
+  until a governed `D-FS` exists (devPNT-side work).
+
 ## [1.24.0 / kb 1.4.4 / mkt 0.4.4] - 2026-08-05
 
 ### Added

package/gemini-extension.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-sdlc-skill",
-  "version": "1.24.0",
+  "version": "1.26.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.24.0",
+  "version": "1.26.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/skills/agentic-sdlc-skill/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agentic-sdlc
-version: 1.24.0
+version: 1.26.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
@@ -56,6 +56,16 @@ Cross-cutting rules:
 - **Before asking the user anything — any phase, any level — the question must pass the legality test: search first and name the search with its result; name the decision or fact blocked without the answer.** Blocking the work is the exception, not the default. `elicitation.md` §The question discipline owns the rule and is the only place it is stated — read it before you ask, and do not work from a summary of it.
 - The full audit does not start for L1/L2 unless explicitly requested.
 
+Triage rationalizations — the thought on the left is the signal to STOP and re-triage:
+
+| Excuse | Reality |
+|---|---|
+| "Too simple to need the process" | Simple is where unexamined assumptions bite; L1's process IS proportionally simple — use it, don't skip it |
+| "It's just a fix" | A "fix" that delivers a new capability or client is a new feature wearing a fix label — the framing does not set the level, the criteria do |
+| "It's small, so L2" | Size is one criterion of several: one touched contract, security surface or non-obvious design makes it L3 at any size |
+| "I'll reclassify later if it grows" | Later is after the unscoped edits exist; reclassify the moment the bigger impact emerges, not at closure |
+| "The doubt itself is small" | When in doubt, pick the higher level — that rule exists precisely for this thought |
+
 ## Write Triggers
 
 Triage decides IF documentation is due; this table decides WHICH document each event produces, and when. **One event, one destination:** when the trigger fires and the document does not exist, create it; when it exists, update it — never duplicate it. This table is the authoritative write index — the workflow phases carry the surrounding procedure and point here for the trigger.
@@ -218,9 +228,13 @@ Hybrid:
 
 For any L3, run the spec elicitation round in `elicitation.md` BEFORE drafting the analysis (skip path inside — one-line note when the spec is already complete).
 
+**The strategic pass is ONE search with four open buffers (L3).** The task: find how the Actors (defined in the Vision) obtain from the components what the Vision prescribes — mitigating or eliminating risks along the way, respecting the existing architecture and its patterns, optimizing for quality and maintainability. Actors and Vision are fixed; components, interfaces and flows are the degrees of freedom — modified only as declared changes, never accidental redesign — and Poka-Yoke and DRY govern every choice: the engineering principles are the selection criteria BETWEEN hypotheses during the search, not a checklist after it. The loop is free — hypothesis → verification against the two anchors (the real system, the Vision) → decision → next hypothesis — and every thought is captured immediately in the section it belongs to: Use Cases, Functional Spec, Interface Contract and Security & Threat Model are four open buffers, not four phases (a risk is written into the threat model the moment it is thought; one later eliminated by a design choice disappears at finalization or stays as "eliminated by construction: [the choice]"). The order UC → FS → IC → TM governs only finalization and reading: at convergence, walk the four in dependency order for coherence — each behavior serves a need, each flow realizes a behavior, each threat targets a real surface. The loop is free WITHIN the Vision frame: a hypothesis adding an unauthorized capability or touching a Non-Goal halts the pass and goes to the user.
+
 **Use cases are grounded before anything builds on them (two checks, nothing else).** The use-cases the elicitation produces pass a tight gate whose owning definition is the `templates.md` `## Use Cases / User Needs` comment — cite it, never restate it: every product name they use resolves to EXISTS (the product's own term for a real thing) / NEW (declared) / METAPHOR (never an interface element), and every use-case traces to a Vision benefit. A name in no bucket invents system reality the project does not have; a use-case tracing to no benefit is drift. It is the top-of-funnel twin of the blast-radius duty below — ground the reasoning artifact in what the system IS and the vision WANTS before the contract, the Ledger and the Impact all inherit it. The author self-applies at drafting; then the independent design review (`review.md` moment 1) verifies the two checks before the owner's own review — it precedes it, never replaces it.
 
-**Interface Contract before the Impact (conditional).** When the change creates or modifies an actor-facing surface — the trigger's owning definition lives in the `templates.md` section comment; cite it, never restate it — the ANALYSIS carries a `## Interface Contract`: the observable behavior the actors get, per use case — the responsibility-level flow each action triggers, naming the components it traverses, and the universal feedback that returns — built by first reading the surfaces and interaction idioms already in place and reusing them by default (a new idiom is a declared decision, never an unmarked invention). It binds observable behavior **and the responsibility-level flow** — it names the components in the flow, never their mechanism; **mechanism and files stay the Impact's vocabulary**. Drafting interleaves with the architect pass below (the contract's feasibility notes are early capability probes), but finalization is ordered: contract and Ledger are both complete before the Impact is drafted. After design approval, a contracted path changes only as a user-approved scope change — the solution proposes, never silently enacts. Trigger not fired → one line in the section stating why. Why it exists: without it the interaction is invented at implementation time, UX is emergent instead of designed, and the review's "actor UX fit" check has no object.
+**Functional Spec before the Interface Contract (conditional).** When the change adds or alters observable behavior — the trigger's owning definition lives in the `templates.md` `## Functional Spec` section comment; cite it, never restate it — the ANALYSIS carries a `## Functional Spec`: the complete observable WHAT (rules, cases, acceptance criteria), component-free by construction, the one object a person reads to answer "is this what we want?" and the AI reads as the behavior contract the design and the closure review conform to. Without it the WHAT is validated implicitly across four documents — which is where review rounds go to argue about what was meant. Trigger not fired → one line in the section stating why.
+
+**Interface Contract before the Impact (conditional).** When the change creates or modifies an actor-facing surface — the trigger's owning definition lives in the `templates.md` section comment; cite it, never restate it — the ANALYSIS carries a `## Interface Contract`: the observable interaction the actors get, per use case — the responsibility-level flow each action triggers, naming the components it traverses, and the universal feedback that returns — built by first reading the surfaces and interaction idioms already in place and reusing them by default (a new idiom is a declared decision, never an unmarked invention). It binds the observable interaction **and the responsibility-level flow** (behavior semantics are the Functional Spec's) — it names the components in the flow, never their mechanism; **mechanism and files stay the Impact's vocabulary**. Drafting interleaves with the architect pass below (the contract's feasibility notes are early capability probes), but finalization is ordered: contract and Ledger are both complete before the Impact is drafted. After design approval, a contracted path changes only as a user-approved scope change — the solution proposes, never silently enacts. Trigger not fired → one line in the section stating why. Why it exists: without it the interaction is invented at implementation time, UX is emergent instead of designed, and the review's "actor UX fit" check has no object.
 
 **Architect before you list files.** Once the spec is known and BEFORE drafting the Impact, run the architect pass in `architect.md`: state what the feature requires the system to be able to DO (capabilities — verbs over domain nouns, no files), rule each one against the platform — **EXISTS** (name the component and where it lives) / **INADEQUATE** (name the gap) / **MISSING** (say what you searched) — and design what is missing as a component with **its own contract, in its own vocabulary**, of which this feature is one consumer. The output goes where that mode keeps designs — Standalone: the ANALYSIS `## Capability Ledger`; Hybrid: the `E-ISP`, above its Impacted Components map (`architect.md`; never a second copy in `ai_docs/`) — and it feeds the Impact. Note the coverage asymmetry: the validator backstop reads Standalone ANALYSIS files only, so in Hybrid the sole check that the pass ran is `review.md`'s ledger clause — which is why that clause fires on a MISSING ledger and not only on the rows of one that is present. Why it is its own step: a feature is not a unit of construction, and an agent that skips it builds the missing capability inside the feature's code path, where no component owns it and the next feature rebuilds it differently. The pass is a question, not a form — when every capability plainly exists, one line answers it.
 
@@ -229,7 +243,7 @@ For any L3, run the spec elicitation round in `elicitation.md` BEFORE drafting t
 Standalone L3:
 - Before creating a new `ANALYSIS_[feature].md`, search `ai_docs/solutions/` with glob/grep for an existing analysis on the same topic: if there is one, update it instead of duplicating it.
 - Create or update `ai_docs/solutions/ANALYSIS_[feature].md`.
-- Minimum sections: Objective, Feature Vision (or Vision Alignment), Use Cases / User Needs, Interface Contract (conditional — the paragraph above), Capability Ledger, Impact, Security and Threat Model, Action Plan, Test Strategy, Diary/Current State. (`review.md` makes an uncovered use-case a finding, so an ANALYSIS without that section fails its own closure review.)
+- Minimum sections: Objective, Feature Vision (or Vision Alignment), Use Cases / User Needs, Functional Spec (conditional — behavior change, the paragraph above), Interface Contract (conditional — the paragraph above), Capability Ledger, Impact, Security and Threat Model, Action Plan, Test Strategy, Diary/Current State. (`review.md` makes an uncovered use-case a finding, so an ANALYSIS without that section fails its own closure review.)
 - 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.
 
@@ -238,7 +252,8 @@ Standalone L3:
 Hybrid L3:
 - Restore the Master Plan, Action Plan and linked documents.
 - Use devPNT for plans and governed artifacts.
-- The Interface Contract lives in the `E-ISP`, above its Impacted Components map (like the Capability Ledger — never a second copy in `ai_docs/`); a dedicated governed artifact for it is devPNT-side work, not this skill's. Its place in the governed sequence is between `D-UC` and `P-TM`: the use cases say what the person needs, the contract says through which surface, the threat model then assesses those surfaces — the `E-ISP` inherits the interaction, it never generates it.
+- The Interface Contract is devPNT's governed `D-IC`, between `D-UC` and `P-TM`: the use cases say what the person needs, the contract says through which surface, the threat model then assesses those surfaces — the `E-ISP` inherits the interaction, it never generates it. The strategy artifacts (`D-UC`/`D-IC`/`P-TM`) are authored as ONE bundle pass and approved per-document in one sitting (one reasoning act, three projections — devPNT doctrine §4.2 owns the procedure).
+- The Functional Spec has no governed artifact yet: it rides in the `E-ISP`, above its Impacted Components map (like the Capability Ledger — never a second copy in `ai_docs/`); a dedicated `D-FS` is devPNT-side work, not this skill's.
 - Use `ai_docs/solutions/SHADOW_[doc_key]_vX.Y.md` only as a readable shadow when needed; on divergence devPNT wins.
 
 ### 4. Development and Testing
@@ -257,6 +272,7 @@ Hybrid L3:
 ### 5. Closure
 
 - Run the relevant tests/lint/smoke checks.
+- **Claim-to-evidence (fires at EVERY completion claim, any phase, any level).** Before stating or implying that anything passes, works, is fixed, is clean or is complete: name the claim, run the proof that establishes *that* claim **after the final relevant edit**, read the full result, and report the actual status with the evidence. Freshness: a check run before a later relevant change proves nothing about the current tree. Breadth: a narrower check never supports a broader claim — targeted tests ≠ full suite; lint ≠ build; "tests pass" ≠ "requirements complete" (that claim maps to the Functional Spec acceptance criteria where the artifact carries them; "gate clean" maps to a fresh gate run reporting clean). **Delegated work is verified on the diff/files, never on the agent's report** — "the subagent said success" is a claim, not evidence. If the environment cannot run the proof, say so and give the alternative evidence — never claim the unavailable result. Red flags that mean STOP and run the proof: "should", "probably", "seems to", "still passes", "just this once", any satisfaction expressed before verification.
 - For the review itself follow `review.md` (requesting and receiving findings) — the single definition, intended for reuse by the Hybrid review gates (devPNT-side wiring out of this unit's scope).
 - Verify alignment with the local Vision or the devPNT M-VISION.
 - If the work was governed by user-provided indications and is reusable, **PROPOSE distilling a guide** (proactive trigger, `guides.md` §1) — a proposal for the user, never a silent write, never from model knowledge.
@@ -274,6 +290,7 @@ Hybrid L3:
 - In Standalone, if the project adopts `sdlc_check.py`, run `python <skill_dir>/scripts/sdlc_check.py check --root <project_root>` or the equivalent local copy.
 - Updated documents must travel in the same commit/PR as the code they describe.
 - **Branch/worktree hygiene**: an L3 ran on its own branch (Phase 4) — close it with an explicit merge decision (merge, keep open, or discard) and clean up the branch/worktree; never leave orphan branches. In Hybrid, the running devPNT server locks `.devpnt/*.db`, so the merge is done from a separate git worktree or via a ref-only push, never an in-place branch switch in the primary worktree.
+- **Destructive guards (integration is the user's; destruction is explicit).** The integration choice — merge, push/PR, keep — belongs to the user. Discard happens ONLY on the user's explicit request, and the confirmation names exactly what dies: the branch, its commits, the worktree path. Never force-push without explicit authorization; a rejected push means the remote moved — investigate, don't force. Never clean up a worktree this workflow did not create — the host or another workflow owns it. Repository-specific release/finish commands are the project guide layer's (the router in `## Operative Guides`): the skill owns this discipline, the matched `GUIDE_*.md` owns the commands — cite it, never restate it.
 
 ## ai_docs documents: two indexes + lifecycle
 

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

@@ -99,6 +99,12 @@ conversation instead of reviewing the change itself. Say which finding
 classes you want covered (correctness, security, conformance to the design,
 test coverage) if the default scope is not obvious.
 
+Never pre-judge findings for the reviewer: do not instruct them to ignore or
+not flag a specific issue ("don't treat X as a defect", "at most minor"). If
+you believe a finding would be a false positive, let the reviewer raise it and
+resolve it with evidence in §Receiving — pre-judging is usually the requester
+sparing themselves a round.
+
 ## Receiving
 
 **MUST answer findings one by one — fix, or justify with evidence; why:
@@ -111,6 +117,22 @@ resolve a disagreement by rewording the finding until it goes away. When the
 project keeps a `REVIEW_LOG` (or equivalent), log the outcome of each
 finding there.
 
+### Review-driven corrections (scoped re-review)
+
+A fix made in response to a finding is new, unreviewed work — stopping after
+"I fixed it" ships the one version nobody reviewed. Every review-driven change
+therefore gets a **scoped re-review** before the review can PASS: hand the
+re-reviewer the original findings and ONLY the correction (the fix diff/range
+for code, the amended sections for a document), and require a per-finding
+verdict — `ADDRESSED`, `NOT ADDRESSED`, or `CONTESTED` with evidence. The
+re-review also checks the correction itself for new blocker-level
+breakage — and nothing else: out-of-scope observations become separately
+recorded findings, never an extension of the loop. Expect two rounds as the
+norm, not the exception — round 1 finds, round 2 verifies the fixes — inside
+the same cap of 3 (§When a review is due). One logical review stays ONE
+REVIEW_LOG row, its rounds narrated inside; a scoped re-review is a round,
+not a new review.
+
 ## Reviewing
 
 When you are the reviewer:
@@ -123,6 +145,12 @@ When you are the reviewer:
   (see `## Requesting`).
 - Cite evidence as `file:line` for every finding — a finding without a
   location is not actionable.
+- **Say what you could NOT verify.** When a claim in the artifact cannot be
+  verified from the inputs you were given (it lives in unchanged code, another
+  document, or an environment you cannot reach), report it as a
+  `CANNOT VERIFY` item instead of silently passing it — the requester holds
+  the context to resolve it, and must do so before closing. A PASS that
+  silently skipped unverifiable claims is review theater.
 - Keep severity honest: do not inflate a style preference to a blocker, and
   do not soften a real correctness or security issue to a nit.
 - No praise padding. A review reports problems and their fixes, not a
@@ -159,6 +187,21 @@ When you are the reviewer:
   review, never replacing it; coverage of each use-case by the Impact, and the
   Actor it serves, stay the conformance-statement clause above. A lens whose
   template defines no `## Use Cases` section never fires this clause.
+- **Functional Spec (same reviews; fires only in the lens whose template defines
+  the section — the code lens today).** When the change adds or alters observable
+  behavior (the trigger's owning definition is the code lens's `templates.md`
+  `## Functional Spec` section comment — cite it, never restate it), **an L3
+  artifact carrying NO `## Functional Spec` is itself a finding** — absence is
+  what a skipped spec looks like, not a reason to skip the check. When the spec
+  is there, these findings live here: **a component, file or mechanism named
+  inside it** — the spec is component-free by construction; that is
+  Solution-leakage (component names belong to the Interface Contract, mechanism
+  to the Impact); a behavior whose edge, error or state-dependent cases are
+  absent with no stated reason; an acceptance criterion no `## Test Strategy`
+  item covers; a behavior serving no use case, or a use case whose behavior the
+  spec leaves unstated; and an Interface Contract flow realizing a behavior the
+  spec does not state. A lens whose template defines no such section (knowledge,
+  marketing) never fires this clause.
 - **Capability Ledger (same reviews).** **An L3 impact/solution analysis or design
   that carries NO Capability Ledger is itself a finding** — the lens's capability
   pass (`architect.md` in the code lens, `taxonomy.md` in the knowledge lens) left

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

@@ -266,6 +266,32 @@ checks: [marketing.funnel]      # optional — extra portable checks to run on t
      drafting is grounded in BOTH anchors first — the Vision (benefit + actors)
      and the real system (summaries / existing features / source). -->
 
+## Functional Spec
+<!-- [conditional] Fires when the change ADDS or ALTERS observable behavior —
+     what the system does, decides or shows. Not fired (pure internal refactor,
+     no behavior change) → one line stating why. This comment is the OWNING
+     definition of the section; SKILL.md and review.md cite it, never restate it.
+     THE validation object: the complete observable WHAT, readable by a person
+     ("is this what we want?") and by the AI (the contract the design and the
+     closure review conform to). Component-free by construction: it names NO
+     components, files or mechanisms — behavior only, in the actor's and the
+     domain's vocabulary. (Product names obey the Use Cases grounding buckets:
+     EXISTS with the product's own term / NEW declared / METAPHOR never an
+     interface element.)
+     Content, per use case whose behavior the change touches (a question, not a form):
+     1. Behavior — the rules and decisions, stated as observable outcomes
+        ("a request with an expired token is rejected and the actor is told the
+        session expired; no partial state persists").
+     2. Cases — normal, edge, error and state-dependent behavior: empty, invalid,
+        concurrent, limits, repeated. Each case states what the actor observes.
+     3. Acceptance criteria — the "done when": checkable statements
+        (given/when/then form welcome), each covered by ## Test Strategy.
+     Authority split: Use Cases own WHY (the need), this section owns WHAT
+     (behavior semantics), the Interface Contract owns THROUGH-WHAT (surfaces,
+     flows, feedback), the Impact owns HOW. A component or mechanism named here
+     is Solution-leakage — move it to the Interface Contract (component names)
+     or the Impact (mechanism). -->
+
 ## Interface Contract
 <!-- [conditional] Fires when the change creates or modifies a surface through
      which an actor **acts on or perceives** the system — GUI view, CLI
@@ -297,9 +323,11 @@ checks: [marketing.funnel]      # optional — extra portable checks to run on t
         feed the threat model (## Security) and the Impact.
      Reuse the as-is idioms by default; a NEW idiom where an existing one covers
      the job is a declared decision with its reason — never an unmarked invention.
-     Authority split: the contract binds observable behavior AND the
-     responsibility-level flow — it NAMES the components in the flow, never their
-     mechanism or file-level design (that is the Impact's vocabulary). After
+     Authority split: behavior semantics (rules, cases, outcomes) are
+     ## Functional Spec's — this contract binds the observable interaction AND
+     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
      change the USER approves: the solution may propose it, never enact it
      silently. Every contracted flow is covered by ## Test Strategy. -->