yadflow 4.0.0-next.3 → 4.0.0

package/skills/sdlc/module-help.csv

@@ -3,13 +3,13 @@ SDLC Workflow,yad-discovery,Foundation,DI,"The Foundation — the Product level,
 SDLC Workflow,yad-analysis,Author Analysis,AN,"Optional Shape step: with the analyst pressure-test a feature idea and write the discovery brief into analysis.md. Assigns the EP-<slug> ID and seeds .sdlc state (the chain that puts analysis before epic). If skipped, the epic step does this shaping inline. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,false,epics/EP-<slug>/,analysis.md state.json
 SDLC Workflow,yad-epic,Author Epic,AE,"Shape step 1: shape an idea with analyst then pm into epic.md; assign EP-<slug> ID and seed .sdlc state. Never auto-advances.",,{idea: one-line feature idea},1-front,,yad-review-gate,true,epics/EP-<slug>/,epic.md state.json
 SDLC Workflow,yad-review-gate,Team Review Gate,RG,"Reusable review+approve gate for every Shape review. Shares an artifact for review, records comments and approvals as files, enforces at least 1 approval from someone other than the author (contract/auth/payments add a risk step to the count, capped at the active people less one and advisory), advances state only when approved.",,{artifact: file under the epic} {action: open|comment|approve|advance},1-front,,,true,epics/EP-<slug>/reviews/,reviews/*.md approvals.json state.json
-SDLC Workflow,yad-review-companion,Review Companion,RC,"Fun, easy, transparent review companion for the review gates (Shape gate AND Build code PR). Generates a 60-sec AI trailer of what changed and where the risk is, deals swipe-through review cards, and runs a grounded chat where a reviewer's questions become the review record — then records an engagement signal on the approval (verified vs none) and posts a friendly public @-mention nudge on a bare rubber-stamp. Companion comments carry a noblock marker so they never hold the gate. Soft by default (visible, not impossible); gates only when hub.review.requireEngagement. Never auto-advances.",,{epic: EP-<slug>} {artifact} | {repo} {pr} {action: trailer|cards|chat|nudge},1-front,,,false,epics/EP-<slug>/reviews/ | code PR,trailer/cards/chat (platform) approvals.json engagement
-SDLC Workflow,yad-pair-review,Pair Review,PV,"The guided, two-way, teaching pair-review walkthrough — the AI-driven 5th companion face (Shape gate AND Build code PR). The human opens a PR/MR with an AI session and the AI walks them through the change one stop at a time (highest-risk first), gives comprehensive context per change, then asks a Socratic question; the human answers and asks back until BOTH declare satisfied. Doubles as a learning session: demonstrates a transferable review method, scores the engineer, and records review-skill growth in the local-only yad-learn ledger (rolled up by yad status). Soft and additive — NEVER blocks; rides the engagement signal and surfaces genuine concerns as normal blocking comments. Never auto-advances.",,{epic: EP-<slug>} {artifact} | {repo} {pr} {member} {action: walkthrough|record|rubric},3-build,yad-review-companion,,false,epics/EP-<slug>/reviews/ | code PR | epics/EP-<slug>/learning/ (local-only),pair session (platform) learning-records.json learning/<member>--review-<pr>.md
+SDLC Workflow,yad-review-companion,Review Companion,RC,"Fun, easy, transparent review companion for the review gates (Shape gate AND Build code PR). Generates a 60-sec AI trailer of what changed and where the risk is, deals swipe-through review cards, and runs a grounded chat where a reviewer's questions become the review record — then records an engagement signal on the approval (verified vs none) and posts a friendly public @-mention nudge on a bare rubber-stamp. Companion comments carry a noblock marker so they never hold the gate. Soft by default (visible, not impossible); gates only when review.requireEngagement is on in the Product settings. Never auto-advances.",,{epic: EP-<slug>} {artifact} | {repo} {pr} {action: trailer|cards|chat|nudge},1-front,,,false,epics/EP-<slug>/reviews/ | code PR,trailer/cards/chat (platform) approvals.json engagement
+SDLC Workflow,yad-pair-review,Pair Review,PV,"The guided, two-way, teaching pair-review walkthrough — the AI-driven 5th companion face (Shape gate AND Build code PR). The human opens a PR/MR with an AI session and the AI walks them through the change one stop at a time (highest-risk first), gives comprehensive context per change, then asks a Socratic question; the human answers and asks back until BOTH declare satisfied. Doubles as a learning session: demonstrates a transferable review method, scores the engineer, and records review-skill growth in the local-only yad-learn ledger (rolled up by the yad-status skill). Soft and additive — NEVER blocks; rides the engagement signal and surfaces genuine concerns as normal blocking comments. Never auto-advances.",,{epic: EP-<slug>} {artifact} | {repo} {pr} {member} {action: walkthrough|record|rubric},3-build,yad-review-companion,,false,epics/EP-<slug>/reviews/ | code PR | epics/EP-<slug>/learning/ (local-only),pair session (platform) learning-records.json learning/<member>--review-<pr>.md
 SDLC Workflow,yad-architecture,Author Architecture,AA,"Shape step 3: with the architect author architecture.md and the locked contract.md; hash-lock the contract surface. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,architecture.md contract.md contract-lock.json state.json
 SDLC Workflow,yad-ui,Author UI Design,AU,"Shape step 5: with the ux-designer author ui-design.md and DESIGN.md, driving Impeccable slash-commands when installed. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,ui-design.md DESIGN.md state.json
 SDLC Workflow,yad-stories,Author Stories,AS,"Shape step 7: with the pm break the epic into repo-tagged stories with stable EP-<slug>-S0N IDs, one file each under stories/. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/stories/,stories/EP-<slug>-S0N.md state.json
 SDLC Workflow,yad-test-cases,Author Test Cases,TC,"Shape step 9 (PARALLEL, non-blocking): opens when the stories gate passes — the epic is already ready-for-build, so Build can start at the same time the tester works here. With the test architect author test-cases.md covering the approved stories, and — when a testing tool is connected (.sdlc/testing.json) — generate/link the actual automation tests in it, recording test-links.json; otherwise produce the test-case artifact only. Its review never moves currentStep off ready-for-build. Never auto-advances.",,{epic: EP-<slug>},1-front,yad-review-gate,yad-review-gate,true,epics/EP-<slug>/,test-cases.md test-links.json state.json
-SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the Product so the Shape/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. yad repo refresh --push publishes the refreshed code-maps + registry to the Product default branch as a chore(hub): sync code-context [skip ci] audit commit. Also drafts each code repo's .sdlc/risk-map (a level per directory, no names) by reading the code, marked guessed for a person to confirm. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>},0-setup,,yad-sync-repos,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
+SDLC Workflow,yad-connect-repos,Connect Code Repos,CR,"Setup/maintenance: connect code repos to the Product so the Shape/brain phases are code-aware. Registers each repo (GitHub or GitLab, local-user auth, no stored tokens) in .sdlc/repos.json and caches a Repomix pack + a lightweight code-map (existing endpoints/events/data-models/modules, secret-scanned). Idempotent and refreshable; staleness tracked by HEAD sha. yad repo refresh --push publishes the refreshed code-maps + registry to the Product default branch as a chore(product): sync code-context [skip ci] audit commit. Also drafts each code repo's .sdlc/risk-map (a level per directory, no names) by reading the code, marked guessed for a person to confirm. Run at setup or any time a new repo is added. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {repo: <name>} {path: <path-or-absolute>} {git_url: <ssh-or-https>},0-setup,,yad-sync-repos,false,.sdlc/,repos.json code-context/<repo>/pack.md code-context/<repo>/code-map.md
 SDLC Workflow,yad-sync-repos,Sync Connected Repos,SR,"Setup/maintenance: bring every connected repo up to date in one shot — switch each repo in .sdlc/repos.json to its default_branch and fast-forward it from origin (local-user git, no stored tokens). Working-tree only; never a gate and never writes the registry. A dirty repo is skipped and reported (never overwritten); a diverged branch is left for manual resolution (fast-forward only). After pulling, a repo's cached pack goes stale — points the human at yad repo refresh.",,{action: sync} {repo: <name>},0-setup,yad-connect-repos,yad-connect-design,false,,(none — working-tree only)
 SDLC Workflow,yad-connect-design,Connect Design Tool,CD,"Setup/maintenance: connect a design tool (Figma-first, pluggable) to the Product so the UI design step can materialize the actual feature design (mobile screens / web pages) inside it, alongside ui-design.md + DESIGN.md. Records the tool + project/file references in .sdlc/design.json (local-user / MCP-session auth, no stored tokens), detecting whether a design-tool MCP is available and degrading to markdown-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,"{action: connect|refresh|list|disconnect} {tool: figma|pencil|none} {project_url: <team/project/file url>} {files: {web,mobile}}",0-setup,,yad-ui,false,.sdlc/,design.json
 SDLC Workflow,yad-connect-testing,Connect Testing Tool,CT,"Setup/maintenance: connect a testing tool (Playwright-first, pluggable) to the Product so the test-cases step can implement the actual automation tests in it, alongside test-cases.md. Records the tool + project/suite references in .sdlc/testing.json (local-user / MCP-session auth, no stored tokens), detecting whether a testing-tool MCP is available and degrading to artifacts-only when absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {tool: playwright|cypress|pytest|none} {project_url: <project/config reference>} {suites: {<repo>}},0-setup,,yad-test-cases,false,.sdlc/,testing.json
@@ -17,18 +17,18 @@ SDLC Workflow,yad-connect-learning,Connect Learning Tool,CL,"Setup/maintenance:
 SDLC Workflow,yad-learn,Learn (Tutor),LN,"Cross-cutting learning layer: at ANY SDLC stage a team member can ask to learn a concept and be tutored in the context of what the team is building. Routes to the connected learning tool (.sdlc/learning.json, DeepTutor-first) grounded in the project knowledge base, or degrades to harness-native tutoring (the harness model reading the artifacts). Renders a tutorial artifact and appends to a per-member learning ledger kept LOCAL-ONLY (gitignored, never committed/pushed to the Product or any code repo) so it stays a private, personal skills log (yad-status rolls up the local records). Purely opt-in — never blocks a gate, never touches epic state, approvals, or the contract lock.",,{concept: <idea>} {context: <focus>} {epic: EP-<slug>} {stage: <sdlc stage>} {member: <who>} {mode: explain|deep|quiz} {action: learn|list|complete},anytime,,,false,epics/EP-<slug>/,learning-records.json learning/<member>--<concept>.md
 SDLC Workflow,yad-spec,Author Spec,SP,"Build Step A: for one ready-for-build story and one of its repos, run the heavy Spec Kit ceremony once (specify→clarify→plan→analyze→checklist→tasks) inside that code repo, writing specs/<story-id>/ in Spec Kit's layout (drives /speckit.* when installed, else hand-authors and records speckit: not-installed). References the locked contract; never re-invents the surface. Writes link.md back to the story. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>},3-build,yad-review-gate,,false,demo-repos/<repo>/specs/<story-id>/,spec.md research.md data-model.md contracts/ plan.md tasks.md link.md
 SDLC Workflow,yad-implement,Implement Task,IM,"Build Step B: with the dev lens, implement ONE atomic task from a story's tasks.md as a small diff (<=3 files) on its own branch feat/<story>-<task>-<slug> in the code repo. Diff stays inside the task's declared files (flag and STOP if it grows beyond them). Commit ends with a Task: <story>-<task> trailer; add Contract-Change: yes only when the locked contract surface is touched (routes back to the architecture gate). Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <one of story.repos>} {task: T0N},3-build,yad-spec,,false,demo-repos/<repo>/,branch+commit per atomic task
-SDLC Workflow,yad-checks,Check Gates,CK,"Build Step C: wire and run the production-safety CI gates on a code repo (and Product) — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (every commit carries a platform-Verified signature), and the pattern gates commit-message / pr-title / pr-template (profile-aware code|hub). CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab/ci/yad-checks.yml
-SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build Step D: detect a code repo's platform and commit the matching PR/MR template (.github/pull_request_template.md or .gitlab/merge_request_templates/Default.md) with an Impact & Risk block. A high risk level (or a touched contract surface) raises the approver count — the same count yad-review-gate prints. Ships the routing helper risk-route.sh plus the pattern-gate scripts pr-title.sh and pr-template.sh (used by yad-checks). Never auto-advances.",,{repo: <one of an epic's repos | hub>} {action: wire|route} {body: PR description file},3-build,yad-checks,,false,demo-repos/<repo>/,.github/pull_request_template.md .gitlab/merge_request_templates/Default.md checks/risk-route.sh checks/pr-title.sh checks/pr-template.sh
+SDLC Workflow,yad-checks,Check Gates,CK,"Build Step C: wire and run the production-safety CI gates on a code repo (and Product) — spec-link (every change links a real story/spec via its Task trailer), contract-check (a contract-surface change without Contract-Change + an updated re-locked contract FAILS and routes back to the architecture gate), build/test/lint, verified-commits (every commit carries a platform-Verified signature), and the pattern gates commit-message / pr-title / pr-template (profile-aware code|product). CI-agnostic bash invoked by GitHub Actions and GitLab CI. Blocking in CI; the human still owns the merge. Never auto-advances.",,{repo: <one of an epic's repos | product>} {action: wire|run} {base: target branch},3-build,yad-implement,,false,demo-repos/<repo>/,checks/*.sh .github/workflows/yad-checks.yml .gitlab/ci/yad-checks.yml
+SDLC Workflow,yad-pr-template,PR/MR Template,PT,"Build Step D: detect a code repo's platform and commit the matching PR/MR template (.github/pull_request_template.md or .gitlab/merge_request_templates/Default.md) with an Impact & Risk block. A high risk level (or a touched contract surface) raises the approver count — the same count yad-review-gate prints. Ships the routing helper risk-route.sh plus the pattern-gate scripts pr-title.sh and pr-template.sh (used by yad-checks). Never auto-advances.",,{repo: <one of an epic's repos | product>} {action: wire|route} {body: PR description file},3-build,yad-checks,,false,demo-repos/<repo>/,.github/pull_request_template.md .gitlab/merge_request_templates/Default.md checks/risk-route.sh checks/pr-title.sh checks/pr-template.sh
 SDLC Workflow,yad-commit,Commit by Convention,CM,"Build helper: commit ONE staged atomic change by the conventions — a Conventional-Commits subject, the fixed trailer block (Task -> Contract-Change -> Co-Authored-By), and the <=3-file atomic guard. The human git author owns the commit; an assisting AI is recorded only as a Co-Authored-By footer chosen per-commit with --ai (claude|copilot|cursor|coderabbit|none, default none). Drives the yad commit CLI. Never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {task: <id>} {contract-change: true|false},3-build,yad-implement,,false,<repo>/,one commit
-SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Assigns the logged-in gh/glab login and requests no reviewers; high risk / contract surface raises the approver count (risk-route.sh prints it). Bases the PR on the repo's RESOLVED default branch (--base, else repos.json default_branch, else hub.json default_branch for a PR on the Product itself, else the platform's own default, else origin/HEAD, else main) instead of a hardcoded main, and warns when the base is not the platform default — that loses the AI first pass irreversibly. Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-commit,,false,<repo>/,one PR/MR
+SDLC Workflow,yad-open-pr,Open PR/MR,OP,"Build helper: open a code-repo task PR/MR from the committed platform template — detect GitHub/GitLab, push the task branch, create the PR/MR with the body prefilled (Summary / Story-task / Impact & Risk) and the title defaulting to the commit subject. Assigns the logged-in gh/glab login and requests no reviewers; high risk / contract surface raises the approver count (risk-route.sh prints it). Bases the PR on the repo's RESOLVED default branch (--base, else repos.json default_branch, else product.json (hub.json on an older Product) default_branch for a PR on the Product itself, else the platform's own default, else origin/HEAD, else main) instead of a hardcoded main, and warns when the base is not the platform default — that loses the AI first pass irreversibly. Drives the yad open-pr CLI. Never merges; never auto-advances.",,{repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-commit,,false,<repo>/,one PR/MR
 SDLC Workflow,yad-ship,Commit + Open PR/MR,SP2,"Build helper: commit AND open the task PR/MR in one step — a thin orchestration over yad-commit then yad-open-pr. Commits the staged atomic change by the conventions, then pushes the branch and opens the PR/MR from the committed template, assigned to the logged-in gh/glab login with no reviewers requested. The PR step runs ONLY if the commit lands (a failed commit, tripped guard, or --dry-run stops before pushing). Drives the yad ship CLI. Never merges; never auto-advances.",,{type: feat|fix|...} {message: subject} {ai: <tool|none>} {repo: <name>} {risk: low|medium|high} {contract-change: true|false} {base: <branch>},3-build,yad-pr-template,,false,<repo>/,one commit + one PR/MR
-SDLC Workflow,yad-hub-bridge,Hub Review Bridge,HB,"The templated PR/MR bridge for the Shape review gate: when the Product has a platform (.sdlc/hub.json), open a review PR/MR on the Product for an authored artifact, apply the touched-domain labels (no reviewers are requested), and provide the read-only gh/glab recipes yad-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to local when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,yad-review-gate,yad-review-gate,false,epics/EP-<slug>/.sdlc/,hub-prs.json
+SDLC Workflow,yad-product-bridge,Product Review Bridge,PB,"The templated PR/MR bridge for the Shape review gate: when the Product has a platform (.sdlc/product.json), open a review PR/MR on the Product for an authored artifact, apply the touched-domain labels (no reviewers are requested), and provide the read-only gh/glab recipes yad-review-gate's sync uses to pull platform comments + approvals into the file ledger. Local-user auth, no stored tokens; file ledger stays the source of truth; degrades to local when no platform/CLI. Never auto-advances.",,{epic: EP-<slug>} {artifact: epic.md|architecture.md|ui-design.md|stories/} {action: open|route},1-front,yad-review-gate,yad-review-gate,false,epics/EP-<slug>/.sdlc/,product-prs.json
 SDLC Workflow,yad-engineer-review,Engineer Review & Merge,ER,"Build Step E: wire an advisory AI first-pass (CodeRabbit) on the PR, record the human engineer review with the same advance-human discipline as the Shape gates (1 approval from someone other than the author; high risk / contract / auth / payments add an advisory risk step), and on merge record the ship in epics/<epic>/.sdlc/build-log.json and update the story state. AI review is advisory, never the authority; the human owns the merge. Never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {task: T0N} {repo: <repo>} {action: ai-review|approve|ship},3-build,yad-ship,,false,epics/EP-<slug>/.sdlc/,build-log.json story-status
 SDLC Workflow,yad-backfill,Backfill Specs,BF,"Build Step G: generate specs for already-built features in an existing repo. Confirm Repomix (npx repomix CLI), pack ONE feature (compress + git logs, secret-scan), feed to AI with a 'describe what exists, do not invent' prompt, write a DRAFT spec marked verified: false. Human approval (reuse yad-review-gate) makes it real. Boundary auto-proposed and human-confirmed. A change is blocked only until the features it touches have approved specs. The promote action flips a brownfield stub epic (yad-stub) to a real, verified feature epic once its backfill spec is approved. Never auto-advances.",,{repo: <repo>} {feature: <name + globs>} {action: pack|draft|approve|gate|promote} {epic: EP-<slug> (promote)},3-build,,,false,demo-repos/<repo>/specs/backfill/<feature>/,spec.md backfill-check.sh
 SDLC Workflow,yad-run,Run (Automation),RN,"Phase 4 orchestrator: drive a story's Build loop (spec→tasks→implement→checks) in one code repo, reading each step's advance dial through the engine (yad dial --json) — on auto it advances on its own, on human it stops for a human. Records every run in the trust log, the run record yad dial shows as advice. A clean checks pass on auto advances to the engineer review; any FAIL / scope overrun / contract touch HALTS. set-dial runs yad dial (no trust threshold since E34; a gate is refused); kill/unkill run yad kill / yad unkill, recorded in .sdlc/automation.json. Never drives a Shape step; the human merge gate never auto-advances.",,{epic: EP-<slug>} {story: EP-<slug>-S0N} {repo: <repo>} {action: run|set-dial|kill|unkill} {step: <back-step>} {to: human|auto},4-automate,yad-spec,yad-engineer-review,false,epics/EP-<slug>/.sdlc/,build-state/<story-id>.json trust-log.json
 SDLC Workflow,yad-status,SDLC Status,SS,"Read-only: print the full Shape step chain, per-step dials, contract lock, story repo tags, and pending approvals at the active gate. For stories in Build, also print each Build step's automation dial and status, the run record (runs / % approved-unchanged, as advice), the Shape author dials and the kill switch from .sdlc/automation.json.",,{epic: EP-<slug>},anytime,,,false,,
 SDLC Workflow,yad-report,Report Issue,RP,"Self issue reporter: when a yad flow breaks, file a well-formed bug in the upstream yadflow repo with AUTO-SCRUBBED diagnostics (yadflow/node/os version, tool present+authenticated booleans, Product platform enum, the YadError code/hint, a path-scrubbed message, and the failing command + flag NAMES only) — never absolute paths, hostnames, git URLs, repo names, logins/emails, epic/story IDs, branch names, or flag values. Searches open issues first to avoid duplicates, previews the exact payload, and asks before posting to the public repo; files via an authenticated gh (the upstream repo is on GitHub) or a prefilled issues/new URL fallback. Also offered automatically after an unexpected failure (interactive only; YAD_NO_REPORT=1 disables). Never a gate, never touches epic state.",,{message: one-line summary},,,,false,,
-SDLC Workflow,yad-connect-docs,Connect Docs Target,DX,"Setup/maintenance: connect a docs/Pages publishing target so the interactive-docs steps can deploy the generated site (not just commit its source). Auto-detects the platform from .sdlc/hub.json (github->github-pages, gitlab->gitlab-pages, null->build-only), resolves the Vite base path, and records the target in .sdlc/docs.json (local-user auth, no stored tokens). Degrades to build-only when gh/glab is absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {target: github-pages|gitlab-pages|none} {scope: hub|<repo>|dedicated} {base_path: <override>},0-setup,,yad-docs,false,.sdlc/,docs.json
+SDLC Workflow,yad-connect-docs,Connect Docs Target,DX,"Setup/maintenance: connect a docs/Pages publishing target so the interactive-docs steps can deploy the generated site (not just commit its source). Auto-detects the platform from .sdlc/product.json (github->github-pages, gitlab->gitlab-pages, null->build-only), resolves the Vite base path, and records the target in .sdlc/docs.json (local-user auth, no stored tokens). Degrades to build-only when gh/glab is absent. Idempotent and refreshable; one connection per project. Not a gated state — never touches epic state or approvals.",,{action: connect|refresh|list|disconnect} {target: github-pages|gitlab-pages|none} {scope: product|<repo>|dedicated} {base_path: <override>},0-setup,,yad-docs,false,.sdlc/,docs.json
 SDLC Workflow,yad-docs,Author Docs Site,DS,"Generate the per-epic interactive documentation SPA (animated flow canvas + role-based stakeholder doc pages) from the epic's approved artifacts (epic, architecture, locked contract, ui-design, stories, code-context, test-cases), themed by the connected design system, into epics/EP-<slug>/docs-site/. Copies the vendored React/Vite/Tailwind shell verbatim and generates src/data/*.ts deterministically; drives the yad docs build/deploy CLI to publish to Pages (or build-only). An OUTPUT ENRICHMENT — never a gate; never mutates state.json, approvals, or the contract lock.",,{epic: EP-<slug>} {action: generate|refresh|deploy} {login_gate: true|false},4-automate,yad-review-gate,,false,epics/EP-<slug>/docs-site/,docs-site/ docs-build.json
 SDLC Workflow,yad-docs-overview,Docs Overview Site,DO,"Generate the project SDLC-overview interactive site (docs/sdlc-site/) — every stage from setup to ship modeled as flow paths, system components, and stakeholder roles — reusing the same vendored shell, themed with yadflow's brand palette. Reads config.yaml + module-help.csv + the overview diagram as the pipeline source. Folds the hand-maintained docs/index.html report into the site as report.html (linked from the nav). Not a gate — a project-level enrichment that regenerates whenever the skill set / pipeline changes.",,{action: generate|deploy},4-automate,,,false,docs/sdlc-site/,sdlc-site/ .docs-build.json
 SDLC Workflow,yad-docs-sync,Docs Sync,DY,"Maintenance/CI: keep the generated doc sites fresh. Detect staleness (a content hash of the approved artifacts + the connected repos' HEAD shas + for a per-epic site the doc-shell version, vs each site's build manifest), report which sites drifted and why, regenerate + redeploy the stale ones, and wire a CI job that rebuilds on push (carrying [skip ci] + a concurrency group to prevent deploy loops). Generalizes the rule that feature work must hand-update docs/index.html + diagrams + skill counts. Refresh is always a human/CI decision; never a gate.",,{action: check|refresh|wire} {epic: EP-<slug>},4-automate,,,false,epics/EP-<slug>/.sdlc/,docs-build.json yad-docs.yml

package/skills/yad-analysis/SKILL.md

@@ -15,7 +15,9 @@ This step is **optional**. When it runs, it is the entry point: it assigns the I
 analyst shaping inline and seeds the **10-step** chain — no behaviour change for teams that skip it.
 
 This skill enforces the build plan's core rules: all state lives in files; IDs are generated by the
-engine (never typed by hand); Shape steps are locked to `advance: human`.
+engine (never typed by hand); every Shape step starts at `advance: human`. A review gate is always
+human; only the team can set a Shape author step to auto (`yad dial`, recorded in
+`.sdlc/automation.json`; nothing acts on it yet).
 
 ## Conventions
 
@@ -131,7 +133,7 @@ yad epic new EP-<slug> --profile spike --type <feature|chore>   # a timeboxed in
 
 That writes `{project-root}/epics/EP-<slug>/.sdlc/state.json`, the empty `approvals.json` and
 `comments.json`, and the `reviews/` directory. With `--profile analysis-first` the chain is the full
-**12-step** route (`analysis` before `epic`). Every step is `advance: human` and locked; `analysis` is
+**12-step** route (`analysis` before `epic`). Every step starts at `advance: human`; `analysis` is
 open and the rest are `todo`. The chain comes from the step catalogue and the lifecycle profile in
 the engine (`../yad-epic/references/state-schema.md`), so there is one definition of it and no copy
 here to drift from it.
@@ -177,7 +179,7 @@ Notes:
 *(**Always run this**, on both entry modes. The chain is seeded by now either way — by `yad epic new`
 in Step 6, or by `yad epic new` before this skill was invoked — and `analysis.md` is written. This is
 the step that closes the authoring step and opens its gate.)*
-**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name):
 **verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run
 `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
@@ -211,7 +213,7 @@ Report: epic ID, the path to `analysis.md`, and that the next action is **review
 `yad-review-gate` (base rule: 1 distinct approver, who should not be the author). **Never mark the analysis-review step approved
 here** — only real reviewers do that through the gate. Shape steps do not auto-advance. When the
 analysis gate passes, control moves to `yad-epic`, which reads `analysis.md` as input. When the
-Product has a platform, the gate opens a review PR on the Product (via `yad-hub-bridge`) and
+Product has a platform, the gate opens a review PR on the Product (via `yad-product-bridge`) and
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; otherwise the review
 is recorded local.
 

package/skills/yad-architecture/SKILL.md

@@ -12,7 +12,8 @@ When both artifacts are drafted, control passes to `yad-review-gate`. The archit
 `risk_tags: ["contract"]` by default, which raises the review's (advisory) approver count.
 
 This skill enforces the build plan's core rules: all state lives in files; the contract holds only the
-shared cross-repo surface at charter altitude; Shape steps stay locked to `advance: human`.
+shared cross-repo surface at charter altitude; every Shape step starts at `advance: human` (a review gate
+is always human; the team sets an author step's dial with `yad dial`).
 
 ## Conventions
 
@@ -179,7 +180,7 @@ awk '/CONTRACT-SURFACE:BEGIN/{f=1;next} /CONTRACT-SURFACE:END/{f=0} f' \
 > of hash-binding.
 
 ### Step 6 — Advance the authoring step (NOT the gate)
-**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/hub.json`:
+**Check the mode first — the two modes have opposite instructions here.** Read `.sdlc/product.json` (`.sdlc/hub.json` on an older Product that has only that name):
 **verified mode** is `platform` set AND `ledger: "verified"` — or, on a project that has not run `yad migrate` yet, `bridge_enabled` (or legacy `bridge`) `true`. `ledger` wins whenever it is present.
 
 **verified mode — do NOT write `state.json`.** The ledger is CI-owned: the `ledger-guard` check rejects
@@ -212,7 +213,7 @@ the count at the active people less one, floor 1, and prints it (E72) — with 2
 ask is 1, with 3 it is 2, with 4 or more all 3 — and a shortfall never holds the gate. When the people
 cannot be counted (as in Product CI with connected repos), no cap is shown. The review PR requests no reviewers; the team asks them on the PR itself.
 **Never record approval here.** Shape steps do not auto-advance. When the Product has a platform, the gate
-opens a review PR on the Product (via `yad-hub-bridge`, labelled per touched repo) and
+opens a review PR on the Product (via `yad-product-bridge`, labelled per touched repo) and
 `yad-review-gate action: sync` pulls platform approvals/comments into the ledger; a contract re-lock
 invalidates prior platform approvals too. Otherwise the review is recorded local.
 

package/skills/yad-backfill/SKILL.md

@@ -57,17 +57,19 @@ feature: <feature>
 repo: <repo>
 artifact: backfill-spec
 status: draft
-verified: false        # not real until a human approves
+verified: false
 source: repomix         # or "repomix: unavailable" when degraded
 generated: <YYYY-MM-DD>
 ---
 ```
-Mark every uncertain item explicitly (`<!-- unverified: ... -->`); do not fill gaps with invented
-behaviour.
+`verified: false` means the spec is not real until a human approves it. Keep that line free of a `#`
+comment: the gate reads the whole line, so `verified: true   # approved` would not count. Mark every
+uncertain item explicitly (`<!-- unverified: ... -->`); do not fill gaps with invented behaviour.
 
 ### Step 4 — `approve` (human approval — reuse the gate)
 A human reads the draft against the real code and approves it with the same `advance: human` discipline
-as `yad-review-gate` (at least 1 approver who is not the author). On approval set the frontmatter `verified: true` and record
+as `yad-review-gate` (at least 1 approver who is not the author). On approval set the frontmatter line to exactly `verified: true` (lowercase, nothing after it — the
+gate reads it from the base branch, so the approval merges before the change it allows) and record
 the approver(s) + date. Only a `verified: true` backfill spec counts as real.
 
 ### Step 5 — `gate` (block changes per touched feature)
@@ -75,7 +77,11 @@ the approver(s) + date. Only a `verified: true` backfill spec counts as real.
 that feature's spec is `verified: true`. `<base>` is optional and resolves like every other gate's —
 see "Resolving `<base>`" in `../yad-checks/references/check-gates.md`. It is **per touched feature** —
 a change touching feature A is not blocked by an unverified feature B. Forward-spec'd features (those with their own `specs/<story>/`)
-are not this gate's concern.
+are not this gate's concern. The spec and its `verified: true` are read **from the base**, so an
+approval counts once it is merged — approve in its own PR, before the change (E116). A symlink or
+submodule at `src`, at `src/<feature>` or inside a feature being backfilled fails every PR until one PR
+removes it; so do two spellings of that folder at once (`src/Billing/` beside `src/billing/`) until one
+PR removes one of them.
 
 ### Step 6 — `promote` (flip a stub epic → real, once its spec is approved)
 When a brownfield feature was anchored with a **stub genesis epic** (`yad-stub`) so that defects could

package/skills/yad-backfill/references/backfill.md

@@ -64,10 +64,40 @@ A change is blocked **only until the features it touches** have approved specs
 - A feature with **no** `specs/backfill/<feature>/` is not this gate's concern (it is either
   forward-spec'd via `yad-spec`, or not yet being backfilled).
 - Fails closed on an unresolvable base ref, like the other gates.
-- A **moved** file counts at both ends (E114). The changed list is `git diff --no-renames --name-only
-  -z`, so `git mv src/<feature>/x.js lib/x.js` still touches `<feature>`; without `--no-renames` git
+- Only a frontmatter that closes counts: a spec that opens `---` and never closes it is unapproved,
+  whatever its body says. A repeated `verified:` key is read as YAML reads it: the last one wins — and any spelling YAML
+  may take for the key (`"verified":`, `verified :`, another case) counts as a later line. The last one
+  must be exactly `verified: true`, the key in lowercase.
+- A **moved** file counts at both ends (E114). The changed list is `git diff --no-renames --raw
+  -z`, each path paired with its header NUL by NUL (so a newline in one name cannot shift the rest), so `git mv src/<feature>/x.js lib/x.js` still touches `<feature>`; without `--no-renames` git
   named the move by its new path only and the feature was never checked. `-z` and `LC_ALL=C` keep an
   odd file name (a `"`, a tab, bytes that are not UTF-8) from hiding a path.
+- **The spec is read from the base** (E116), never from the PR: which features are being backfilled,
+  and whether each spec says `verified: true`. Read from the PR, a PR could approve itself (set
+  `verified: true` in the same PR) or delete the spec and read as "not being backfilled". So an approval
+  must merge before the change it allows. A spec the PR adds counts once merged. Names are compared as
+  macOS and Windows compare them: ASCII case, plus the 13 characters a Mac folds into ASCII alone
+  (U+00DF ß and U+1E9E ẞ as `ss`, U+017F ſ as `s`, U+212A Kelvin sign as `k`, the ligatures U+FB00–U+FB06
+  as their letters, U+037E and U+1FEF as `;` and `` ` ``). Other non-ASCII case (`CAFÉ`/`café`) and
+  NFC/NFD twins are not folded — a stated limit, as in contract-check: `specs/backfill/Billing/spec.md` is
+  `billing`'s spec.
+- **No link where a backfilled feature lives** (E116). The gate reads paths, so a symlink or submodule
+  at `src`, at `src/<feature>` or inside `src/<feature>/` let the code live where no path under `src/`
+  names it, and every later edit to the link's target passed. The tree at HEAD is read on every PR,
+  before the "no src/<feature> changes" PASS, and such a link is refused by name — only for a feature
+  the base is backfilling (a code repo may hold real links elsewhere in `src/`). So is a second spelling
+  of that folder at the same time (`Src/billing/` or `src/Billing/` beside `src/billing/`), which is one
+  folder on macOS and Windows but two on Linux CI; a lone `Src/` clashes with nothing and is read as
+  `src/`. **Not a dead end:** a PR that only deletes a link, or every file of one spelling while
+  another spelling stays, is not a change to the feature, so it passes. (Deleting both spellings deletes
+  the feature, and is a change to it.) A link where the spec lives on the base (`specs/backfill/<feature>` or its
+  `spec.md`) makes that feature unapproved; one at `specs` or `specs/backfill` fails every feature change
+  until a PR puts the real folder back, and meanwhile every folder under `src/` is checked for links —
+  so that PR must also remove any link under `src/` (it can come back after); the message says so.
+  **A repo that keeps `specs` as a symlink** is refused this way on every feature change until it holds
+  real files. A path that IS `src/<feature>` (a link, a submodule, or a file
+  where the folder goes) counts as that feature; a top-level `src/*.js` file still does not.
 - This script is never wired by `yad check`; each copy is placed by hand. `yad doctor` warns
   `checks:rename-blind` when a copy at `checks/backfill-check.sh` (in the Product or a connected repo)
-  is an older one that lists a rename by one path.
+  is an older one that lists a rename by one path, and `checks:backfill-blind` when it is older than
+  E116 (it reads the approval from the PR, and does not read the tree for links).

package/skills/yad-backfill/templates/checks/backfill-check.sh

@@ -3,7 +3,33 @@
 # until that feature's backfill spec is human-approved (verified: true). Gated PER touched feature, not
 # the whole repo: touching feature A is never blocked by an unverified feature B. Features that are
 # forward-spec'd (their own specs/<story>/) or not yet being backfilled are not this gate's concern.
+# The spec and its approval are read from the BASE, and a link where a backfilled feature lives is
+# refused (E116).
 set -euo pipefail
+
+# --- shared Product settings file (byte-identical across the gates; they are standalone by design, so
+# --- it is duplicated, not sourced) ---
+# The Product's settings live under two names until v5: `.sdlc/product.json`, read first from 4.0, and
+# `.sdlc/hub.json`, which an older yadflow wrote and its gates read. The environment may name the file
+# instead: SDLC_PRODUCT_CONFIG, or the older SDLC_HUB_CONFIG. Two names that say different things are
+# never settled by picking one — the CLI refuses the same way (YAD-STATE-008) — so the gate FAILS and
+# names both. Said on stderr and returned as a failure: this runs inside `$(...)`, where an `exit` would
+# only leave the subshell. `cmp -s` is byte for byte, like the CLI's own comparison.
+product_config() {
+  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ] && [ -n "${SDLC_HUB_CONFIG:-}" ] \
+    && [ "$SDLC_PRODUCT_CONFIG" != "$SDLC_HUB_CONFIG" ] && ! cmp -s "$SDLC_PRODUCT_CONFIG" "$SDLC_HUB_CONFIG"; then
+    echo "FAIL [product-settings]: SDLC_PRODUCT_CONFIG (${SDLC_PRODUCT_CONFIG}) and SDLC_HUB_CONFIG (${SDLC_HUB_CONFIG}) name files that say different things. Set only SDLC_PRODUCT_CONFIG." >&2
+    return 1
+  fi
+  if [ -n "${SDLC_PRODUCT_CONFIG:-}" ]; then printf '%s' "$SDLC_PRODUCT_CONFIG"; return 0; fi
+  if [ -n "${SDLC_HUB_CONFIG:-}" ]; then printf '%s' "$SDLC_HUB_CONFIG"; return 0; fi
+  if [ -f .sdlc/product.json ] && [ -f .sdlc/hub.json ] && ! cmp -s .sdlc/product.json .sdlc/hub.json; then
+    echo "FAIL [product-settings]: .sdlc/product.json and .sdlc/hub.json say different things — they are one file under two names until v5. Run \`yad migrate\` in the Product to choose the copy to keep, and commit both." >&2
+    return 1
+  fi
+  if [ -f .sdlc/product.json ]; then printf '%s' .sdlc/product.json; else printf '%s' .sdlc/hub.json; fi
+}
+PRODUCT_CONFIG="$(product_config)" || exit 1
 # Bytes, not characters (E114). The changed list below carries raw path bytes, and a path that is not
 # valid UTF-8 read under a UTF-8 locale is one GNU grep and sed may skip or leave unmatched — one such
 # file in a diff would hide every other path from the patterns (Linux CI). On macOS, `tr` and `sed` stop
@@ -14,7 +40,7 @@ export LC_ALL=C
 # --- is duplicated, not sourced) ---
 # With no explicit base, RESOLVE the trunk instead of assuming a hardcoded `origin/main` — on a repo
 # whose trunk is `develop`/`master` that guess either fails closed or, where a stale `main` still
-# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/hubcommit.mjs,
+# exists, silently diffs the WRONG range (issue #161). Mirrors the CLI's own order (cli/productcommit.mjs,
 # cli/repo.mjs): the CONFIGURED default_branch first, then the remote's published default
 # (origin/HEAD), then origin/main. Each candidate must actually resolve before it is used, so a
 # DANGLING origin/HEAD (trunk renamed, the old remote-tracking ref pruned) falls through to the next
@@ -23,7 +49,7 @@ export LC_ALL=C
 # command substitution in an assignment aborts the script.
 resolve_base() {
   # tr first: a key and its value may legally sit on separate lines, which a per-line match misses.
-  _cfg="$(tr -d '\n' < "${SDLC_HUB_CONFIG:-.sdlc/hub.json}" 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
+  _cfg="$({ tr -d '\n' < "$PRODUCT_CONFIG"; } 2>/dev/null | sed -nE 's/.*"default_branch"[[:space:]]*:[[:space:]]*"([^"]*)".*/\1/p')" || _cfg=""
   _head="$(git symbolic-ref --short --quiet refs/remotes/origin/HEAD 2>/dev/null)" || _head=""
   for _c in "origin/${_cfg}" "${_head}" origin/main; do
     case "$_c" in ''|origin/) continue ;; esac
@@ -39,14 +65,144 @@ if ! git rev-parse --verify --quiet "${BASE}^{commit}" >/dev/null; then
   exit 1
 fi
 
+
+# Folded as macOS and Windows fold a name (E116, as E115): `Src/` IS `src/` there, and `src/Billing/` IS
+# `src/billing/`, while git and Linux CI read exact bytes. `tolower` under LC_ALL=C folds ASCII only, so
+# every character APFS folds (full case folding, then NFD) into ASCII alone is mapped by hand, as bytes —
+# all 13 of them, from Unicode's own tables (reviews 4 and 5): ß and ẞ into `ss`, ſ into `s`, the
+# Kelvin sign into `k`, the ligatures ff fi fl ffi ffl ſt st into their letters, and the Greek question mark and
+# varia into `;` and `` ` ``. So `src/claß/` IS `src/class/` on a Mac, and is read so here. Not folded,
+# and stated: characters that fold into other non-ASCII ones (`CAFÉ` is `café` on a Mac) and NFC/NFD
+# twins; awk cannot fold them, and refusing every non-ASCII feature name would refuse real repos (E115
+# made the same call).
+FOLD='function fold(x) { x = tolower(x)
+  gsub(/\303\237|\341\272\236/, "ss", x); gsub(/\305\277/, "s", x); gsub(/\342\204\252/, "k", x)
+  gsub(/\357\254\200/, "ff", x); gsub(/\357\254\201/, "fi", x); gsub(/\357\254\202/, "fl", x)
+  gsub(/\357\254\203/, "ffi", x); gsub(/\357\254\204/, "ffl", x); gsub(/\357\254\205|\357\254\206/, "st", x)
+  gsub(/\315\276/, ";", x); gsub(/\341\277\257/, "`", x); return x }'
+
+# Which features are being backfilled is read from the BASE, never from the PR (E116). Read from the
+# PR, the gate let a PR approve itself: it could set `verified: true` in the same PR, or delete the spec
+# so the feature read as "not being backfilled". So a spec, and its approval, count once they are merged.
+# The whole tree, folded: on a Mac checkout `Specs/backfill/Billing/spec.md` is the spec of `billing`.
+# A symlink or submodule where the specs live hides what the spec says: at `specs/backfill/<f>` or its
+# spec.md, <f> counts as being backfilled and unapproved; at `specs` or `specs/backfill`, the gate cannot
+# tell which features are, so every src/<feature> change fails until one PR puts real files back (that PR
+# changes no feature, so it passes).
+# `tr '\n\0' '?\n'`: one record per line, and a newline inside a path becomes `?` — split on newlines
+# alone, a file named `notes<newline>100644 blob 0<TAB>src/Billing/y` added a record nobody made (review 2).
+base_tree="$(git ls-tree -r -z --full-tree "$BASE" | tr '\n\0' '?\n')" || {
+  echo "FAIL [backfill]: git could not read the tree of '${BASE}' — the gate cannot tell which features are being backfilled."
+  exit 1
+}
+# One line each: `S <oid> <path>` a spec to read, `U - <path>` a link where a spec goes, `A - <path>` a
+# link above. A spec is read by its object id, never by its path again: with a newline written as `?`,
+# `x?y/spec.md` and `x<newline>y/spec.md` are one path here, and reading `<base>:x?y/spec.md` twice let
+# an approved spec stand in for an unapproved one (review 3).
+specs="$(printf '%s\n' "$base_tree" | awk "$FOLD"'
+  { t = index($0, "\t"); if (!t) next; p = substr($0, t + 1); m = substr($0, 1, 6); lp = fold(p); split(substr($0, 1, t - 1), h, " ") }
+  lp !~ /^specs(\/backfill(\/[^\/]+(\/spec\.md)?)?)?$/ { next }
+  m == "120000" || m == "160000" { print (lp ~ /^specs\/backfill\/[^\/]+/ ? "U - " : "A - ") p; next }
+  lp ~ /^specs\/backfill\/[^\/]+\/spec\.md$/ { print "S " h[3] " " p }
+')"
+blind="$(printf '%s\n' "$specs" | sed -n 's/^A - //p')"
+# The folded names of the features being backfilled, one per line.
+bf="$(printf '%s\n' "$specs" | sed -n 's/^[SU] [^ ]* //p' | awk "$FOLD"'{ split($0, c, "/"); print fold(c[3]) }' | sort -u)"
+
+# No symlink, no submodule and no second spelling where a feature being backfilled lives (E116). The
+# gate reads PATHS: with a link at `src/<feature>` (or `src`, or inside the feature) the code lives
+# where no path under src/ names it, so every later edit to the link's target passed. Read from the tree
+# at HEAD, on EVERY PR and before the "no src/<feature> changes" PASS — an edit to the target changes no
+# path under src/ at all. Links elsewhere in src/ are not this gate's concern: a code repo may hold real
+# ones. 120000 is a symlink, 160000 a submodule; `-r` lists `src` itself when `src` is the link. When
+# the base hides its specs behind a link (`blind`), every folder under src/ is taken as backfilled here.
+# A second spelling is two spellings of one folder at HEAD at once (`Src/billing/` beside `src/billing/`,
+# or `src/Billing/` beside it): one folder on macOS and Windows, two on Linux CI. A lone `Src/` clashes
+# with nothing, and is read as `src/`.
+# Lists go to awk IN the stream, each line tagged, never through the environment: a list of every
+# src/ folder passed as a variable hit the size limit ("Argument list too long") in a large repo and
+# failed every PR there (review 2). `tagged T "$list"` prints `T<TAB><line>` for each line that is not
+# empty.
+tagged() { printf '%s\n' "$2" | awk -v t="$1" 'length($0) { print t "\t" $0 }'; }
+head_tree="$(git ls-tree -r -z --full-tree HEAD | tr '\n\0' '?\n')" || {
+  echo "FAIL [backfill]: git could not read the tree at HEAD — the gate cannot check src/ for links."
+  exit 1
+}
+if [ -n "$bf" ] || [ -n "$blind" ]; then
+  bad="$({ tagged B "$bf"; printf '%s\n' "$head_tree"; } | ALL="${blind:+1}" awk "$FOLD"'
+    function once(k, s) { if (!(k in done)) { done[k] = 1; print "  " s } }
+    BEGIN { all = (ENVIRON["ALL"] != "") }
+    /^B\t/ { bf[substr($0, 3)] = 1; next }
+    { t = index($0, "\t"); if (!t) next; p = substr($0, t + 1); m = substr($0, 1, 6); lp = fold(p); ln = (m == "120000" || m == "160000") }
+    lp == "src" && ln { print "  " p (m == "120000" ? " (a symlink" : " (a submodule") ", where the src/ folder goes)"; next }
+    lp !~ /^src\// { next }
+    { split(p, c, "/"); f = fold(c[2]) }
+    !all && !(f in bf) { next }
+    { s = c[1] "/" c[2] }
+    (f in sp) && sp[f] != s { once("f/" f "/" s, sp[f] " and " s " (one name on macOS and Windows)") }
+    !(f in sp) { sp[f] = s }
+    m == "120000" { print "  " p " (symlink)"; next }
+    m == "160000" { print "  " p " (submodule)"; next }
+  ')"
+  if [ -n "$bad" ]; then
+    echo "FAIL [backfill]: src/ holds a symlink, a submodule or a second spelling where a feature being backfilled lives — this gate cannot see what changes behind it:"
+    printf '%s\n' "$bad"
+    echo "  -> put the real files in place of each link, and keep one spelling of each folder. A PR that only"
+    echo "     removes a link, or every file of one spelling, passes; until then every PR in this repo fails,"
+    echo "     because an edit to the link's target changes no path under src/."
+    if [ -n "$blind" ]; then
+      echo "     On the base, $(printf '%s' "$blind" | head -n 1) is a symlink or submodule, so the gate cannot tell which"
+      echo "     features are being backfilled and checks EVERY folder under src/ — a link above may belong to no"
+      echo "     backfilled feature. Remove it in the PR that puts the real specs back; add it back after."
+    fi
+    exit 1
+  fi
+fi
+
 # --no-renames (E114): a rename is listed by BOTH paths. Without it git names a rename by its NEW path
 # only, so `git mv src/<feature>/x.js lib/x.js` took the file out of a feature being backfilled and the
 # gate never saw the feature. -z | tr: NUL-separated, so git never quotes a path — a quoted one (any
-# non-ASCII byte by default; a `"` or a tab always) never matched src/<feature>/ below.
-changed="$(git diff --no-renames --name-only -z "${BASE}..HEAD" | tr '\0' '\n')"
-# Feature = a directory under src/ (src/<feature>/...). Top-level src/*.js files are deliberately NOT
-# gated here (they belong to no single feature); only src/<feature>/ changes are checked.
-feats="$(printf '%s\n' "$changed" | sed -nE 's#^src/([^/]+)/.*#\1#p' | sort -u)"
+# non-ASCII byte by default; a `"` or a tab always) never matched src/<feature>/ below. --raw gives each
+# path after a record with its modes and status; with --no-renames every change has exactly one path.
+# The two are paired here, NUL by NUL, into one line — `<modes and status><TAB><path>` — and a newline
+# inside a path becomes `?`: split into lines first, one file named `a<newline>b` put every later header
+# where its path should be, and every src/<feature> change after it was never seen (review 1).
+changed="$(git diff --no-renames --raw -z "${BASE}..HEAD" | while IFS= read -r -d '' h && IFS= read -r -d '' p; do
+  printf '%s\t%s\n' "$h" "${p//$'\n'/?}"
+done)" || {
+  echo "FAIL [backfill]: git could not list the changes between '${BASE}' and HEAD."
+  exit 1
+}
+# The spellings of each src/<feature> folder, on the base and at HEAD: `<top>/<feature>`, once each.
+spellings() {
+  awk "$FOLD"'{ t = index($0, "\t"); if (!t) next; p = substr($0, t + 1); if (fold(p) !~ /^src\/[^\/]+\//) next
+    split(p, c, "/"); s = c[1] "/" c[2]; if (!(s in seen)) { seen[s] = 1; print s } }'
+}
+base_sp="$(printf '%s\n' "$base_tree" | spellings)"
+head_sp="$(printf '%s\n' "$head_tree" | spellings)"
+# Feature = a directory under src/ (src/<feature>/...), folded (E116). A path that IS `src/<feature>` — a
+# link, a submodule or a file put where the folder goes — is that feature too. Top-level src/*.js files
+# are deliberately NOT gated here (they belong to no single feature), so a path that IS `src/<name>`
+# counts only as a link or a submodule (either side), or when <name> is being backfilled. A deleted
+# symlink or submodule is not a change to the feature: removing the link is how a repo gets out of the
+# refusal above, and the spec's approval may itself be waiting on that PR. For the same reason a file
+# deleted from one spelling of a folder the base held in two, when that spelling is gone at HEAD, is not
+# a change either (review 1): without it, neither removing the twin nor approving the spec could pass.
+# Only while ANOTHER spelling of that folder is still there at HEAD (review 2): deleting both spellings
+# deletes the feature, and that is a change to it. (A diff header starts with `:`, so the tags below
+# cannot be mistaken for one.)
+feats="$({ tagged B "$bf"; tagged S "$base_sp"; tagged H "$head_sp"; printf '%s\n' "$changed"; } | awk "$FOLD"'
+  /^B\t/ { bf[substr($0, 3)] = 1; next }
+  /^S\t/ { cnt[fold(substr($0, 3))]++; next }
+  /^H\t/ { here[substr($0, 3)] = 1; still[fold(substr($0, 3))] = 1; next }
+  { t = index($0, "\t"); if (!t) next; h = substr($0, 1, t - 1); p = substr($0, t + 1); lp = fold(p) }
+  lp !~ /^src\/./ { next }
+  { split(h, w, " "); om = substr(w[1], 2); nm = w[2]; ln = (om ~ /^1[26]0000$/ || nm ~ /^1[26]0000$/) }
+  w[5] == "D" && ln { next }
+  { k = split(p, c, "/"); f = fold(c[2]); s = c[1] "/" c[2] }
+  w[5] == "D" && k > 2 && cnt[fold(s)] > 1 && !(s in here) && (fold(s) in still) { next }
+  k > 2 || ln || (f in bf) { print f }
+' | sort -u)"
 
 if [ -z "$feats" ]; then
   echo "PASS [backfill]: no src/<feature> changes."
@@ -56,18 +212,45 @@ fi
 rc=0
 while IFS= read -r f; do
   [ -z "$f" ] && continue
-  spec="specs/backfill/${f}/spec.md"
-  [ -f "$spec" ] || { echo "note [backfill]: ${f} is not being backfilled (no ${spec}) — skipped."; continue; }
-  # Read ONLY the YAML frontmatter (between the first two --- lines) so a prose line that merely
-  # contains "verified: true" cannot false-pass the gate.
-  fm="$(awk 'NR==1 && /^---[[:space:]]*$/ {f=1; next} f && /^---[[:space:]]*$/ {exit} f {print}' "$spec")"
-  if printf '%s\n' "$fm" | grep -qiE '^verified:[[:space:]]*true[[:space:]]*$'; then
-    echo "PASS [backfill]: ${f} has an approved (verified) backfill spec."
-  else
-    echo "FAIL [backfill]: ${f} is being backfilled but its spec is not yet human-approved (verified: true)."
-    echo "  -> run yad-backfill approve for ${spec} before changing this feature."
+  if [ -n "$blind" ]; then
+    echo "FAIL [backfill]: cannot tell whether ${f} is being backfilled — on the base, $(printf '%s' "$blind" | head -n 1) is a symlink or submodule, so the specs behind it are not read."
+    echo "  -> put the real specs/backfill/ folder back in its own PR first."
     rc=1
+    continue
   fi
+  mine="$(printf '%s\n' "$specs" | F="$f" awk "$FOLD"'/^[SU] / { r = substr($0, 3); split(substr(r, index(r, " ") + 1), c, "/"); if (fold(c[3]) == ENVIRON["F"]) print }')"
+  if [ -z "$mine" ]; then
+    echo "note [backfill]: ${f} is not being backfilled (no specs/backfill/${f}/spec.md on the base) — skipped."
+    continue
+  fi
+  ok=1
+  while IFS= read -r l; do
+    rest="${l#? }"; oid="${rest%% *}"; spec="${rest#* }"
+    case "$l" in
+      U\ *) echo "FAIL [backfill]: ${f} is being backfilled, but on the base ${spec} is a symlink or submodule — its spec is not read."
+            echo "  -> put the real spec there in its own PR first."
+            ok=0; continue ;;
+    esac
+    # Read ONLY the YAML frontmatter (between the first two --- lines) so a prose line that merely
+    # contains "verified: true" cannot false-pass the gate — and only once it closes: a spec that opens
+    # `---` and never closes it has no frontmatter, or a body line would count (review 5). Read to the end,
+    # never stopped early: under pipefail a closed pipe would read a long approved spec as unapproved.
+    fm="$(git cat-file blob "$oid" 2>/dev/null | awk 'NR==1 && /^---[[:space:]]*$/ {f=1; next} f==1 && /^---[[:space:]]*$/ {f=2; next} f==1 {b = b $0 "\n"} END {if (f == 2) printf "%s", b}')" || fm=""
+    # The LAST line that could set the key, as YAML reads a repeated key (review 6): `true` then `false`
+    # is false. Any spelling YAML might take for it — quoted, a space before the colon, another case —
+    # is found (review 7), and the last one must be exactly `verified: true` (the key in lowercase, as
+    # YAML keys are case-sensitive; the value as YAML 1.1 reads it). Anything else is not approved.
+    last="$(printf '%s\n' "$fm" | grep -iE "^[\"']?verified[\"']?[[:space:]]*:" | tail -n 1)" || last=""
+    if ! printf '%s\n' "$last" | grep -qE '^verified:[[:space:]]*(true|True|TRUE)[[:space:]]*$'; then
+      echo "FAIL [backfill]: ${f} is being backfilled but its spec is not yet human-approved (verified: true) on the base."
+      echo "  -> run yad-backfill approve for ${spec} and merge that first: the gate reads the spec"
+      echo "     as it stands on the base, so an approval in this same PR does not count."
+      ok=0
+    fi
+  done <<EOF
+$mine
+EOF
+  if [ "$ok" = 1 ]; then echo "PASS [backfill]: ${f} has an approved (verified) backfill spec."; else rc=1; fi
 done <<EOF
 $feats
 EOF

package/skills/yad-change/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: yad-change
-description: 'Phase 6 post-lock change management — the change-request/defect INTAKE + TRIAGE step of a feature thread. After the contract locks and code ships, a change must NOT mutate a locked artifact; it becomes a NEW epic threaded to its parent. This skill classifies the change DEPTH (defect-fix / behavioral-no-surface / contract-surface / new-capability), seeds a new EP-<slug> change-epic threaded to its parent (lineage frontmatter kind+type/parent/thread/inherits/supersedes; then `yad epic new --parent` writes the state.json whose inherited steps are carried by reference and only the changed steps run, plus a pointer-lock contract-lock.json when architecture is inherited), and records the intake in change.json (escape_stage + root_cause for defects). For hotfixes it records the ship-first exception and opens reconcile-debt.json. Never auto-advances — hands off to the normal authoring skills + the team review gate. Use when the user says "log a change request", "file a defect", "thread a change off EP-…", "open a hotfix", or after a shipped feature needs a fix.'
+description: 'Phase 6 post-lock change management — the change-request/defect INTAKE + TRIAGE step of a feature thread. After the contract locks and code ships, a change must NOT mutate a locked artifact; it becomes a NEW epic threaded to its parent. Classifies the change DEPTH (defect-fix / behavioral-no-surface / contract-surface / new-capability), seeds that EP-<slug> change-epic (lineage frontmatter kind+type/parent/thread/inherits/supersedes; `yad epic new --parent` writes a state.json that carries inherited steps by reference and runs only the changed ones, plus a pointer-lock contract-lock.json when architecture is inherited), and records the intake in change.json (escape_stage + root_cause for defects). For hotfixes it records the ship-first exception and opens reconcile-debt.json. Never auto-advances — hands off to the authoring skills + the team review gate. Use when the user says "log a change request", "file a defect", "thread a change off EP-…", "open a hotfix", or after a shipped feature needs a fix.'
 ---
 
 # SDLC — Change/Defect Intake + Triage (Phase 6, the entry of a feature thread)