opencode-skills-collection 4.0.42 → 4.0.43

package/bundled-skills/lore/scripts/list_entries.py

@@ -19,13 +19,15 @@ entry with these fields:
     text            entry body, with tags stripped
     tags            dict of tag name -> value, e.g. {"added": "2026-07-09", "verified": "2026-07-15"}
     last_verified   value of #verified tag, or None
+    replaced_by     value of #superseded-by tag (replacement entry ID), or None
 
 Used by:
-    - query / audit / compress workflows (pre-step enumeration)
+    - query / audit / compress / history workflows (pre-step enumeration)
     - find_duplicates.py
     - find_stale.py
 """
 import json
+import os
 import re
 import sys
 from pathlib import Path
@@ -91,10 +93,40 @@ def parse_entry(line: str):
     layer, date, h, rest = m.group(1), m.group(2), m.group(3), m.group(4)
     eid = f"{layer}-{date}-{h}"
 
-    # Extract #tag:value pairs
-    tag_re = re.compile(r"#(added|verified|stale|archived):(\S+)")
-    tags = {name: val for name, val in tag_re.findall(rest)}
+    # Extract #tag:value pairs.
+    # #superseded-by:<id> is special: its value is an entry ID, not a date,
+    # so we keep it on a separate `replaced_by` field rather than in `tags`.
+    ENTRY_ID = r"[A-Z]+-\d{4}-\d{2}-\d{2}-[a-f0-9]{4}"
+    tag_re = re.compile(
+        r"#(added|verified|stale):(\S+)"
+        r"|#superseded-by:(" + ENTRY_ID + r")"
+    )
+    tags = {}
+    replaced_by = None
+    for m in tag_re.finditer(rest):
+        if m.group(1):
+            tags[m.group(1)] = m.group(2)
+        elif m.group(3):
+            if replaced_by is None:
+                replaced_by = m.group(3)
+            else:
+                print(
+                    f"[WARN] entry {eid} carries multiple #superseded-by "
+                    "tags; keeping the first only.",
+                    file=sys.stderr,
+                )
     text = tag_re.sub("", rest).strip()
+    # Any #superseded-by still present after the valid-tag strip is
+    # malformed (value is not LAYER-YYYY-MM-DD-xxxx). Warn instead of
+    # dropping it silently: the entry stays intact in the file, but the
+    # chain cannot be resolved and replaced_by stays None.
+    for m in re.finditer(r"#superseded-by:(\S+)", text):
+        print(
+            f"[WARN] entry {eid} has a malformed #superseded-by value "
+            f"'{m.group(1)}' (expected LAYER-YYYY-MM-DD-xxxx); chain not "
+            "resolved.",
+            file=sys.stderr,
+        )
 
     return {
         "id": eid,
@@ -105,6 +137,7 @@ def parse_entry(line: str):
         "text": text,
         "tags": tags,
         "last_verified": tags.get("verified"),
+        "replaced_by": replaced_by,
     }
 
 
@@ -123,14 +156,43 @@ def collect_entries(root: Path):
             layer_file = md_file.stem
             try:
                 with open(md_file, encoding="utf-8") as f:
-                    for line in f:
-                        e = parse_entry(line)
-                        if e is None:
-                            continue
-                        e["scope"] = scope
-                        e["layer_file"] = layer_file
-                        e["file"] = str(md_file.relative_to(root))
-                        entries.append(e)
+                    lines = f.readlines()
+                if lines:
+                    # Strip a UTF-8 BOM (Windows editors / PowerShell
+                    # Set-Content add one); otherwise the first entry of
+                    # the file would fail to parse and be silently skipped.
+                    lines[0] = lines[0].lstrip("\ufeff")
+                i = 0
+                while i < len(lines):
+                    # Join wrapped continuation lines into one logical
+                    # bullet before parsing. A continuation is a non-blank
+                    # line starting with 2+ spaces (or a tab) that is not
+                    # itself a new entry bullet. This matches the documented
+                    # "2 lines or fewer" bullet format without silently
+                    # truncating the entry text.
+                    joined = lines[i].rstrip("\n")
+                    j = i + 1
+                    while j < len(lines):
+                        nxt = lines[j].rstrip("\n")
+                        if nxt.strip() == "":
+                            break
+                        if not re.match(r"^\s{2,}", nxt):
+                            break
+                        if re.match(r"^\s*-\s*\[", nxt):
+                            break
+                        joined += " " + nxt.strip()
+                        j += 1
+                    e = parse_entry(joined)
+                    if e is None:
+                        i += 1
+                        continue
+                    e["scope"] = scope
+                    e["layer_file"] = layer_file
+                    e["file"] = str(md_file.relative_to(root)).replace(
+                        os.sep, "/"
+                    )
+                    entries.append(e)
+                    i = j
             except OSError as exc:
                 print(f"warning: cannot read {md_file}: {exc}", file=sys.stderr)
     return entries
@@ -138,6 +200,10 @@ def collect_entries(root: Path):
 
 def main():
     args = sys.argv[1:]
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")
+    except AttributeError:  # Python < 3.7
+        pass
 
     scope_filter = None
     layer_filter = None
@@ -176,7 +242,10 @@ def main():
             f" [verified:{e['last_verified']}]" if e["last_verified"] else ""
         )
         stale = " [STALE]" if "stale" in e["tags"] else ""
-        print(f"[{e['file']}] {e['id']} {e['text']}{verified}{stale}")
+        chain = (
+            f" -> {e['replaced_by']}" if e.get("replaced_by") else ""
+        )
+        print(f"[{e['file']}] {e['id']} {e['text']}{verified}{stale}{chain}")
 
 
 if __name__ == "__main__":

package/bundled-skills/poka-yoke/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: poka-yoke
+description: "Mistake-proof code, config and process: make the wrong action impossible or self-announcing rather than documented."
+category: development
+risk: safe
+source: rainmanjam/poka-yoke
+source_repo: rainmanjam/poka-yoke
+source_type: community
+date_added: "2026-08-25"
+author: rainmanjam
+tags: [mistake-proofing, code-review, api-design, guardrails, reliability]
+tools: [claude, cursor, codex]
+license: "MIT"
+license_source: "https://github.com/rainmanjam/poka-yoke/blob/v0.1.2/LICENSE"
+---
+
+# Poka-Yoke: Mistake-Proofing for Software
+
+Shigeo Shingo's insight, from the Toyota Production System: **people will always make
+mistakes; that is not the problem worth solving. The problem is letting a mistake become a
+defect.** So you stop trying to make humans more careful and start redesigning the work so
+the mistake either cannot physically happen or announces itself immediately.
+
+A poka-yoke ("poh-kah yoh-kay", ポカヨケ) is a *device*: a jig, a shape, a counter: not
+an instruction. In software: a type, a constraint, a hook, a schema, a state machine. The
+single most important consequence:
+
+> **A comment, a docstring, a wiki page, a code review checklist, or a line in CLAUDE.md
+> saying "don't do X" is not a poka-yoke.** It is training. Training degrades. A device
+> does not. If your proposed fix relies on someone remembering something, keep going.
+
+## When to Use This Skill
+
+- Use when the user says "poka-yoke this", "mistake-proof it", or "make this harder to get wrong".
+- Use when designing an interface, schema or state machine and the ask is "make invalid states unrepresentable" or "so callers cannot screw it up".
+- Use when auditing existing code for footguns: "what could bite us here", "what is easy to misuse".
+- Use after an incident, when the fix must close the class rather than the case: "make sure this never happens again", "this is the third time".
+- Especially for money, auth, permissions, deletion, migrations and pipelines, where failure is silent.
+
+## The two axes
+
+Every real poka-yoke answers two questions. Use both when you classify a hazard or propose a
+device. They are the difference between this method and generic code review.
+
+### Axis 1, Regulatory function: what happens when the mistake occurs?
+
+This is a strict preference ladder. Always reach for the highest rung you can afford.
+
+| Rung | Name | What it does | Software examples |
+|---|---|---|---|
+| **1** | **Control** | The mistake is **impossible**. The work cannot proceed. | Type won't compile · `NOT NULL` / `CHECK` / unique constraint · required function argument · private constructor + smart constructor · PreToolUse hook returns deny · protected branch |
+| **2** | **Warning** | The mistake is possible but **announced at the moment it happens**. | Lint error in the editor · failing CI gate · runtime assertion that throws · confirmation prompt naming the exact thing being destroyed |
+| **3** | **Detection** | The mistake ships, and something **finds it afterward**. | Tests · monitoring · alerting · reconciliation job |
+| **0** | *(not a poka-yoke)* | Relies on a human remembering. | Docs · comments · training · "be careful" · review checklists |
+
+Shingo's rule: prefer **control** over **warning**, always, and only settle for warning when
+control is genuinely too expensive, then say *why* out loud. In software the honest reason
+is usually "the language can't express it" or "it would break every existing caller," and
+both are worth stating explicitly so the tradeoff is visible.
+
+### Axis 2, Setting function: how does the device notice?
+
+Shingo's three detection methods map cleanly onto software. These are your **inspection
+lenses**, run all three over any interface and you will find hazards that a general
+code review misses.
+
+| Method | Factory floor | The question to ask code | Software devices |
+|---|---|---|---|
+| **Contact** | The part physically won't seat unless it's the right shape and orientation | **Can the wrong thing fit?** | Distinct types instead of shared primitives · branded/newtype IDs · parse-don't-validate at boundaries · units in the type · discriminated unions instead of bags of optionals |
+| **Fixed-value** | A counter says all 6 screws were fitted | **Can the wrong count or an incomplete set pass?** | Exhaustive `match`/`switch` over an enum · required fields · "all migrations applied" check · row-count guard on a bulk write · checksums · config validated as a whole at boot |
+| **Motion-step** | A sensor confirms step 3 happened before step 4 | **Can the steps happen in the wrong order, or be skipped?** | Typestate · builder that cannot `.build()` until required steps run · state machines with illegal transitions unrepresentable · idempotency keys · RAII / `defer` / context managers · transactions |
+
+### The third principle: inspect at the source
+
+Shingo separated **source inspection** from **informative inspection**, which finds the defect
+only after it exists and comes in two forms. Ranked best first, that is three places you can
+put the device.
+
+1. **Source inspection**: check the *conditions* before the error can occur. Designed in
+   where you can, enforced at runtime where you cannot.
+   The type, the constraint, the signature.
+2. **Self-check** (informative): the work checks itself as it happens. Runtime. Assertions,
+   fail-fast, validation at the boundary.
+3. **Successive check** (informative): the next station checks the previous one. Review, CI,
+   QA.
+
+Push every device as far up this list as it will go. A CI gate that catches a bad migration
+is good; a schema that makes the bad migration unwritable is better and costs less forever.
+
+## How to use this skill
+
+Apply the method directly to the subject in front of you. A Terraform module, a support
+runbook, a spreadsheet everyone edits, a release checklist, a
+prompt template, an onboarding process, a physical workflow: the method works on any of them,
+because Shingo developed it on an assembly line, for people fitting springs into switches, and
+not for software at all.
+
+Applying it directly means four steps, in order:
+
+1. **Name what is being done, and by whom.** A device protects a specific action taken by a
+   specific person or system. "The pipeline" is not an action; "an engineer re-runs the deploy
+   job after it fails halfway" is.
+2. **Run the three lenses** over that action, can the wrong thing fit, can an incomplete or
+   wrong-sized set pass, can the steps happen in the wrong order. Most subjects yield
+   something on at least one.
+3. **For each hazard found, state it as a mistake someone could make**, what happens when they
+   do, whether it is silent, and what exists today to stop it.
+4. **Propose the highest-rung device you can afford**, and say which rung it reaches. If you
+   land on Warning, say what Control would have required and why you did not take it.
+
+Then apply the two rules in *How to talk about this* below: name the mistake rather than the
+mistaken, and never let the answer come out as "be more careful" or "document it". Those are
+rung zero, and the whole method exists because they do not work.
+
+**If the request is bare**, `/poka-yoke` with nothing attached, look at what is actually in
+front of you: the current diff, the file under discussion, the thing the conversation has been
+about. Say what you picked in one line before starting, so it is cheap to redirect you. If
+there is genuinely no subject, ask what they want mistake-proofed rather than guessing.
+
+## How to talk about this
+
+Two habits keep the analysis honest and keep people from getting defensive:
+
+**Name the mistake, not the mistaken.** "This signature lets a caller swap the two IDs" is
+actionable and true. "The developer should have been more careful" is neither. Shingo was
+emphatic that blaming the operator is how organizations avoid fixing the process. Write
+findings about the code's affordances, never about who wrote it.
+
+**Say which rung you achieved, and what stopped you going higher.** A recommendation that
+reads "added a runtime assertion (warning), control would need a newtype, which touches 40
+call sites" gives the reader a real decision. One that reads "added validation" does not.
+
+## Example
+
+Suppose a destructive API accepts `deleteAccount(accountId: string, tenantId: string)`.
+The two identifiers can be swapped, and the call can target an account outside the caller's
+tenant.
+
+1. **Contact lens:** two plain strings have the same shape, so the wrong value fits.
+2. **Motion-step lens:** deletion can run before tenant ownership is established.
+3. **Control device:** replace the strings with distinct validated ID types and expose a
+   deletion operation that accepts only an account loaded through the authenticated tenant.
+4. **Warning fallback:** if compatibility prevents that interface change, reject ownership
+   mismatches at the boundary and require a confirmation that names the exact account. State
+   explicitly that this is weaker than making the invalid call unrepresentable.
+5. **Detection:** retain audit logging and reconciliation for failures the control does not
+   cover; do not present those after-the-fact checks as the poka-yoke itself.
+
+## Applying changes
+
+Propose before you edit. Show the hazard, the proposed device, and the rung it reaches, then
+wait for a go-ahead before changing files: the whole point of this method is that it changes
+the shape of an interface, and that is precisely the kind of change people want to see first.
+Once approved, apply it and record the prevented mistake where future maintainers can verify
+the constraint without mistaking the explanation itself for the device.
+
+The exception is when someone has explicitly asked you to write new code: mistake-proofing
+*is* the code they asked for, so build it, then narrate which hazards
+you designed out and why.
+
+## Limitations
+
+- Poka-yoke reduces predictable misuse; it cannot prove that a design is correct or cover
+  hazards the analysis never identifies.
+- The strongest control may be unavailable in the current language, platform or compatibility
+  envelope. When that happens, state the tradeoff and retain appropriate tests, monitoring and
+  recovery paths instead of presenting a warning as complete prevention.
+- A guard can itself be wrong, overbroad or operationally expensive. Validate proposed devices
+  against real callers and failure modes, especially for destructive, financial, authentication
+  and authorization flows.
+- This method complements, but does not replace, domain review, security review, testing,
+  observability or incident response.

package/bundled-skills/project-state-governor/SKILL.md

@@ -216,7 +216,7 @@ Example:
 session DONE != task DONE
 task DONE != milestone DONE
 milestone DONE != workstream DONE
-workstream DONE != mission success
+workstream COMPLETED != mission success
 ```
 
 ## 5. Session bootstrap and recall

package/bundled-skills/project-state-governor/references/project-state-schema.md

@@ -31,7 +31,7 @@ detailed record no longer affects future work.
 
 ## Milestones
 ### [Milestone ID or name]
-- Status: PROPOSED | ACTIVE | BLOCKED | PAUSED | DONE | DEFERRED
+- Status: PROPOSED | ACTIVE | BLOCKED | PAUSED | DONE | CANCELLED | DEFERRED
 - Goal: ...
 - DoD: ...
 - Parent: ...

package/bundled-skills/spec-driven-loop/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: spec-driven-loop
+description: Freeze PRD, technical design, and acceptance criteria before medium-to-large Codex work; coordinate agents with explicit ownership, then judge delivery from diffs, tests, and evidence.
+category: development
+risk: safe
+source: self
+source_repo: Linji-x/spec-driven-loop
+source_type: self
+license: MIT
+license_source: https://github.com/Linji-x/spec-driven-loop/blob/v1.0.0/LICENSE
+date_added: "2026-08-25"
+author: Linji-x
+tags:
+  - codex
+  - spec-driven-development
+  - multi-agent
+  - agent-orchestration
+  - acceptance-testing
+tools:
+  - codex
+---
+
+# Spec-Driven Loop
+
+Turn an uncertain software request into an approved specification, a controlled implementation, and evidence-backed acceptance. Keep project documents in the repository's established location; otherwise use `docs/spec-driven/<feature-slug>/`.
+
+## When to Use
+
+Use this skill for new products, medium-to-large features, cross-module changes, or requests that need PRD/technical design, active clarification, multi-agent execution, or a main-agent judge. Do not use it for a small single-file change, a tiny bug fix, code explanation, review-only or diagnostic work, pure research, or a simple task whose specification is already complete.
+
+## Quick Example
+
+```text
+$spec-driven-loop Build a multi-tenant job dashboard with role-based access and evidence-backed acceptance.
+```
+
+## Limitations
+
+- Not intended for small isolated edits, review-only work, diagnosis, or pure research.
+- Does not replace environment-specific testing or grant authorization for unrelated changes or external actions.
+- Production implementation cannot start until the user explicitly approves the frozen specification and acceptance contract.
+
+Follow repository instructions and authorization boundaries throughout. Match generated project documents to the user's language or the repository's existing documentation language; keep identifiers such as `FR-001` and `AC-001` stable.
+
+## Operating Invariants
+
+- Facts are the agent's responsibility. Decisions belong to the user.
+- Investigate discoverable facts before asking questions. Ask only for real product decisions or consequential technical tradeoffs.
+- Never write or modify production code until the user explicitly approves the specification, scope, and acceptance contract for implementation.
+- Never disguise uncertainty. Mark it `TBD`, `ASSUMPTION`, or `BLOCKED`.
+- A subagent's completion report is evidence, not acceptance. The main agent owns integration and the final judgment.
+- Freeze shared interfaces, data structures, and public types before parallel work. Assign non-overlapping file ownership; serialize overlapping work.
+- Update the durable documents after every decision or implementation loop. A chat transcript is not the source of truth.
+- If implementation reveals a requirement change rather than a code defect, stop affected work, revise the specification, obtain renewed user approval, and then resume.
+- Preserve the user's authorization scope. A specification approval authorizes the approved implementation, not unrelated changes or external actions.
+
+The requirements-grilling stage is informed by Matt Pocock's MIT-licensed `grill-me` / `grilling` decision-tree and frontier method.
+
+## Document Boundaries
+
+Keep each fact in one authoritative document and reference its stable ID elsewhere:
+
+- `PRD.md`: why and what the product must do; owns scope, user behavior, business rules, assumptions, and product decisions.
+- `TECH_DESIGN.md`: how the approved product behavior will work; owns architecture, contracts, data, operations, security, and technical decisions.
+- `ACCEPTANCE.md`: observable proof that frozen requirements are met; owns pass/fail criteria and required evidence.
+- `AGENT_PLAN.md`: who performs approved implementation work; owns dependencies, file ownership, validation, and agent task contracts.
+- `LOOP.md`: current recoverable execution state and append-only loop history; owns attempts, evidence, judgments, rework, risks, and next action.
+
+Read [references/document-templates.md](references/document-templates.md) when creating or updating these five documents. Read [references/agent-and-judge-contracts.md](references/agent-and-judge-contracts.md) before assigning implementation tasks, integrating agent work, judging acceptance, or issuing rework.
+
+## 1. Inspect the Current System
+
+Before asking the user questions:
+
+1. Read applicable `AGENTS.md`, project instructions, existing specifications, and repository conventions.
+2. Inspect the relevant architecture, modules, interfaces, database, tests, deployment method, and code conventions.
+3. Identify established domain terms and documentation locations.
+4. Resolve facts from code, files, tools, and documentation. Record findings and sources in the draft rather than asking the user to rediscover them.
+5. Separate product choices from technical choices and note decision dependencies.
+
+If frozen, approved PRD, Tech Design, and Acceptance documents already exist, verify their status, consistency, and applicability. Resume from planning or the current `LOOP.md` instead of repeating resolved grilling. If approval is absent or the request changes frozen behavior, return to the appropriate specification stage.
+
+## 2. Draft `PRD.md`
+
+Create the best initial PRD from the request and inspected system. Include:
+
+- problem and context;
+- users and stakeholders;
+- product goals and measurable success metrics;
+- user flows;
+- functional requirements with stable IDs (`FR-001`, `FR-002`, ...);
+- business rules and data lifecycle;
+- in scope, out of scope, and non-goals;
+- assumptions;
+- open product decisions;
+- decision log.
+
+Do not turn unknowns into requirements. Label each unresolved item `TBD`, `ASSUMPTION`, or `BLOCKED`, and show which FRs it affects.
+
+## 3. Grill Product Decisions
+
+Represent unresolved decisions as a dependency tree. The current **frontier** contains only high-impact questions whose upstream decisions are resolved.
+
+For each round:
+
+1. Select one to three independent frontier questions that the user can answer now.
+2. For every question, state why it matters, concrete options, the impact of each option, a recommended option, and the reason for that recommendation.
+3. Prefer a reversible explicit assumption for a low-risk issue that does not affect acceptance behavior.
+4. After the answer, immediately update `PRD.md` and its decision log, then recompute the frontier.
+5. Continue until no important unresolved branch remains. Do not dump a backlog of dependent questions or repeat resolved questions.
+
+Never auto-assume core product behavior, data ownership, permission or security behavior, migrations, external compatibility, payments or money movement, destructive actions, explicit performance targets, or behavior that changes final acceptance. Keep these as blockers.
+
+When the product frontier is clear, summarize confirmed decisions, accepted assumptions, non-goals, deferred items, and remaining risks. Ask the user to confirm that the PRD reflects the shared product understanding before treating it as frozen.
+
+## 4. Draft and Grill `TECH_DESIGN.md`
+
+After product behavior is understood, document:
+
+- current system state and overall approach;
+- module boundaries and responsibilities;
+- interface contracts;
+- data models and migrations;
+- state transitions;
+- concurrency, consistency, and idempotency;
+- authentication, authorization, privacy, and security;
+- failures, retries, recovery, and degradation;
+- performance and capacity;
+- logs, metrics, and alerts;
+- compatibility;
+- release and rollback;
+- test boundaries;
+- alternatives and technical decision log;
+- technical issues blocked by product decisions.
+
+Mark a design item `BLOCKED` when it depends on an unresolved product decision. Grill consequential technical choices with the same decision-tree/frontier method: one to three answerable questions per round, options and impacts, a recommendation with rationale, immediate document updates, and no hidden high-risk assumptions. Resolve ordinary implementation facts by inspecting the system.
+
+## 5. Freeze `ACCEPTANCE.md` and Request Approval
+
+After the PRD and Tech Design share a stable understanding, write the acceptance contract. Give each criterion a stable ID (`AC-001`, `AC-002`, ...), link it to one or more FRs, and specify:
+
+- scenario and preconditions;
+- action or event;
+- observable expected result;
+- required evidence;
+- whether it is release-blocking.
+
+Cover applicable happy paths, boundary and invalid inputs, permissions, failure and recovery, repeated requests and idempotency, concurrency, compatibility, performance and capacity, migration, rollback, regression, and existing quality gates. Distinguish In Scope, Out of Scope, Non-goals, Deferred, Assumptions, Release Blockers, and Definition of Done.
+
+Do not accept subjective criteria such as "good experience", "good performance", "high code quality", or "mostly works". Every blocking AC needs observable evidence such as automated tests, API responses, database state, logs, metrics, screenshots, performance results, or a precise manual check.
+
+Show the user a concise specification summary and ask: **The specification, scope, and acceptance conditions are defined. Do you approve implementation?** Record the answer. Do not write production code without explicit approval.
+
+## 6. Create `AGENT_PLAN.md`
+
+Only after implementation approval, split work into independently verifiable vertical slices rather than mechanically separating frontend, backend, and tests. For each task include:
+
+- Task ID and objective;
+- linked FR and AC IDs;
+- inputs and dependencies;
+- exact allowed files or directories;
+- exact forbidden files or directories;
+- required code, tests, or documentation;
+- required checks and evidence;
+- stop-and-report conditions.
+
+Before parallel delegation, freeze shared interfaces, schemas, and public types. Confirm that writes do not overlap. Serialize any tasks with overlapping ownership or unresolved dependencies. Use multiple agents only when at least two tasks are truly independent and delegation is available and authorized; do not create agents merely to display parallelism.
+
+The main agent maintains the specification, approves ownership changes, handles dependencies and conflicts, integrates results, runs system-level verification, and judges final acceptance. Subagents may not expand scope, change acceptance criteria, unilaterally change shared contracts, cross ownership boundaries, lower test requirements, or declare the whole project complete.
+
+## 7. Create and Maintain `LOOP.md`
+
+Create `LOOP.md` before production implementation. Its top section must expose enough state for a new session to resume after reading only the top status and current loop. Use exactly one current state:
+
+`drafting`, `grilling`, `awaiting-spec-approval`, `ready`, `implementing`, `judging`, `changes-requested`, `blocked`, or `accepted`.
+
+Each loop records its Loop ID, objective, FR/AC IDs, assignments, dependencies, outputs, changed files, commands/checks, results, evidence, main-agent judgment, failure conditions, rework requirements, unresolved risks, next state, and next action. Update the top state when reality changes. Never delete or overwrite a failed loop; append the next attempt.
+
+## 8. Execute Approved Work
+
+Give each subagent only the context required by its task contract. Require the completion-report format from [references/agent-and-judge-contracts.md](references/agent-and-judge-contracts.md). Treat contract deviations, new blockers, interface changes, and ownership conflicts as stop-and-report events.
+
+Integrate in dependency order. Inspect actual changes instead of relying on summaries. Keep `LOOP.md` current with files, checks, results, evidence, risks, and status.
+
+## 9. Judge Independently
+
+The main agent must:
+
+1. Compare the actual diff and behavior with the frozen specification.
+2. Check ownership compliance and scope expansion.
+3. Check cross-module contracts and data structures.
+4. Run the highest feasible end-to-end validation plus necessary unit, integration, and regression tests.
+5. Exercise applicable failure, permission, idempotency, concurrency, migration, rollback, and recovery behavior.
+6. Produce evidence for every blocking AC.
+7. Record an acceptance matrix: `Acceptance ID | Result | Evidence | Defect/Caveat`.
+
+Allowed conclusions are `ACCEPTED`, `CHANGES_REQUESTED`, `BLOCKED`, and `ACCEPTED_WITH_CAVEATS`. Missing evidence for a blocking AC is a failure. Existing code, passing unit tests, a subagent's claim, or majority agreement is never sufficient by itself; only the frozen acceptance contract determines the result.
+
+For `CHANGES_REQUESTED`, append a new loop for only the failed ACs, include reproduction evidence, constrain the minimum repair scope, and require regression coverage. Never weaken acceptance to manufacture a pass. After the same AC fails judgment in three consecutive loops, stop automatic rework and ask the user to choose redesign, scope change, accepted limitation, or termination of that part.
+
+## 10. Deliver
+
+Lead with the result, then report completed scope, incomplete or deferred scope, the acceptance matrix, test and validation evidence, key design decisions, remaining risks, accepted assumptions, and suggested next steps. Ensure the final `LOOP.md` state matches the real outcome.

package/bundled-skills/spec-driven-loop/references/agent-and-judge-contracts.md

@@ -0,0 +1,120 @@
+# Agent and Judge Contracts
+
+Read this reference only after the specification and acceptance contract are frozen and the user has approved implementation. The main agent owns these contracts, integration, and final judgment.
+
+## Subagent Task Contract
+
+```markdown
+Task ID:
+Objective:
+Related FR IDs:
+Related AC IDs:
+
+Inputs:
+Dependencies and prerequisite state:
+Frozen contracts/types/schemas:
+
+Allowed files or directories:
+Forbidden files or directories:
+
+Required implementation outputs:
+Required tests or documentation:
+Checks that must be executed:
+Evidence that must be returned:
+
+Stop and report if:
+- a requirement or acceptance condition must change;
+- a frozen shared contract must change;
+- an allowed path is insufficient;
+- another task owns a required file;
+- a dependency is missing or inconsistent;
+- a security, data-loss, migration, or external-compatibility risk appears.
+
+Completion authority: Report task results and evidence only. Do not declare overall acceptance.
+```
+
+## Subagent Completion Report
+
+Require this exact field set so integration evidence is comparable:
+
+```text
+Status:
+Acceptance IDs addressed:
+Files changed:
+Behavior implemented:
+Checks executed:
+Results:
+Evidence:
+Assumptions:
+Risks:
+Contract deviations:
+```
+
+`Status` describes the assigned task only. Any non-empty `Contract deviations` field is a main-agent review trigger, not an implicit approval.
+
+## File Ownership Rules
+
+1. Express ownership with explicit repository-relative paths or narrowly defined directory trees; never use phrases such as "related files" or "files as needed".
+2. Freeze shared interfaces, schemas, generated clients, public types, and migration ordering before parallel work.
+3. Give each writable file to one task at a time. Read access may overlap; write ownership may not.
+4. If two tasks require the same file, order them serially or assign the shared edit to a separate prerequisite task.
+5. A subagent must stop and request an ownership amendment before editing outside its allowed scope.
+6. Only the main agent may approve an ownership amendment, recheck overlap, update `AGENT_PLAN.md`, and notify affected tasks.
+7. Changes beyond the frozen scope return to specification approval; they are not ownership amendments.
+
+## Main-Agent Integration Checklist
+
+- Inspect actual diffs and changed files, not only reports.
+- Compare changed paths with every task's ownership contract.
+- Confirm shared contracts match the frozen version across modules.
+- Integrate in dependency order and resolve conflicts centrally.
+- Check that no task expanded requirements or weakened tests/acceptance.
+- Run the highest feasible end-to-end path.
+- Run applicable unit, integration, regression, migration, rollback, permission, invalid-input, idempotency, concurrency, failure, and recovery checks.
+- Collect observable evidence for every blocking AC.
+- Update the current `LOOP.md` attempt before reaching a judgment.
+
+## Acceptance Matrix
+
+```markdown
+| Acceptance ID | Result | Evidence | Defect/Caveat |
+|---|---|---|---|
+| AC-001 | Pass | <test/log/API/DB/screenshot/metric/manual check> | None |
+```
+
+Use only `Pass`, `Fail`, or `Blocked` per row. A blocking row without adequate evidence cannot be `Pass`. After evaluating all rows, choose exactly one overall judgment:
+
+- `ACCEPTED`: every blocking AC passes and the Definition of Done is met.
+- `ACCEPTED_WITH_CAVEATS`: every blocking AC passes; documented non-blocking limitations remain.
+- `CHANGES_REQUESTED`: one or more ACs fail and a bounded repair is feasible.
+- `BLOCKED`: required validation or implementation cannot proceed because of an unresolved dependency or decision.
+
+## Rework Task Contract
+
+```markdown
+Rework Task ID:
+Source Loop ID:
+Failed AC IDs:
+Reproduction evidence:
+Observed versus expected behavior:
+Minimum repair scope:
+Allowed files or directories:
+Forbidden files or directories:
+Required regression test:
+Checks and evidence required:
+Unchanged frozen contracts:
+Stop and report if:
+Attempt number for each failed AC:
+```
+
+Append rework as a new loop. Do not erase the failed attempt, broaden the repair beyond failed ACs, or lower an acceptance condition to produce a pass.
+
+## Three-Consecutive-Failures Stop Rule
+
+Track failure counts per AC, not per project. When the same AC fails main-agent judgment in three consecutive loops:
+
+1. stop automatic rework for that AC;
+2. set `LOOP.md` to `blocked` unless other independent work may safely continue;
+3. present the three attempts and evidence to the user;
+4. ask the user to choose redesign, scope change, acceptance of a documented limitation, or termination of that part;
+5. obtain renewed specification approval before continuing after redesign or scope/acceptance changes.