feat(forge): definition-of-done card contract + card gate + sop-to-skills offer (#31)

feat(forge): definition-of-done card contract + card gate + sop-to-skills offer

Author: aegntic

05_Clients/offer-sop-to-skills.md

@@ -0,0 +1,70 @@
+---
+id: sop-to-skills
+title: 'Turn Your SOPs Into a Running Agent System'
+state: draft
+---
+
+## SOP-to-Skills
+
+Your standard operating procedures are already written. They are also
+already dead: nobody re-reads a SOP folder, new hires learn by asking
+the person who wrote them, and the processes drift.
+
+We convert your SOP library into a running agent system: each recurring
+procedure becomes a versioned, quality-gated skill an agent executes on
+schedule, with monitoring attached from day one.
+
+## What gets delivered
+
+1. **SOP audit** (week 1): we read your procedures, rank them by
+   recurrence x failure cost, and select the 3-5 worth automating first.
+   You approve the list before anything is built.
+2. **Skill conversion** (weeks 2-3): each selected SOP becomes a
+   machine-executable skill with an explicit definition of done,
+   verification gates, and a rollback path. Built on the open-source
+   Hermes agent stack.
+3. **Schedules and watchers** (week 4): the skills run themselves:
+   daily briefs, weekly reports, follow-ups. Every automated job has a
+   monitoring check that notices when it silently stops working,
+   because broken automation is worse than no automation.
+4. **Handover**: your team gets the system, the documentation, and the
+   ability to modify it. It runs from a clean checkout without us.
+
+## What it costs
+
+- **Setup**: 10,000 to 25,000 USD depending on SOP count and
+  integration depth (fixed after the audit; no scope drift).
+- **Monitoring retainer**: 1,000 to 2,000 USD/month. Optional, and
+  the only ongoing relationship: we watch the watchers, fix drift,
+  and convert the next SOP when you say so.
+
+Anchors, honestly sourced: these price points come from published
+playbooks in the agent-services market [unverified as market-wide
+rates; they are our opening anchors, negotiable per engagement].
+
+## Why this works when your automations usually rot
+
+- Every skill carries a **definition of done** written before the work
+  starts: machine-checkable acceptance criteria, not "looks right".
+- The **worker never grades its own homework**: completion is verified
+  by a gate or a second pass, never by the automation's self-report.
+- **Monitoring is installed at build time**, not bolted on after the
+  first silent failure.
+
+## Proof this is not slideware
+
+The method is public and inspectable:
+
+- The skill pipeline: github.com/aegntic/cognitive-os (agent-forge)
+- The quality gates that run on every deliverable: same repo,
+  agent-forge/tools/qc.py
+- A working end-to-end skill with examples: github.com/aegntic/tab-harvest
+
+## Fit check (be honest)
+
+This is for you if: you have 10+ written SOPs, a team that follows
+them most of the time, and recurring processes with real failure costs.
+It is not for you if: your processes live in one person's head, or you
+want "an AI strategy" rather than specific jobs executed reliably.
+
+Next step: a 30-minute call, then the SOP audit.

agent-forge/docs/card-contract.md

@@ -0,0 +1,80 @@
+# Definition of Done: The Card Contract
+
+Every agent-forge delegation card MUST carry a DONE section before
+dispatch. A card without one does not ship. This file is the schema and
+the law; qc and reviewers reject cards that dodge it.
+
+Why: agents chase passing conditions (the "agent school" problem). If
+the finish line is not defined in machine-checkable terms before launch,
+the work produces process, not value [qYe1GsMRElw; wiki/definition-of-done].
+
+## The DONE schema
+
+Every card's DONE section contains, in this order:
+
+1. **Machine-checkable acceptance criteria.** Each criterion must be
+   verifiable by a command, a file assertion, or a count. "Looks good"
+   is not a criterion. Format: `DONE IF <checkable statement>`.
+   - File existence and counts: "DONE IF renders/manifest.json lists
+     5 entries with qc_status passed"
+   - Measurable qualities: "DONE IF python3 -m py_compile tools/*.py
+     exits 0" or "DONE IF the HTML contains zero em-dash characters"
+   - Behavioral: "DONE IF ffprobe reports 30-70s and 1080x1920"
+     Minimum 3, maximum 7 criteria. More than 7 means the card is two
+     cards.
+
+2. **The second-best-engineer test.** State who could maintain the
+   output: "DONE IF a competent non-author reviewer can open any file
+   produced and explain its purpose in under 20 minutes." For code:
+   note file sizes, function limits, reuse boundaries. Complexity
+   budgets belong here (e.g. no file over 400 lines, no function over
+   50 [wiki/definition-of-done]).
+
+3. **The unplug test.** What breaks when this ships and the author
+   disappears: "DONE IF the deliverable runs from a clean checkout
+   with only the README's install steps." If it needs the author's
+   machine, it is not done.
+
+4. **Business measure linkage.** One line tying the deliverable to a
+   cash-register metric or a portfolio goal. If no link exists, the
+   card says so explicitly ("infrastructure; no direct metric") rather
+   than inventing one.
+
+## Verification rules
+
+- The DONE section is written BEFORE dispatch, by the dispatcher.
+- The executor may not weaken, reinterpret, or re-scope criteria; if a
+  criterion proves wrong, the executor stops and reports rather than
+  quietly shipping around it.
+- Completion claims must quote command output for every machine-
+  checkable criterion. "All tests pass" without the output is a
+  failed card.
+- The reviewer (human or council) re-runs at least one criterion.
+
+## Anti-gaming
+
+Every metric gets gamed eventually [qYe1GsMRElw 7:05]. Countermeasures:
+
+- Prefer counts that are expensive to fake (real file contents, real
+  command output) over counts that are cheap to fake (line counts,
+  TODO markers added/removed).
+- Tests must protect behavior, not bless the answer: if the executor
+  wrote the test, the reviewer spot-checks it against the spec.
+- The judge is never the worker: card completion is verified by the
+  parent or a second pass, never solely by the executor's self-report.
+
+## Card template snippet
+
+    ## DONE
+    - DONE IF <criterion 1 (command/file/count)>
+    - DONE IF <criterion 2>
+    - DONE IF <criterion 3>
+    - Maintainable by: <who, and what they need to understand it>
+    - Unplug test: <clean-checkout condition>
+    - Business link: <metric or explicit "no direct metric">
+
+## Provenance
+
+Pattern: Runable "agents that finish" thesis + forge qc gates.
+Sources: [qYe1GsMRElw 4:28, 9:59]; wiki/definition-of-done;
+Nate Herk roast-council verification discipline [iTY8Q449YNQ].

agent-forge/tools/card_gate.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+"""card_gate.py - refuse delegation cards that lack a definition-of-done.
+
+Implements the card contract (agent-forge/docs/card-contract.md):
+a card is dispatchable only if its DONE section carries machine-checkable
+criteria (minimum 3 "DONE IF" statements), a maintainability line, an
+unplug test, and a business link.
+
+Usage:
+  python3 card_gate.py <card.md> [--strict]
+
+Exit codes: 0 = dispatchable; 1 = rejected (report on stdout).
+--strict additionally requires the reviewer line and rejects vague
+criteria (no digits, no file paths, no commands) heuristically.
+"""
+from __future__ import annotations
+
+import argparse
+import re
+import sys
+from pathlib import Path
+
+MIN_CRITERIA = 3
+MAX_CRITERIA = 7
+
+DONE_RE = re.compile(r"^##\s+DONE\s*$", re.MULTILINE)
+CRITERION_RE = re.compile(r"^\s*-\s*DONE IF\s+(.+)$", re.MULTILINE)
+MAINTAIN_RE = re.compile(r"maintainable by[:\s]", re.IGNORECASE)
+UNPLUG_RE = re.compile(r"unplug test[:\s]", re.IGNORECASE)
+BIZ_RE = re.compile(r"business link[:\s]", re.IGNORECASE)
+
+VAGUE_MARKERS = ("looks good", "works well", "is nice", "is clean",
+                 "high quality", "properly", "correctly formatted")
+
+
+def check_card(card_path: Path, strict: bool = False) -> tuple[bool, list[str]]:
+    """Return (dispatchable, findings)."""
+    findings: list[str] = []
+    text = card_path.read_text(encoding="utf-8")
+
+    if not DONE_RE.search(text):
+        return False, ["card has no '## DONE' section; see agent-forge/docs/card-contract.md"]
+
+    done_block = DONE_RE.search(text)
+    # capture from DONE header to next ## or EOF
+    tail = text[done_block.end():]
+    nxt = re.search(r"^##\s+", tail, re.MULTILINE)
+    block = tail[:nxt.start()] if nxt else tail
+
+    criteria = CRITERION_RE.findall(block)
+    n = len(criteria)
+    if n < MIN_CRITERIA:
+        findings.append(f"only {n} 'DONE IF' criteria; minimum {MIN_CRITERIA}")
+    if n > MAX_CRITERIA:
+        findings.append(f"{n} criteria exceeds maximum {MAX_CRITERIA}; split the card")
+
+    if not MAINTAIN_RE.search(block):
+        findings.append("missing 'Maintainable by:' line (second-best-engineer test)")
+    if not UNPLUG_RE.search(block):
+        findings.append("missing 'Unplug test:' line")
+    if not BIZ_RE.search(block):
+        findings.append("missing 'Business link:' line (or explicit 'no direct metric')")
+
+    if strict:
+        for c in criteria:
+            low = c.lower()
+            if any(v in low for v in VAGUE_MARKERS):
+                findings.append(f"vague criterion: 'DONE IF {c[:60]}'")
+            checkable = bool(re.search(r"\d|\.py|\.md|\.json|\.mp4|/|exit|grep|count|ffprobe|py_compile", low))
+            if not checkable:
+                findings.append(f"criterion not machine-checkable: 'DONE IF {c[:60]}'")
+
+    return (not findings), findings
+
+
+def main() -> int:
+    ap = argparse.ArgumentParser()
+    ap.add_argument("card", help="path to the delegation card markdown")
+    ap.add_argument("--strict", action="store_true")
+    args = ap.parse_args()
+    path = Path(args.card)
+    if not path.is_file():
+        print(f"card not found: {path}")
+        return 1
+    ok, findings = check_card(path, strict=args.strict)
+    if ok:
+        print(f"DISPATCHABLE: {path.name} ({len(CRITERION_RE.findall(path.read_text(encoding='utf-8')))} criteria)")
+        return 0
+    print(f"REJECTED: {path.name}")
+    for f in findings:
+        print(f"  - {f}")
+    print("fix per agent-forge/docs/card-contract.md; a card without a finish line buys process, not value")
+    return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())