Add lightweight maintenance guardrails

.github/workflows/validate.yml

@@ -0,0 +1,25 @@
+name: Validate
+
+on:
+  pull_request:
+  push:
+    branches:
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  validate:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+
+      - name: Run validation
+        run: npm run validate

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing To Gooblin
+
+Gooblin is a small plugin-style Agent Skills pack. Keep changes boring, reviewable, and easy to delete.
+
+## What To Open
+
+- Bugs, typo fixes, and small documentation corrections can go straight to a pull request.
+- New skills, new commands, new adapters, new hooks, benchmark claims, and distribution changes should start with an issue.
+- Keep one conceptual change per pull request.
+
+## Design Rules
+
+- `/gooblin` stays the primary interface.
+- Character commands are advanced shortcuts, not the main user experience.
+- Skills should stay readable as plain Markdown.
+- Hooks should stay tiny, dependency-free, and safe by default.
+- Do not add app scaffolding, runtime services, build tooling, or dependencies without a concrete compatibility reason.
+
+## Before Opening A Pull Request
+
+Check `docs/maintenance.md` for affected surfaces, then run:
+
+```bash
+npm run validate
+git diff --check
+```
+
+For release or package changes, also run:
+
+```bash
+npm pack --dry-run
+```
+
+Do not claim adoption, benchmarks, marketplace approval, official host support, or integrations unless the repository includes evidence and reproduction notes.

commands/shipcheck.md

@@ -28,7 +28,9 @@ Respond in the user's language by default. Keep code, commands, file paths, API
 ## Shipcheck
 
 Scope:
+Intent checked:
 Evidence checked:
+Gaps or unverified risk:
 
 ### Findings
 
@@ -42,12 +44,23 @@ Evidence checked:
 ### Reproduce or bound bugs
 ### Defer optional scope
 ### Safety floor
+### Intent vs implementation
+
+- Intended behavior:
+- Implementation evidence:
+- Gap:
+
 ### Verification
+
+- Existing verification:
+- Proposed verification:
+- Unverified risk:
+
 ### Verdict
 ```
 
 ## Example Invocation
 
 ```text
-/shipcheck Review this branch diff before I ship it. Return numbered findings first, then cover unnecessary code, speculative architecture, debugging gaps, optional scope, safety, and verification.
+/shipcheck Review this branch diff before I ship it. Return numbered findings first, then cover unnecessary code, speculative architecture, debugging gaps, optional scope, safety, intent vs implementation, and verification.
 ```

docs/maintenance.md

@@ -6,6 +6,8 @@ This is a checklist, not a process framework. Keep it small and update it when a
 
 ## Change Impact Matrix
 
+Use this matrix as the copy-sync map. When a public behavior changes, update the smallest set of affected surfaces rather than adding a new process or parallel source of truth.
+
 | Change | Check these surfaces |
 | --- | --- |
 | Skill behavior or skill wording | `skills/`, `commands/`, `README.md`, `examples/`, `evals/rubric.md`, `evals/fixtures/` |
@@ -31,9 +33,11 @@ npm pack --dry-run
 
 For release PRs, also verify at least the current local plugin install paths documented in `docs/verified-install-paths.md`.
 
+The validation workflow should stay tiny: checkout, Node, `npm run validate`. Do not add dependency installs, generated reports, or release automation unless a real failing PR shows the need.
+
 ## What Not To Add
 
-- No CI just to mirror local validation until it has clear value.
+- No heavy CI beyond the lightweight validation gate.
 - No generated docs index unless manual drift becomes common.
 - No benchmark numbers without method, task set, sample size, limitations, and reproduction instructions.
 - No official host support claims unless the specific installer path has been verified against the released repository.

scripts/validate-skill-pack.mjs

@@ -30,6 +30,9 @@ for (const command of ['gooblin', 'clip', 'ground', 'duck', 'yak', 'shipcheck'])
   const file = `commands/${command}.md`;
   assert(fs.existsSync(file), `${file} must exist`);
   const text = fs.readFileSync(file, 'utf8');
+  const frontmatter = text.match(/^---\n([\s\S]*?)\n---\n/);
+  assert(frontmatter, `${file} must have YAML frontmatter`);
+  assert(frontmatter[1].split('\n').some((line) => line.startsWith('description: ')), `${file} frontmatter must include description`);
   assert(text.includes(`# /${command}`), `${file} must document /${command}`);
 }
 
@@ -43,7 +46,16 @@ for (const phrase of [
 }
 
 const shipcheck = fs.readFileSync('commands/shipcheck.md', 'utf8');
-for (const phrase of ['Working tree review', 'Branch review', 'Release review', 'numbered findings']) {
+for (const phrase of [
+  'Working tree review',
+  'Branch review',
+  'Release review',
+  'numbered findings',
+  'Intent checked',
+  'Intent vs implementation',
+  'Implementation evidence',
+  'Unverified risk',
+]) {
   assert(shipcheck.includes(phrase), `commands/shipcheck.md missing: ${phrase}`);
 }
 

skills/gooblin/SKILL.md

@@ -120,3 +120,4 @@ Before calling work done, check:
 - Did it avoid inventing facts?
 
 For working tree, branch, or release reviews, return numbered findings first. Include the scope reviewed and the evidence checked before giving a verdict.
+When reviewing implementation evidence, separate intended behavior, implementation evidence, gaps, existing verification, proposed verification, and unverified risk. Do not treat proposed tests or unverified claims as completed proof.