@windyroad/itil 1.2.0 → 2.0.0-preview.1111

package/skills-codex/review-problems/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Review Problems"
+  short_description: "Reassess and reprioritise the problem backlog."

package/skills-codex/scaffold-intake/SKILL.md

@@ -0,0 +1,209 @@
+---
+name: wr-itil:scaffold-intake
+description: Scaffold the four OSS intake surfaces (.github/ISSUE_TEMPLATE/, SECURITY.md, SUPPORT.md, CONTRIBUTING.md) for a downstream project that adopts @windyroad/itil. Idempotent, foreground-synchronous, and respects the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule marker semantics. Implements the contract in the "Scaffold downstream OSS intake — skill + layered triggers" architecture rule.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, request_user_input
+---
+
+<!-- Generated from the runtime-neutral skill source. Do not edit. -->
+
+> Codex runtime note: use `request_user_input` only where this contract
+> explicitly requires a human decision. Resolve `<itil-plugin-root>` from
+> this installed `SKILL.md`: it is two directories above the skill
+> directory. Run bundled commands from `<itil-plugin-root>/bin/`; do not
+> search the adopter repository or rely on those commands being on `PATH`.
+> Spawn `wr-itil:hang-off-check` with the native Codex subagent tool, wait
+> for it, and close that same agent.
+
+
+# Scaffold Intake — Downstream OSS Intake Skill
+
+Scaffold the five intake files every project in the Windy Road ecosystem needs to receive structured problem reports and route security disclosure properly:
+
+- `.github/ISSUE_TEMPLATE/config.yml`
+- `.github/ISSUE_TEMPLATE/problem-report.yml`
+- `SECURITY.md`
+- `SUPPORT.md`
+- `CONTRIBUTING.md`
+
+Templates are seeded from this repo's the "Problem 066: Intake templates split bug / feature instead of a problem-first template — misaligned with ITIL problem management" problem-corrected problem-first intake set and are substituted with per-project values for project name, repository URL, plugin list, and security-contact path.
+
+This skill implements the contract in [the "Scaffold downstream OSS intake — skill + layered triggers" architecture rule](../../../../docs/decisions/036-scaffold-downstream-oss-intake.proposed.md) (Scaffold downstream OSS intake — skill + layered triggers). It is the reciprocal of [`/wr-itil:report-upstream`](../report-upstream/SKILL.md) — that skill files reports against upstream intake; this skill creates the intake surface so a downstream project can be a target.
+
+## Pattern
+
+This skill is **foreground-synchronous** per [the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule](../../../../docs/decisions/032-governance-skill-invocation-patterns.proposed.md) (Governance skill invocation patterns). Scaffolding writes files into the project that the user normally wants to review before they commit; the wrapped-pattern subagent shape would defeat that review. The skill commits its own work per [the "Governance Skills Commit Their Own Completed Work" architecture rule](../../../../docs/decisions/014-governance-skills-commit-their-own-work.proposed.md).
+
+## Invocation
+
+```
+/wr-itil:scaffold-intake [--dry-run] [--force] [--project-name <name>] [--project-url <url>] [--security-contact <path>] [--ci]
+```
+
+| Flag | Effect |
+|---|---|
+| `--dry-run` | Preview the files that would be scaffolded; no writes. |
+| `--force` | Overwrite present files after a diff-and-replace prompt. Off by default — present files are reported as "already present" and skipped. |
+| `--project-name <name>` | Override auto-detected project name (default: `package.json` `name`, fallback to repo dirname). |
+| `--project-url <url>` | Override auto-detected repository URL (default: `package.json` `repository.url`, fallback to `git remote get-url origin`). |
+| `--security-contact <path>` | Override the security-disclosure path written into SECURITY.md (default: `Use GitHub Security Advisories`). |
+| `--ci` | Also emit `.github/workflows/intake-check.yml` (Trigger 3, optional). |
+
+## Steps
+
+### 1. Detect project metadata
+
+```bash
+PROJECT_NAME=$(node -p "require('./package.json').name" 2>/dev/null || basename "$PWD")
+PROJECT_URL=$(node -p "require('./package.json').repository?.url || ''" 2>/dev/null \
+              | sed -E 's|^git\+||; s|\.git$||' \
+              || git remote get-url origin 2>/dev/null \
+              || echo "")
+YEAR=$(date +%Y)
+```
+
+`--project-name` and `--project-url` flags override the auto-detected values when supplied. `package.json` shapes vary across adopters; if detection produces empty values, surface a clear error suggesting the override flags rather than substituting an empty token.
+
+Plugin list: enumerate installed `@windyroad/*` packages from `.codex-plugin/plugin.json` (if present) or from `package.json` dev-dependencies. Used for the SUPPORT.md "affected plugin or component" enumeration.
+
+### 2. Enumerate target paths
+
+Required intake files (per the "Scaffold downstream OSS intake — skill + layered triggers" architecture rule Detection step 5):
+
+```
+.github/ISSUE_TEMPLATE/config.yml
+.github/ISSUE_TEMPLATE/problem-report.yml
+SECURITY.md
+SUPPORT.md
+CONTRIBUTING.md
+```
+
+For each path: classify as **missing**, **present-and-current** (template-substituted output matches existing file content), or **present-and-outdated** (existing differs from substituted template).
+
+### 3. request_user_input: which files to scaffold (foreground only)
+
+In foreground (interactive) mode, fire `request_user_input` per the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 1 with options scoped to the missing set:
+
+- **Scaffold all missing** — write every absent template, skip present files.
+- **Scaffold with review** — preview each substituted template before writing.
+- **Dry-run** — preview only, no writes.
+- **Cancel** — exit without action.
+
+If `--force` is set AND outdated-present files exist, the prompt offers a fifth option for diff-and-replace per file. Architect direction (2026-04-26): keep the prompt one-shot when missing list is small; per-file prompts only when the user explicitly opts into review.
+
+### 4. Substitute templates and write files
+
+Templates live in `templates/` adjacent to this SKILL.md. Substitution is mustache-style — no runtime dependency:
+
+| Token | Value source |
+|---|---|
+| `{{project_name}}` | Detected or `--project-name` flag. |
+| `{{project_url}}` | Detected or `--project-url` flag. |
+| `{{plugin_list}}` | Comma-separated installed `@windyroad/*` plugins. |
+| `{{security_contact}}` | Detected from existing SECURITY.md (when only that file is present); else `--security-contact` flag; fallback `Use GitHub Security Advisories`. |
+| `{{year}}` | `date +%Y` at scaffold time. |
+
+`sed` substitution sketch (idempotent, no runtime tooling):
+
+```bash
+sed \
+  -e "s|{{project_name}}|$PROJECT_NAME|g" \
+  -e "s|{{project_url}}|$PROJECT_URL|g" \
+  -e "s|{{plugin_list}}|$PLUGIN_LIST|g" \
+  -e "s|{{security_contact}}|$SECURITY_CONTACT|g" \
+  -e "s|{{year}}|$YEAR|g" \
+  templates/SECURITY.md.tmpl > SECURITY.md
+```
+
+For each missing file: substitute, write to the target path, report the write + a short diff to stdout.
+
+For each present-and-current file: report "already present — skipped" without modification.
+
+For each present-and-outdated file: when `--force` is set, offer diff-and-replace; otherwise skip with a clear note that `--force` would update it.
+
+### 5. Mark scaffold as done
+
+After successful write:
+
+```bash
+mkdir -p .codex
+: > .codex/.intake-scaffold-done
+```
+
+The marker suppresses Trigger-1 first-run prompts in subsequent `/wr-itil:manage-problem` and `/wr-itil:work-problems` invocations. the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule marker semantics — persistent (no TTL), file-presence is the policy signal, deletable to reset.
+
+### 6. Commit per the "Governance Skills Commit Their Own Completed Work" architecture rule
+
+```bash
+git add .github/ISSUE_TEMPLATE/ SECURITY.md SUPPORT.md CONTRIBUTING.md .codex/.intake-scaffold-done
+git -c commit.gpgsign=false commit -m "docs: scaffold OSS intake (ISSUE_TEMPLATE, SECURITY, SUPPORT, CONTRIBUTING)"
+```
+
+Follow the project's existing commit-gate flow: the commit triggers `wr-risk-scorer:pipeline` per the "Governance Skills Commit Their Own Completed Work" architecture rule; remediation suggestions are applied per the "Auto-apply scorer remediations to reach within appetite — open action-class vocabulary" architecture rule if residual exceeds appetite.
+
+## Idempotency
+
+The skill is idempotent by construction:
+
+- Present files are skipped unless `--force`.
+- Re-running the skill on a fully-scaffolded project produces no diff.
+- The done marker prevents the host first-run prompt from re-firing.
+
+## Rule 6 audit (per the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule)
+
+Every `request_user_input` branch this skill uses must enumerate its AFK fail-safe per the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6. The audit table below documents each branch:
+
+| request_user_input branch | Resolution |
+|---|---|
+| Step 3: "Which files to scaffold?" (foreground invocation) | Foreground-synchronous — user is in-session; `request_user_input` fires normally. |
+| Step 4: "Overwrite outdated present file with updated template?" (with `--force`) | Foreground-synchronous; same as Step 3. |
+| First-run prompt fired from `/wr-itil:manage-problem` or `/wr-itil:work-problems` (foreground invocation) | Foreground-synchronous per the hosting skill's pattern. |
+| First-run prompt fired from an AFK orchestrator iteration | **Fail-safe (Rule 6)**: do NOT fire `request_user_input` and do NOT auto-scaffold. Append a single one-line "pending intake scaffold" note to the orchestrator's iteration report; defer the prompt to the user's next interactive session. the ": Progress the Backlog While I'm Away" user outcome forbids the agent from making this judgement call. |
+
+## Trigger surfaces (layered)
+
+The skill is reachable via three trigger surfaces, layered so a soft prompt fires weeks before the hard publish stop. the "Scaffold downstream OSS intake — skill + layered triggers" architecture rule specifies the exact contract.
+
+### Trigger 1: First-run prompt from manage-problem / work-problems
+
+When `/wr-itil:manage-problem` or `/wr-itil:work-problems` fires in a foreground session, the host skill's preamble checks:
+
+- Is `.github/ISSUE_TEMPLATE/` missing OR are any of the four other intake files absent?
+- Is `.codex/.intake-scaffold-declined` absent?
+- Is `.codex/.intake-scaffold-done` absent?
+
+When all three checks pass, the host emits a one-shot `request_user_input` prompt with three options — **Scaffold now**, **Not now (ask again next session)**, **Decline (never prompt in this project)**. On "Decline", write `.codex/.intake-scaffold-declined` and never re-prompt unless the user deletes the marker.
+
+**AFK fail-safe**: when the host is invoked from an AFK orchestrator, do NOT fire the prompt. Append a one-line "pending intake scaffold" note to the iteration report and continue. The user catches up on next interactive session.
+
+**the "Structured User Interaction for Governance-Skill Decisions" architecture rule Rule 6 universal default (the "AFK iter default when a skill needs to ask a question and request_user_input is unavailable — should queue the question and move to the next iteration (not halt, not silently skip)" problem, 2026-06-06 amendment)**: this IS queue-and-continue — the iteration-report note is the queued surface; the loop advances. Persona-correct for the ": Progress the Backlog While I'm Away" user outcome ("queued for my return, not guessed at"). Not a carve-out — this is the canonical default shape.
+
+### Trigger 2: Pre-publish PreToolUse gate (hard stop)
+
+`<itil-plugin-root>/hooks/pre-publish-intake-gate.sh` matches `npm publish` and `gh pr merge ... changeset-release/*` and denies if any of the five intake files are missing AND the decline marker is absent AND `INTAKE_BYPASS` is not set.
+
+**Override paths** (in priority order):
+1. `INTAKE_BYPASS=1 npm publish` — short-circuits the gate before existence check (consistent with `RISK_BYPASS` naming).
+2. `.codex/.intake-scaffold-declined` marker — explicit opt-out.
+3. Run `/wr-itil:scaffold-intake` to remove the cause.
+
+### Trigger 3: Optional CI check (deferred to v2)
+
+`--ci` flag emits `.github/workflows/intake-check.yml` asserting the four files exist on every PR. Not shipped by default; layered ADD-on for adopters with GitHub Actions.
+
+## Idempotent re-runs and template drift
+
+When this repo's intake files evolve (e.g., a future the "Problem 066: Intake templates split bug / feature instead of a problem-first template — misaligned with ITIL problem management" problem-style reform), downstream adopters' previously-scaffolded files stay frozen. Re-running the skill at any time picks up the diff: the present-and-outdated branch reports each file's diff and, with `--force`, performs diff-and-replace. Template drift policy (when this should fire automatically) is out of scope for v1 — see the "Scaffold downstream OSS intake — skill + layered triggers" architecture rule Reassessment Criteria.
+
+## Related
+
+- [the "Scaffold downstream OSS intake — skill + layered triggers" architecture rule](../../../../docs/decisions/036-scaffold-downstream-oss-intake.proposed.md) — design record (driver decision).
+- [the "Cross-project problem-reporting contract — `report-upstream` skill in `@windyroad/itil`" architecture rule](../../../../docs/decisions/024-cross-project-problem-reporting-contract.proposed.md) — sibling skill (`/wr-itil:report-upstream`); reciprocal pair.
+- [the "Governance skill invocation patterns — foreground + background with deferred-question resumption" architecture rule](../../../../docs/decisions/032-governance-skill-invocation-patterns.proposed.md) — foreground-synchronous pattern + Rule 6 audit requirement.
+- [the "Structured User Interaction for Governance-Skill Decisions" architecture rule](../../../../docs/decisions/013-structured-user-interaction-for-governance-decisions.proposed.md) — Rule 1 (interactive prompt) + Rule 6 (AFK fail-safe).
+- [the "Gate Marker Lifecycle: TTL + Drift, Not Stop-Hook Reset" architecture rule](../../../../docs/decisions/009-gate-marker-lifecycle.proposed.md) — marker lifecycle (the `.intake-scaffold-{done,declined}` markers).
+- [the "Governance Skills Commit Their Own Completed Work" architecture rule](../../../../docs/decisions/014-governance-skills-commit-their-own-work.proposed.md) — commit discipline.
+- the "Problem 065: No skill scaffolds intake files (ISSUE_TEMPLATE, SECURITY.md, CONTRIBUTING.md, SUPPORT.md) in downstream projects" problem — driver ticket.
+- the "Problem 066: Intake templates split bug / feature instead of a problem-first template — misaligned with ITIL problem management" problem — parent (template seed source); the corrected problem-first intake shape this skill propagates.
+- the "Report a Problem Without Pre-Classifying It" user outcome — primary persona; downstream-project intake coverage.
+- the "Extend the Suite with New Plugins" user outcome — clear patterns for adopters extending the suite.
+- the ": Progress the Backlog While I'm Away" user outcome — AFK fail-safe constraint.

package/skills-codex/scaffold-intake/agents/openai.yaml

@@ -0,0 +1,3 @@
+interface:
+  display_name: "WR ITIL: Scaffold Intake"
+  short_description: "Create ITIL intake and support surfaces."

package/skills-codex/scaffold-intake/templates/CONTRIBUTING.md.tmpl

@@ -0,0 +1,31 @@
+# Contributing
+
+Thanks for your interest in {{project_name}}. This guide covers how to contribute code, decisions, and bug reports.
+
+## Before you start
+
+- **Problems**: open an issue first using the **Report a problem** template under `.github/ISSUE_TEMPLATE/`. You do not need to pre-classify it as a bug or a feature -- this project practises ITIL problem management, so triage decides the category. Drive-by PRs without an issue are harder to merge because the problem framing is missing.
+- **Security vulnerabilities**: do not open a public issue. See [SECURITY.md](SECURITY.md).
+- **Usage questions**: use [Discussions]({{project_url}}/discussions), not issues.
+
+## Pull requests
+
+1. **Branch off the default branch**.
+2. **Make your change** with tests where applicable.
+3. **Open the PR** with a clear description of what is changing and why.
+
+### Commit style
+
+- Follow Conventional Commits (`feat:`, `fix:`, `docs:`, `chore:`, etc.).
+- Reference problem tickets in the commit message when the work closes one.
+- Sign-off is not required.
+
+## Code of conduct
+
+Be kind. Engage in good faith. Critique ideas, not people. Maintainers reserve the right to lock or remove discussions, issues, or PRs that derail into personal attacks.
+
+## License
+
+By contributing, you agree your contributions are licensed under {{project_name}}'s license. See the project root for the canonical LICENSE file.
+
+Copyright (c) {{year}} the {{project_name}} contributors.

package/skills-codex/scaffold-intake/templates/SECURITY.md.tmpl

@@ -0,0 +1,39 @@
+# Security Policy
+
+## Reporting a Vulnerability
+
+**Do not file a public issue for security vulnerabilities.**
+
+{{security_contact}} to disclose privately. Maintainers receive an email; the report stays private until a fix ships.
+
+A useful report includes:
+
+- The affected version of {{project_name}} (e.g. `{{project_name}}@x.y.z`).
+- The runtime / platform you reproduced on.
+- Reproduction steps that demonstrate the impact.
+- Your assessment of impact (data loss, code execution, escalation, secret leak, etc.).
+- Any suggested fix or mitigation.
+
+## What's in scope
+
+Code shipped from this repository: {{project_url}}.
+
+## What's out of scope
+
+- Vulnerabilities in third-party dependencies -- report to their maintainers.
+- Issues that require an attacker to already have local code-execution on the user's machine.
+
+## Disclosure timeline
+
+We aim to:
+
+- **Acknowledge** the report within 7 calendar days.
+- **Provide an initial assessment** (in scope, severity, planned fix) within 14 days.
+- **Ship a fix** within 90 days for confirmed vulnerabilities, with most resolved sooner.
+- **Coordinate disclosure** with the reporter so a public advisory and credit can be published when the fix lands.
+
+If we cannot meet a 90-day timeline, we will say so in the advisory thread before the deadline.
+
+## Credit
+
+Reporters who follow this private-disclosure path are credited in the published advisory unless they ask to remain anonymous.

package/skills-codex/scaffold-intake/templates/SUPPORT.md.tmpl

@@ -0,0 +1,32 @@
+# Getting Help
+
+Where to go depends on what you need:
+
+## Usage questions, configuration help, pattern advice
+
+[GitHub Discussions]({{project_url}}/discussions). Discussions stay searchable for the next person who hits the same question.
+
+Before posting, search existing discussions and the project README.
+
+## Report a problem
+
+[Open an issue]({{project_url}}/issues/new/choose) using the **Report a problem** template. You do not need to pre-classify it as a bug or feature -- this project practises ITIL problem management, and triage decides whether the root cause is a defect, a missing capability, a documentation gap, or something else. Describe what you observed and let triage decide the category.
+
+Include:
+
+- A description of what is happening and what you expected
+- Observable symptoms (errors, command output, transcripts, screenshots -- redact secrets)
+- Any workaround you tried, even if it did not help
+- Affected component and version of {{project_name}}
+- Runtime / platform and operating system
+- Minimal reproduction steps or evidence
+
+The template prompts for these. Issues without the template fields are slower to triage.
+
+## Security vulnerabilities
+
+**Do not open a public issue.** {{security_contact}} for private disclosure. See [SECURITY.md](SECURITY.md) for the disclosure timeline and what's in scope.
+
+## Project documentation
+
+Start with the README at the root of {{project_url}} for project-specific behaviour.

package/skills-codex/scaffold-intake/templates/config.yml.tmpl

@@ -0,0 +1,8 @@
+blank_issues_enabled: false
+contact_links:
+  - name: Ask a question (GitHub Discussions)
+    url: {{project_url}}/discussions
+    about: For usage help, configuration questions, and pattern advice. The issue tracker is for problems -- triage decides whether the root cause is a defect, a missing capability, or something else.
+  - name: Report a security vulnerability
+    url: {{project_url}}/security/advisories/new
+    about: Use GitHub Security Advisories for private disclosure. Do not file a public issue. See SECURITY.md.

package/skills-codex/scaffold-intake/templates/problem-report.yml.tmpl

@@ -0,0 +1,114 @@
+name: Report a problem
+description: Report a problem with {{project_name}}. You do not need to pre-classify it as a bug or feature -- triage decides.
+title: "[problem] "
+labels: ["problem", "needs-triage"]
+body:
+  - type: markdown
+    attributes:
+      value: |
+        Thanks for reporting a problem. This project practises ITIL problem management -- you describe what you observed, and triage decides whether the root cause is a defect, a missing capability, a documentation gap, or something else. You do not need to choose in advance.
+
+        For security vulnerabilities, **do not file here** -- use [GitHub Security Advisories]({{project_url}}/security/advisories/new) instead. For usage questions, use [Discussions]({{project_url}}/discussions).
+
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What is happening? What did you expect instead? Describe the observation, not the fix.
+      placeholder: |
+        e.g. "When I run the tool in a fresh project, it reports no items even though the source data has them. I expected it to list them."
+    validations:
+      required: true
+
+  - type: textarea
+    id: symptoms
+    attributes:
+      label: Symptoms
+      description: Observable behaviour -- error messages, command output, transcript snippets, screenshots. Redact secrets.
+      placeholder: |
+        - Command returns exit code 1
+        - Output contains "project root not found"
+        - ...
+    validations:
+      required: true
+
+  - type: textarea
+    id: workaround
+    attributes:
+      label: Workaround
+      description: Anything you tried that got you unstuck, even if temporary. "None found" is a valid answer.
+      placeholder: |
+        Retried after restarting -- same result. No workaround found.
+
+  - type: input
+    id: affected-component
+    attributes:
+      label: Affected component
+      description: Which part of {{project_name}} is involved? "multiple" or "unsure" is a valid answer -- triage will re-scope.
+      placeholder: "e.g. CLI / UI / specific module"
+    validations:
+      required: true
+
+  - type: input
+    id: frequency
+    attributes:
+      label: Frequency
+      description: How often does this happen? (every time, intermittently, once, ...)
+      placeholder: "e.g. every time I run the command"
+    validations:
+      required: true
+
+  - type: input
+    id: version-local-plugin
+    attributes:
+      label: Local plugin / project version
+      description: The version of {{project_name}} you are running. Enter `not detected` if you cannot determine the version.
+      placeholder: "x.y.z"
+    validations:
+      required: true
+
+  - type: input
+    id: version-upstream-package
+    attributes:
+      label: Upstream package version
+      description: If the problem involves a non-{{project_name}} upstream package, the package name and version. Enter `not applicable` or `not detected` if neither.
+      placeholder: "<pkg>@<version>"
+
+  - type: input
+    id: version-codex
+    attributes:
+      label: Codex CLI version
+      description: Output of `codex --version`. Enter `not detected` if not running through Codex.
+      placeholder: "1.x.x"
+
+  - type: input
+    id: version-node
+    attributes:
+      label: Node version
+      description: Output of `node --version`. Enter `not detected` if Node is not part of the failure path.
+      placeholder: "v20.11.0"
+
+  - type: input
+    id: version-os
+    attributes:
+      label: Operating system
+      description: Output of `uname -srm` (POSIX) or platform-equivalent. Enter `not detected` if you cannot determine.
+      placeholder: "Darwin 25.3.0 arm64"
+    validations:
+      required: true
+
+  - type: textarea
+    id: evidence
+    attributes:
+      label: Evidence
+      description: Minimal reproduction steps, transcript links, screenshots, or related prior discussions. Feeds the investigation tasks triage will open.
+      placeholder: |
+        1. Clone the repo
+        2. Run the failing command
+        3. Observe output
+
+  - type: textarea
+    id: additional
+    attributes:
+      label: Additional context
+      description: Anything else relevant -- related tickets, prior art, a hypothesis you already formed.