Approval Gates: extend to non-ALM skills + plugin-wide hard-fail lint

[T-Nid (tyaginidhi)]

Summary

Extends the Approval Gate pattern from §6.1–§6.12 (12 ALM skills) to cover all 25 user-invocable power-pages skills, flips lint enforcement to hard-fail across the whole plugin, and closes 16 pre-existing catalog orphans.

• 45 new gates + 9 not-a-gates in 12 non-ALM skills (create-site, deploy-site, add-server-logic, add-cloud-flow, setup-auth, integrate-webapi, setup-datamodel, add-sample-data, add-seo, create-webroles, audit-permissions, integrate-backend) — catalogued in §6.13–§6.24.
• 3 new gates + 2 not-a-gates in the 4 security skills picked up during rebase (manage-firewall, manage-headers, scan-site, security-review) — catalogued in §6.24a + §6.25–§6.28. §6.24a documents the runtime-loop prompt convention these skills use.
• 4 new gates in the add-ai-webapi skill introduced by PR [Pages] Add skill for ai webapi #144 — catalogued in §6.29. Covers: iteration-mode batched deploy+commit prompt (iter.deploy-commit), skip-web-role trade-off confirmation (4.2.skip-webrole), Phase 5 commit offer (5.5.commit), Phase 6 Summarization/* settings commit offer (6.4.commit).
• scripts/lint-skills-alm.js warn-only branch removed. severityForSkill() (now SKILL_SEVERITY constant) returns 'error' for every skill. Test updated. Dead warnings-only branch in main() removed. m <= promptLine tightened to m < promptLine. CATALOG_GATE_ID_PATTERN made case-insensitive to align with GATE_MARKER_PATTERN. Two new rules added: CATALOG-row-must-have-marker (reverse check — catalog rows must have a matching SKILL.md marker) and GATE-prose-block-required (every marker must be followed within 10 lines by a 🚦 sentinel). Lint now enforces 7 gate-related rules plugin-wide.
• AGENTS.md Key Patterns generalized — Approval Gate convention applies plugin-wide; new skills must extend the catalog in the same PR that introduces a prompt. PLUGIN_DEVELOPMENT_GUIDE.md:273 updated to list all seven enforced rules.
• 16 pre-existing ALM catalog orphans closed — see commit 1011030 for the per-row resolution. Some got new markers (test-site:5.5.form-submit, setup-pipeline:4.3.name-conflict, etc.); others were removed from the catalog as redundant or unimplemented (deploy-pipeline:6.1.pac-fallback-consent, configure-env-variables:6.confirm-matrix, force-link-environment:2.host-fallback/2.dev-fallback).
• readSettingsFile bug fix — now handles all three deployment-settings.json shapes (top-level / Stages: [] array / stages: {} keyed object), with preserveAllStages mode to validate every per-stage entry. Fixes a silent validation pass for the Microsoft deployment-settings/2024 schema shape.
• Markdown rendering polish — 6 spots where gate marker blocks were splitting numbered lists are fixed (marker now precedes the list). Stray ``` tokens at add-cloud-flow:346 and `integrate-backend:271` (from PR Power Pages ALM: 10 new skills + 45 helpers + 6 reference docs for site-to-pipeline lifecycle #167) removed.
• CI workflows kept deliberately separate — added header comments to .github/workflows/power-pages-alm-lint.yml and power-pages-script-tests.yml explaining why.

Test plan

• node plugins/power-pages/scripts/lint-skills-alm.js → alm-lint: 0 findings
• node --test plugins/power-pages/scripts/tests/*.test.js → 1108/1108 passing
• Catalog completeness — every <!-- gate: --> marker in SKILL.md has a backticked catalog row in references/approval-gates.md; the previous orphan ALM rows are resolved (marker added or row removed).
• Markdown polish — 6 list-breakage spots fixed; 2 stray ``` tokens removed.
• Live exercise of /power-pages:plan-alm end-to-end against a real tenant to confirm the new plan-alm:2.q4-host marker fires.
• Live exercise of /power-pages:ensure-pipelines-host against a NoHost tenant to confirm the 3.C / 4.0 / 4.A / 4.C markers fire as expected.

Notes

This is a draft PR while live-tenant validation is pending. The structural changes (markers, catalog, lint) are complete and verified; the runtime gate firing remains to be confirmed against real flows.

🤖 Generated with Claude Code

[T-Nid (tyaginidhi)]

Addressed all 9 review items in commit 8d02547. Summary:

Lint hardening:

• ✅ Reverted accidental underscore widening in CATALOG_GATE_ID_PATTERN (kept case-insensitivity).
• ✅ Added CATALOG-row-must-have-marker reverse rule — catches orphan catalog rows that v3 closed by hand. Same machinery, inverted check.
• ✅ Added GATE-prose-block-required — every marker must be followed by a 🚦 sentinel within 10 lines. Minimum-viable check against prose-block deletion.
• ✅ Strict precede: m < promptLine (was <=). New test pins the behavior.
• ✅ Removed dead ALM_SKILLS export + its membership test.
• ✅ Simplified the wishful "future per-skill policy" comment.

Catalog clarifications:

• ✅ §3.2 plan: paragraph explaining why deploy-dispatch prompts are plan (the destructive consent lives inside the dispatched skill).
• ✅ §11 caveats: phase-number drift convention; lint-prose-block weakness (only 🚦 enforced, not the 3 structured labels); runtime-loop coverage hole status.
• ✅ §10: cross-plugin lint TODO for shared/skills/report-issue/.
• ✅ Removed archaeological commentary in §6.4 / §6.7 / §6.9.

Runtime-loop coverage hole — CLOSED:

• ✅ manage-firewall:3.action-choice (plan) + manage-firewall:3.execute-consent (consent) — destructive WAF mutations are now lint-anchored.
• ✅ scan-site:3.action-choice (plan) — scan-trigger decision is now lint-anchored.
• §6.24a updated to reflect resolution.

Field rename:

• ✅ Blast radius if skipped: → Why we ask: across all 60 prose blocks + §4.1 template.

Verified: node plugins/power-pages/scripts/lint-skills-alm.js → 0 findings (with new reverse + prose-block rules active); 984/984 plugin tests pass.

Still pending (post-merge):

• Live-tenant exercises for plan-alm:2.q4-host (renamed) and the new ensure-pipelines-host:3.C.* / 4.0 / 4.A / 4.C markers. The structural review is unblocked; runtime validation happens against a real tenant before/after merge.

[Copilot]

Pull request overview

This PR extends the Power Pages “Approval Gates” pattern and catalog coverage from ALM-only skills to all user-invocable power-pages skills, and updates the linter to hard-fail plugin-wide when gate markers/catalog drift occurs.

Changes:

• Added <!-- gate: ... --> / <!-- not-a-gate: ... --> markers (plus 🚦 prose blocks) across non-ALM and security skills to fully cover AskUserQuestion call sites.
• Updated scripts/lint-skills-alm.js to enforce gate/catalog rules at error severity for every skill, and added new drift-prevention rules.
• Updated reference docs and contributor guidance (approval-gates.md, AGENTS.md, PLUGIN_DEVELOPMENT_GUIDE.md) plus workflow headers to reflect plugin-wide enforcement.

Reviewed changes

Copilot reviewed 29 out of 29 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
plugins/power-pages/skills/test-site/SKILL.md	Adds a consent gate for live form submission testing.
plugins/power-pages/skills/setup-pipeline/SKILL.md	Adds planning gates for pipeline name conflicts and v2→v3 manifest migration decisions.
plugins/power-pages/skills/setup-datamodel/SKILL.md	Adds plan gates for model source selection and pre-write approval.
plugins/power-pages/skills/setup-auth/SKILL.md	Adds multiple plan gates for deploy prerequisites, web role creation, requirements, plan approval, and deploy dispatch.
plugins/power-pages/skills/security-review/SKILL.md	Adds plan gates for goal selection and post-report next action.
plugins/power-pages/skills/scan-site/SKILL.md	Anchors the action-choice prompt as a plan gate; adds a not-a-gate marker for meta option rules.
plugins/power-pages/skills/plan-alm/SKILL.md	Adds a plan gate for host environment selection (Q4 host).
plugins/power-pages/skills/manage-headers/SKILL.md	Adds a plan gate for the per-finding accept/customize/skip loop.
plugins/power-pages/skills/manage-firewall/SKILL.md	Adds a plan gate for action selection and a consent gate before destructive firewall mutations; adds not-a-gate meta marker.
plugins/power-pages/skills/integrate-webapi/SKILL.md	Adds plan gates for table confirmation, deploy prerequisite, permissions source/approval, and deploy dispatch.
plugins/power-pages/skills/integrate-backend/SKILL.md	Adds a plan-approval gate before dispatching to child integration skills; removes stray markdown token.
plugins/power-pages/skills/force-link-environment/SKILL.md	Converts prior not-a-gate placeholders into explicit plan gates for host/dev env resolution prompts.
plugins/power-pages/skills/export-solution/SKILL.md	Adds plan gates for solution identification (when manifest missing) and overwrite/name decision.
plugins/power-pages/skills/ensure-pipelines-host/SKILL.md	Adds plan/consent/progress gates for NoHost routing, provisioning confirmations, sandbox reconfirm, and PPAC manual completion.
plugins/power-pages/skills/deploy-site/SKILL.md	Adds consent/plan gates for environment confirmation, multi-project selection, optional audit, activation prompt, cache restart, and blockedattachments change.
plugins/power-pages/skills/create-webroles/SKILL.md	Adds plan gates for deploy prerequisite, role selection, and deploy dispatch.
plugins/power-pages/skills/create-site/SKILL.md	Adds plan gates for purpose/requirements/plan approval/review/deploy dispatch; adds not-a-gate marker for protocol prose.
plugins/power-pages/skills/audit-permissions/SKILL.md	Adds a plan gate for offering auto-fixes after report generation.
plugins/power-pages/skills/add-server-logic/SKILL.md	Adds plan gates for deploy prerequisite, custom actions usage, Key Vault decision, plan approval, no-vaults branch, frontend scope, deploy/test dispatch; adds not-a-gate markers for sub-prompts.
plugins/power-pages/skills/add-seo/SKILL.md	Adds not-a-gate markers for data-gathering prompts and a plan-approval gate before writing SEO artifacts.
plugins/power-pages/skills/add-sample-data/SKILL.md	Adds plan gates for table selection and record count selection.
plugins/power-pages/skills/add-cloud-flow/SKILL.md	Adds plan gates for deploy prerequisite, flow selection, plan approval, deploy/test dispatch; removes stray markdown token; adds not-a-gate marker for scenario clarification.
plugins/power-pages/scripts/tests/lint-skills-alm.test.js	Updates tests to reflect plugin-wide hard-fail severity and stricter “marker must precede prompt line” behavior.
plugins/power-pages/scripts/lint-skills-alm.js	Removes ALM/non-ALM severity split; tightens pairing logic; makes catalog parsing more permissive; adds reverse catalog completeness and prose-block drift checks; simplifies output to error-only.
plugins/power-pages/references/approval-gates.md	Expands catalog to all skills, updates terminology/landing history, and documents new gate coverage patterns.
plugins/power-pages/PLUGIN_DEVELOPMENT_GUIDE.md	Updates contributor guidance to reflect plugin-wide gate enforcement (no ALM carve-out).
plugins/power-pages/AGENTS.md	Updates key patterns/reference doc description to reflect plugin-wide approval gate cataloging and enforcement.
.github/workflows/power-pages-script-tests.yml	Adds header comments explaining workflow separation and intent.
.github/workflows/power-pages-alm-lint.yml	Adds header comments explaining workflow separation and intent.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 29 out of 29 changed files in this pull request and generated 4 comments.

Comments suppressed due to low confidence (1)

plugins/power-pages/scripts/lint-skills-alm.js:93

• The usage header still describes a warnings-vs-errors split (exit 0 when only warnings; stdout lists warnings). In v3, main() now treats every finding as severity: 'error' and always exits 1 if there are any findings. Please update this usage comment to match the current behavior (or reintroduce the warning path).

// Usage:
//   node scripts/lint-skills-alm.js [--plugin-root <path>]
//   Exit 0 when no findings (or only warnings); exit 1 when at least one
//   finding has severity 'error'. stderr lists errors; stdout lists warnings.
//

[T-Nid (tyaginidhi)]

Addressed all 10 review-skill findings + 9 Copilot inline comments in commit `b42ddc6`. Also picked up Copilot Autofix commit `f4c8ced` on the rule-count wording (rebased onto it, kept the more detailed version).

Lint script

Robustness:

• ✅ `CATALOG_GATE_ROW_PATTERN` now tolerates up to 3 leading spaces (GFM table indentation). Was `^|`, now `^\s{0,3}|`.
• ✅ `GATE-prose-block-required` window now includes the marker's own line — single-line compact markers pass.
• ✅ `GATE-prose-block-required` 🚦 search is now code-fence-aware — a literal 🚦 inside a ```bash``` example no longer satisfies the rule.
• ✅ `main()` uses single `process.stderr.write` + `process.exitCode` (was multiple sync writes + `process.exit`) — fixes potential stderr truncation on Windows piped output.

Docstring fix (Copilot inline #1):

• ✅ `CATALOG-row-must-have-marker` docstring updated. The old text promised inline `` waiver that the implementation never honored. New docstring states `.almlintignore` is the only suppression mechanism (consistent with actual behavior).

Cleanups:

• ✅ Removed dead `skillNameFromFile()` function (no callers).
• ✅ Removed half-applied `SKILL_SEVERITY` constant — inlined `'error'` everywhere.
• ✅ Updated stale Usage header comment (Copilot inline Update skills and marketplace #2) to match v3 exit-code behavior.

Tests (Copilot inline #3 + review-skill finding #1)

Added 7 new tests for the two rules introduced in commit `8d02547` that shipped with zero coverage:

CATALOG-row-must-have-marker:

• ✅ fires when a catalog gate row has no SKILL.md marker
• ✅ passes when every gate row has a marker
• ✅ skips not-a-gate rows
• ✅ tolerates GFM leading whitespace on table rows

GATE-prose-block-required:

• ✅ fires when marker has no 🚦 within 10 lines
• ✅ passes when 🚦 sentinel follows within window
• ✅ ignores 🚦 inside a fenced code block
• ✅ tolerates 🚦 on the same line as the marker

Test count: 45 → 52 (+7). Plugin-wide: 984 → 992. Lint: 0 findings.

Docs (Copilot inline #4–#7)

• ✅ `approval-gates.md` intro, `AGENTS.md` ~244, `PLUGIN_DEVELOPMENT_GUIDE.md` ~273: updated "five GATE rules" → "seven gate-related rules" and enumerated all 7 (Copilot Autofix `f4c8ced` covered the first; I expanded the wording in each location to list the new rules with brief inline descriptions).
• ✅ `approval-gates.md` §9 Decisions row 4: marked the v2 "ALM: hard-fail. Non-ALM: warn-only" decision as `[v2 — superseded by §10]`. The history was correct in §10 but §9 read as a current recommendation.

Verified

```
node plugins/power-pages/scripts/lint-skills-alm.js → 0 findings
node --test plugins/power-pages/scripts/tests/ → 992 / 992 passing
```

[T-Nid (tyaginidhi)]

Real-world validation against `C:\Projects\Citizens portal` — found and fixed a pre-existing high-impact bug.

Pushed `371a6e1` fixing `readSettingsFile` to handle the keyed-object stages shape that the actual Microsoft `deployment-settings/2024` schema uses.

What I found

Citizens portal's `deployment-settings.json` uses:

```json
{
"$schema": "https://schemas.microsoft.com/power-platform/deployment-settings/2024",
"stages": {
"Deploy to Staging": {
"EnvironmentVariables": [...]
}
}
}
```

But `readSettingsFile` only handled two shapes (top-level `EnvironmentVariables: []` and array-shaped `Stages: []`). For the keyed-object shape it returned 0 entries, which meant `validate-deployment-settings.js` silently passed even on known-broken values.

Why it matters

The Citizens portal's `docs/alm/last-deploy.json` documents a deploy attempt on 2026-05-21 where `@KeyVault(vaultName=...;secretName=...)` for `c311_api_secret` slipped past validation and failed at ImportAsHolding after ~4 hours of queue wait. The v3 `deploy-pipeline:7.6.4.strip-secret-values` gate is supposed to catch exactly this case at sub-second time — but the gate's underlying validator was broken by this shape mismatch.

The fix

• `readSettingsFile` now handles all three deployment-settings.json shapes (top-level / `Stages: []` array / `stages: {}` keyed object). Each entry now carries `stageLabel` for downstream attribution.
• Deleted the duplicate `readEntriesPreservingStage` parser in `validate-deployment-settings.js` (had the same bug). Now calls the unified `readSettingsFile`.

Verified end-to-end

```bash
$ node validate-deployment-settings.js --settingsFile "C:\Projects\Citizens portal\deployment-settings.json"
{
"summary": { "total": 2, "valid": 0, "invalid": 1, "unknown-type": 1, "skipped": 0 },
"findings": [
{ "schemaName": "c311_api_secret",
"stageLabel": "Deploy to Staging",
"value": "KeyVault (@KeyVault)(vaultName=lakeshore-staging-kv;secretName=api-secret)",
"valueFormat": "kv-placeholder",
"status": "invalid",
"severity": "error",
"message": "...not a recognized syntax for any env var type. If it's intended as a Key Vault reference, use the Secret Identifier URI or Azure resource ID format..." }
]
}
```

This is exactly the finding that would have prevented the 4h queue wait.

Tests + lint

• 993/993 plugin tests pass (was 992; +1 new shape-3 test against a fixture matching the Citizens portal file).
• `alm-lint` 0 findings.
• 2 existing tests updated to expect the new `stageLabel` field on entries.

Other Citizens portal validations (all passed)

• ✅ `detect-project-context.js` reads the v2 multi-solution manifest correctly (5 solutions, publisher prefix `c311`).
• ✅ `check-alm-plan.js` correctly reports `exists:true / stale:false / planStatus:Completed / inExecution:not-running` against `docs/.alm-plan-data.json` — Phase 0 gates would correctly pass through silently.
• ✅ `docs/alm/last-pipeline.json` is v3 multi-solution (5 solutions in deploymentOrder); the v3 `setup-pipeline:6b.v2-migration` gate wouldn't fire here (already on v3), correctly.
• ✅ `docs/alm/last-deploy.json` schema matches what `deploy-pipeline` markers reference (`stageRunId`, `pipelineId`, `status`, `runs[]` per solution).
• ✅ `.powerpages-site/web-roles/` exists with 3 roles (Administrators, Anonymous Users, Authenticated Users) — `setup-auth:1.4.create-webroles` gate wouldn't fire (roles already exist).
• ✅ Multi-stage v3 pipeline (Foundation, Integration, Config, Content, Future) — exactly the MULTI_RUN_MODE scenario `deploy-pipeline:3.6.batch-pending-approval` is designed for.

Branch is now at `371a6e1` — 6 commits ahead of `origin/main`.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 2 comments.

[Copilot]

Pull request overview

Copilot reviewed 33 out of 33 changed files in this pull request and generated 2 comments.

[T-Nid (tyaginidhi)]

Copilot resolve the merge conflicts in this pull request

[Copilot]

Copilot resolve the merge conflicts in this pull request

Resolved in commit 9810f4a. There was one conflict in plugins/power-pages/skills/setup-auth/SKILL.md at section 2.1 — the PR branch had added the <!-- gate: setup-auth:2.1.requirements --> marker + 🚦 prose block, while main (b4c46e9) had added a substantial re-run handling / multi-provider walkthrough in the same spot. The resolution keeps the gate marker first, then incorporates the full new content from main. Verified: alm-lint: 0 findings, 1042/1042 tests passing.

[T-Nid (tyaginidhi)]

Copilot resolve the merge conflicts in this pull request

[Copilot]

Copilot resolve the merge conflicts in this pull request

Resolved in commit 25e1ca0. Two files conflicted (create-webroles/SKILL.md, integrate-webapi/SKILL.md) — kept the existing gate markers from the branch and incorporated the caller-suppress / AI-only-read-mode conditionals added by main (#144). The new add-ai-webapi skill brought in by main had 4 unmarked AskUserQuestion call sites that failed GATE-must-have-marker; added gate markers + 🚦 prose blocks for iter.deploy-commit, 4.2.skip-webrole, 5.5.commit, and 6.4.commit, plus §6.29 catalog rows. Verified: alm-lint: 0 findings, 1108/1108 tests pass.