@gillcash/necktie 0.2.0

package/skills/necktie-reverse/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Necktie Reverse"
+  short_description: "Compile iterations into an executable brief"
+  default_prompt: "Use $necktie-reverse to compile this goal and critique into one executable brief."
+policy:
+  allow_implicit_invocation: false

package/skills/necktie-reverse/references/blueprint-template.md

@@ -0,0 +1,54 @@
+# Executable brief template
+
+Use these headings. Omit a heading only when it is genuinely inapplicable.
+
+```text
+ROLE
+Act as [relevant role and perspective].
+
+OUTCOME
+Produce [artifact/action] so that [audience] can [real-world outcome].
+
+INPUTS AND SOURCE HIERARCHY
+- Evidence: [sources that may support claims]
+- Method guidance: [sources that govern the process only]
+- Constraints: [authority, safety, scope, format]
+- Prior outputs: [hypotheses/style references only]
+Resolve conflicts in this order: [explicit hierarchy].
+
+SCOPE
+Include: [...]
+Exclude: [...]
+
+MATERIAL ASSUMPTIONS
+- [...]
+
+WORKFLOW
+1. Inspect and classify sources.
+2. Establish a baseline and expose assumptions.
+3. Challenge the inquiry and identify the strongest unasked question.
+4. Produce the deliverable from raw evidence.
+5. Review against the acceptance criteria.
+6. Revise within the stated stopping rule.
+7. Verify in the target environment.
+
+DELIVERABLES
+- [exact output, format, and location]
+
+ACCEPTANCE CRITERIA
+- [observable pass/fail criterion]
+
+EVIDENCE AND CITATION RULES
+- [claim support, freshness, provenance, quotation, or uncertainty rules]
+
+REVIEW CONTRACT
+Return APPROVE, REVISE, or BLOCK. Report only material findings with exact evidence and the smallest required change. Ask the strongest unasked expert question. Do not rewrite while reviewing.
+
+STOPPING RULE
+Stop when all criteria pass, a material blocker requires user input, the same issue survives three reviews, or three revision decisions are recorded.
+
+HANDOFF
+Return the artifact, reusable brief, verification record, limitations, overlooked consideration, and strongest unasked question.
+```
+
+Write instructions that are observable and testable. Replace adjectives such as "excellent" or "comprehensive" with explicit criteria. Do not request hidden chain-of-thought; request concise assumptions, decisions, evidence, and verification instead.

package/skills/necktie-review/SKILL.md

@@ -0,0 +1,61 @@
+---
+name: necktie-review
+description: Independently gate a candidate deliverable against its exact brief, evidence, acceptance criteria, and verification results. Use inside the Necktie loop, for an Auto-review-style approval decision, or when the user wants a concise APPROVE, REVISE, or BLOCK judgment with actionable material findings and a strongest unasked question.
+---
+
+# Necktie Review
+
+Judge the proposed result without silently rewriting it or expanding its scope. Review as a separate role from the author, using the smallest evidence packet that permits a reliable decision.
+
+## Inputs
+
+Require:
+
+- the exact executable brief;
+- the candidate artifact or change set;
+- acceptance criteria and constraints;
+- a source ledger plus relevant evidence excerpts, paths, or links;
+- verification results, if already available.
+
+If an input is unavailable, decide whether that absence is itself a material finding. Read [references/reviewer-rubric.md](references/reviewer-rubric.md) completely before judging.
+
+## Review
+
+1. Inspect the candidate read-only. Do not author fixes while acting as reviewer.
+2. Test each acceptance criterion and every material factual claim against the evidence ledger.
+3. Look for omissions, contradictions, fabricated support, stale assumptions, unsafe actions, unusable formatting, and failure to verify in the target environment.
+4. Check whether the deliverable advances the actual goal rather than merely matching its requested shape.
+5. Identify what the author and user may not have considered.
+6. Name the single strongest unasked expert question and its consequence.
+7. Report only material findings. Combine duplicates and point to exact locations when possible.
+
+## Decide
+
+- `APPROVE`: no critical or major finding remains. Minor optional improvements may be noted but cannot block approval.
+- `REVISE`: one or more fixable critical or major findings remain. State the smallest required change for each.
+- `BLOCK`: a required decision, authority, source, or safe execution path is absent and the author cannot resolve it within scope.
+
+Confidence is not a substitute for evidence. Do not approve because the prose sounds plausible.
+
+## Output
+
+Return only one JSON object matching this shape:
+
+```json
+{
+  "decision": "APPROVE",
+  "summary": "One-sentence basis for the decision.",
+  "findings": [],
+  "strongest_unasked_question": "The highest-leverage omitted question.",
+  "question_consequence": "What changes if its answer differs.",
+  "confidence": "high"
+}
+```
+
+Each finding must contain `id`, `severity` (`critical`, `major`, or `minor`), `criterion`, `location`, `evidence`, and `required_change`. Use an empty findings array only for approval. Validate a saved decision with:
+
+```text
+python skills/necktie-review/scripts/validate_review.py review.json
+```
+
+Do not include markdown around the JSON, private reasoning, or an edited artifact.

package/skills/necktie-review/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Necktie Review"
+  short_description: "Gate outputs against evidence and criteria"
+  default_prompt: "Use $necktie-review to independently review this deliverable."
+policy:
+  allow_implicit_invocation: false

package/skills/necktie-review/references/reviewer-rubric.md

@@ -0,0 +1,29 @@
+# Necktie reviewer rubric
+
+## Order of review
+
+1. **Authority and safety**: Is the action permitted, reversible where appropriate, and within the agreed scope?
+2. **Goal fit**: Does the artifact support the user's actual outcome and audience?
+3. **Evidence integrity**: Are material claims traceable to eligible, current sources? Are method context and prior outputs kept out of the evidence chain?
+4. **Correctness and completeness**: Are calculations, logic, content, and required sections accurate and sufficient?
+5. **Usability**: Can the intended audience use the result in its target environment?
+6. **Verification**: Were the relevant tests, renders, checks, or inspections performed, and do their results support completion?
+7. **Economy**: Is the solution no larger or more complex than the goal requires?
+
+## Severity
+
+- `critical`: could cause unsafe action, material loss, invalid conclusion, unauthorized change, or failure of the central deliverable.
+- `major`: violates an acceptance criterion, leaves a material unsupported claim, omits a necessary component, or prevents intended use.
+- `minor`: real but non-blocking defect that does not change the decision or intended use.
+
+Do not inflate preferences into findings. A valid finding states the violated criterion, exact location, concrete evidence, and smallest required change.
+
+## Decision examples
+
+- Approve a sound artifact with an optional wording improvement; record it only as a minor finding if useful.
+- Revise when a KPI definition lacks a denominator, a cited claim is unsupported, a requested file does not render, or a required test fails.
+- Block when the user must choose between materially different scopes, required private data is unavailable, or execution needs authority the run does not possess.
+
+## Independence
+
+Review the artifact that exists, not the artifact you imagine the author intended. Do not fix it during the review pass. If revising later, leave reviewer role and return to author role first.

package/skills/necktie-review/scripts/validate_review.py

@@ -0,0 +1,110 @@
+#!/usr/bin/env python3
+"""Validate the JSON decision emitted by the Necktie reviewer skill."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from pathlib import Path
+import sys
+
+
+TOP_LEVEL_KEYS = {
+    "decision",
+    "summary",
+    "findings",
+    "strongest_unasked_question",
+    "question_consequence",
+    "confidence",
+}
+FINDING_KEYS = {"id", "severity", "criterion", "location", "evidence", "required_change"}
+DECISIONS = {"APPROVE", "REVISE", "BLOCK"}
+SEVERITIES = {"critical", "major", "minor"}
+CONFIDENCE = {"high", "medium", "low"}
+
+
+def nonempty_string(value: object) -> bool:
+    return isinstance(value, str) and bool(value.strip())
+
+
+def validate_review(value: object) -> list[str]:
+    errors: list[str] = []
+    if not isinstance(value, dict):
+        return ["review must be a JSON object"]
+
+    missing = sorted(TOP_LEVEL_KEYS - value.keys())
+    extra = sorted(value.keys() - TOP_LEVEL_KEYS)
+    if missing:
+        errors.append(f"missing top-level keys: {', '.join(missing)}")
+    if extra:
+        errors.append(f"unexpected top-level keys: {', '.join(extra)}")
+    if missing:
+        return errors
+
+    decision = value["decision"]
+    if decision not in DECISIONS:
+        errors.append(f"decision must be one of: {', '.join(sorted(DECISIONS))}")
+    for field in ("summary", "strongest_unasked_question", "question_consequence"):
+        if not nonempty_string(value[field]):
+            errors.append(f"{field} must be a non-empty string")
+    if value["confidence"] not in CONFIDENCE:
+        errors.append(f"confidence must be one of: {', '.join(sorted(CONFIDENCE))}")
+
+    findings = value["findings"]
+    if not isinstance(findings, list):
+        errors.append("findings must be an array")
+        return errors
+
+    blocking_findings = 0
+    seen_ids: set[str] = set()
+    for index, finding in enumerate(findings):
+        prefix = f"findings[{index}]"
+        if not isinstance(finding, dict):
+            errors.append(f"{prefix} must be an object")
+            continue
+        missing_finding = sorted(FINDING_KEYS - finding.keys())
+        extra_finding = sorted(finding.keys() - FINDING_KEYS)
+        if missing_finding:
+            errors.append(f"{prefix} missing keys: {', '.join(missing_finding)}")
+        if extra_finding:
+            errors.append(f"{prefix} unexpected keys: {', '.join(extra_finding)}")
+        if missing_finding:
+            continue
+        for field in FINDING_KEYS - {"severity"}:
+            if not nonempty_string(finding[field]):
+                errors.append(f"{prefix}.{field} must be a non-empty string")
+        if finding["severity"] not in SEVERITIES:
+            errors.append(f"{prefix}.severity must be one of: {', '.join(sorted(SEVERITIES))}")
+        elif finding["severity"] in {"critical", "major"}:
+            blocking_findings += 1
+        if finding["id"] in seen_ids:
+            errors.append(f"duplicate finding id: {finding['id']}")
+        seen_ids.add(finding["id"])
+
+    if decision == "APPROVE" and blocking_findings:
+        errors.append("APPROVE cannot contain critical or major findings")
+    if decision in {"REVISE", "BLOCK"} and blocking_findings == 0:
+        errors.append(f"{decision} requires at least one critical or major finding")
+    return errors
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("review", type=Path)
+    args = parser.parse_args(argv)
+    try:
+        value = json.loads(args.review.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError) as exc:
+        print(f"invalid: {exc}", file=sys.stderr)
+        return 2
+    errors = validate_review(value)
+    if errors:
+        for error in errors:
+            print(f"invalid: {error}", file=sys.stderr)
+        return 1
+    print("valid Necktie review")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())