agentforge-framework 0.2.0__py3-none-any.whl

agentforge_framework/skills/unslop/scripts/wiki_sync.py

@@ -0,0 +1,479 @@
+#!/usr/bin/env python3
+"""
+Sync unslop rules with Wikipedia's "Signs of AI writing" page.
+
+Fetches the latest revision, parses structured data from wikitext,
+and outputs diffs or integration prompts for Claude Code.
+
+Subcommands:
+    check  - Check for updates (exits 0 if no updates, 1 if updates available)
+    diff   - Output structured JSON diff of changes since last sync
+    prompt - Output a Claude Code integration prompt with mapped changes
+
+Usage:
+    python wiki_sync.py check
+    python wiki_sync.py diff
+    python wiki_sync.py prompt
+    python wiki_sync.py prompt | claude -p --allowedTools Edit,Read,Grep,Glob,Bash
+"""
+
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import re
+import sys
+import urllib.request
+import urllib.parse
+from pathlib import Path
+from typing import TypedDict
+
+STATE_FILE = Path(__file__).parent / ".wiki_sync_state.json"
+WIKI_PAGE = "Wikipedia:Signs_of_AI_writing"
+API_URL = "https://en.wikipedia.org/w/api.php"
+
+
+class SyncState(TypedDict):
+    last_revision_id: int
+    last_timestamp: str
+    content_hash: str
+    last_content_snapshot: str
+
+
+class ParsedSection(TypedDict):
+    title: str
+    level: int
+    content: str
+    watch_words: list[str]
+    examples: list[str]
+
+
+class Change(TypedDict):
+    type: str  # "new_section", "new_words", "modified", "removed"
+    section: str
+    details: str
+    words: list[str]
+
+
+def fetch_latest_revision() -> tuple[int, str, str]:
+    """Fetch the latest revision content from Wikipedia.
+
+    Returns (revision_id, timestamp, wikitext).
+    """
+    params = {
+        "action": "query",
+        "titles": WIKI_PAGE,
+        "prop": "revisions",
+        "rvslots": "*",
+        "rvprop": "ids|timestamp|content",
+        "format": "json",
+        "formatversion": "2",
+    }
+    url = f"{API_URL}?{urllib.parse.urlencode(params)}"
+    req = urllib.request.Request(url, headers={"User-Agent": "unslop-wiki-sync/1.0"})
+
+    with urllib.request.urlopen(req, timeout=30) as resp:
+        data = json.loads(resp.read().decode("utf-8"))
+
+    page = data["query"]["pages"][0]
+    if "missing" in page:
+        print(f"Error: Page '{WIKI_PAGE}' not found.", file=sys.stderr)
+        sys.exit(2)
+
+    revision = page["revisions"][0]
+    rev_id = revision["revid"]
+    timestamp = revision["timestamp"]
+    content = revision["slots"]["main"]["content"]
+    return rev_id, timestamp, content
+
+
+def get_wikitext(from_file: str | None) -> tuple[int, str, str]:
+    """Return (revision_id, timestamp, wikitext).
+
+    With `from_file` set, read wikitext from that local path instead of
+    hitting the network — used for offline eval/fixture runs. There is no
+    real revision for a local file, so revision_id/timestamp are placeholders.
+    """
+    if from_file:
+        content = Path(from_file).read_text(encoding="utf-8")
+        return 0, "from-file", content
+    return fetch_latest_revision()
+
+
+def load_state() -> SyncState | None:
+    if not STATE_FILE.exists():
+        return None
+    with open(STATE_FILE, "r") as f:
+        return json.load(f)
+
+
+def save_state(rev_id: int, timestamp: str, content: str) -> None:
+    state: SyncState = {
+        "last_revision_id": rev_id,
+        "last_timestamp": timestamp,
+        "content_hash": hashlib.sha256(content.encode()).hexdigest(),
+        "last_content_snapshot": content,
+    }
+    with open(STATE_FILE, "w") as f:
+        json.dump(state, f, indent=2)
+
+
+def parse_wikitext(wikitext: str) -> list[ParsedSection]:
+    """Parse wikitext into structured sections with watch words and examples."""
+    sections: list[ParsedSection] = []
+    current_title = "Introduction"
+    current_level = 1
+    current_lines: list[str] = []
+
+    for line in wikitext.split("\n"):
+        header_match = re.match(r"^(={2,6})\s*(.+?)\s*\1\s*$", line)
+        if header_match:
+            if current_lines:
+                sections.append(_build_section(current_title, current_level, current_lines))
+            current_level = len(header_match.group(1))
+            current_title = header_match.group(2).strip()
+            current_lines = []
+        else:
+            current_lines.append(line)
+
+    if current_lines:
+        sections.append(_build_section(current_title, current_level, current_lines))
+
+    return sections
+
+
+def _build_section(title: str, level: int, lines: list[str]) -> ParsedSection:
+    """Build a ParsedSection from raw lines."""
+    content = "\n".join(lines).strip()
+    watch_words = _extract_watch_words(content)
+    examples = _extract_examples(content)
+    return {
+        "title": title,
+        "level": level,
+        "content": content,
+        "watch_words": watch_words,
+        "examples": examples,
+    }
+
+
+def _extract_watch_words(content: str) -> list[str]:
+    """Extract words-to-watch from tmbox templates and bold/italic markers."""
+    words: list[str] = []
+
+    # Match {{tmbox|text=...}} content
+    for match in re.finditer(r"\{\{tmbox\|[^}]*text\s*=\s*([^}]+)\}\}", content, re.DOTALL):
+        text = match.group(1)
+        # Extract bold words within tmbox
+        for bold in re.finditer(r"'''(.+?)'''", text):
+            words.append(bold.group(1).strip())
+
+    # Match bold words in "words to watch" style lists
+    for match in re.finditer(r"'''(.+?)'''", content):
+        word = match.group(1).strip()
+        if word and len(word) < 50:
+            words.append(word)
+
+    # Match items in bulleted lists
+    for match in re.finditer(r"^\*\s*'''(.+?)'''", content, re.MULTILINE):
+        words.append(match.group(1).strip())
+
+    return list(dict.fromkeys(words))  # dedupe preserving order
+
+
+def _extract_examples(content: str) -> list[str]:
+    """Extract example blocks (blockquotes, textdiff templates)."""
+    examples: list[str] = []
+
+    # {{blockquote|...}}
+    for match in re.finditer(r"\{\{blockquote\|([^}]+)\}\}", content, re.DOTALL):
+        examples.append(match.group(1).strip())
+
+    # {{textdiff|old=...|new=...}}
+    for match in re.finditer(
+        r"\{\{textdiff\|[^}]*old\s*=\s*([^|]+)\|[^}]*new\s*=\s*([^}]+)\}\}",
+        content, re.DOTALL
+    ):
+        examples.append(f"BEFORE: {match.group(1).strip()}\nAFTER: {match.group(2).strip()}")
+
+    # Indented blockquote lines (: prefix in wikitext)
+    block_lines: list[str] = []
+    for line in content.split("\n"):
+        if line.startswith(":"):
+            block_lines.append(line.lstrip(": "))
+        elif block_lines:
+            examples.append("\n".join(block_lines))
+            block_lines = []
+    if block_lines:
+        examples.append("\n".join(block_lines))
+
+    return examples
+
+
+def compute_diff(old_sections: list[ParsedSection], new_sections: list[ParsedSection]) -> list[Change]:
+    """Compute structured diff between two parsed page versions."""
+    changes: list[Change] = []
+
+    old_by_title = {s["title"]: s for s in old_sections}
+    new_by_title = {s["title"]: s for s in new_sections}
+
+    for title, new_sec in new_by_title.items():
+        if title not in old_by_title:
+            changes.append({
+                "type": "new_section",
+                "section": title,
+                "details": f"New section with {len(new_sec['watch_words'])} watch words",
+                "words": new_sec["watch_words"],
+            })
+        else:
+            old_sec = old_by_title[title]
+            new_words = set(new_sec["watch_words"]) - set(old_sec["watch_words"])
+            if new_words:
+                changes.append({
+                    "type": "new_words",
+                    "section": title,
+                    "details": f"{len(new_words)} new watch words added",
+                    "words": sorted(new_words),
+                })
+
+            old_hash = hashlib.sha256(old_sec["content"].encode()).hexdigest()
+            new_hash = hashlib.sha256(new_sec["content"].encode()).hexdigest()
+            if old_hash != new_hash and not new_words:
+                changes.append({
+                    "type": "modified",
+                    "section": title,
+                    "details": "Section content changed (no new watch words)",
+                    "words": [],
+                })
+
+    for title in old_by_title:
+        if title not in new_by_title:
+            changes.append({
+                "type": "removed",
+                "section": title,
+                "details": "Section removed from Wikipedia page",
+                "words": old_by_title[title]["watch_words"],
+            })
+
+    return changes
+
+
+# Mapping from Wikipedia section themes to unslop target files/sections
+SECTION_MAP: dict[str, dict[str, str]] = {
+    "words to watch": {
+        "file": "references/taboo-phrases.md",
+        "section": "AI Vocabulary (Additional)",
+    },
+    "promotional": {
+        "file": "references/taboo-phrases.md",
+        "section": "Promotional Language",
+    },
+    "significance": {
+        "file": "references/taboo-phrases.md",
+        "section": "Significance & Legacy Inflation",
+    },
+    "legacy": {
+        "file": "references/taboo-phrases.md",
+        "section": "Significance & Legacy Inflation",
+    },
+    "vague": {
+        "file": "references/taboo-phrases.md",
+        "section": "Vague Attributions",
+    },
+    "attribution": {
+        "file": "references/taboo-phrases.md",
+        "section": "Vague Attributions",
+    },
+    "copula": {
+        "file": "references/taboo-phrases.md",
+        "section": "Copula Avoidance",
+    },
+    "participial": {
+        "file": "references/taboo-phrases.md",
+        "section": "Superficial -ing Analyses",
+    },
+    "chatbot": {
+        "file": "references/taboo-phrases.md",
+        "section": "Communication Artifacts",
+    },
+    "jargon": {
+        "file": "references/taboo-phrases.md",
+        "section": "Business Jargon",
+    },
+    "structure": {
+        "file": "references/taboo-phrases.md",
+        "section": "Structural Patterns to Avoid",
+    },
+    "synonym": {
+        "file": "references/taboo-phrases.md",
+        "section": "Elegant Variation / Synonym Cycling",
+    },
+}
+
+
+def map_change_to_target(change: Change) -> dict[str, str]:
+    """Map a Wikipedia change to the appropriate unslop file and section."""
+    section_lower = change["section"].lower()
+    for keyword, target in SECTION_MAP.items():
+        if keyword in section_lower:
+            return target
+    return {
+        "file": "references/taboo-phrases.md",
+        "section": "AI Vocabulary (Additional)",
+    }
+
+
+def generate_prompt(changes: list[Change], sections: list[ParsedSection]) -> str:
+    """Generate a Claude Code integration prompt from detected changes."""
+    if not changes:
+        return "No changes detected since last sync. Nothing to integrate."
+
+    lines = [
+        "# Wikipedia AI Writing Patterns — Integration Update",
+        "",
+        "The Wikipedia 'Signs of AI writing' page has been updated.",
+        "Below are changes that need to be integrated into the unslop skill.",
+        "",
+        "## Changes Detected",
+        "",
+    ]
+
+    for i, change in enumerate(changes, 1):
+        target = map_change_to_target(change)
+        lines.append(f"### {i}. [{change['type'].upper()}] {change['section']}")
+        lines.append(f"")
+        lines.append(f"**Details:** {change['details']}")
+        lines.append(f"**Target file:** `{target['file']}`")
+        lines.append(f"**Target section:** {target['section']}")
+        if change["words"]:
+            lines.append(f"**Words/phrases to add:**")
+            for word in change["words"]:
+                lines.append(f"- \"{word}\"")
+        lines.append("")
+
+    lines.extend([
+        "## Integration Instructions",
+        "",
+        "For each change above:",
+        "",
+        "1. Read the target file",
+        "2. Check if the phrase already exists (avoid duplicates)",
+        "3. Add new phrases to the appropriate section in `references/taboo-phrases.md`",
+        "4. Mirror additions in `scripts/banned_phrase_scan.py` BANNED_PHRASES dict",
+        "5. If a new before/after example is warranted, add to `references/edit-library.md`",
+        "",
+        "After all changes:",
+        "- Run `python3 scripts/banned_phrase_scan.py < /dev/null` to verify no syntax errors",
+        "- Verify no duplicate entries in taboo-phrases.md",
+    ])
+
+    return "\n".join(lines)
+
+
+def cmd_check(from_file: str | None = None) -> None:
+    """Check for updates. Exit 0 = no updates, 1 = updates available."""
+    rev_id, timestamp, content = get_wikitext(from_file)
+    state = load_state()
+
+    content_hash = hashlib.sha256(content.encode()).hexdigest()
+
+    if state is None:
+        print(f"No previous sync state. Current revision: {rev_id} ({timestamp})")
+        print("Run 'diff' or 'prompt' to see all content as new.")
+        sys.exit(1)
+
+    if content_hash == state["content_hash"]:
+        print(f"No changes. Current revision: {rev_id} ({timestamp})")
+        print(f"Last synced revision: {state['last_revision_id']} ({state['last_timestamp']})")
+        sys.exit(0)
+
+    print(f"Updates available!")
+    print(f"  Last synced: revision {state['last_revision_id']} ({state['last_timestamp']})")
+    print(f"  Current:     revision {rev_id} ({timestamp})")
+    sys.exit(1)
+
+
+def cmd_diff(from_file: str | None = None) -> None:
+    """Output structured JSON diff of changes."""
+    rev_id, timestamp, content = get_wikitext(from_file)
+    state = load_state()
+
+    new_sections = parse_wikitext(content)
+
+    if state is None:
+        old_sections: list[ParsedSection] = []
+    else:
+        old_sections = parse_wikitext(state["last_content_snapshot"])
+
+    changes = compute_diff(old_sections, new_sections)
+
+    output = {
+        "revision_id": rev_id,
+        "timestamp": timestamp,
+        "previous_revision_id": state["last_revision_id"] if state else None,
+        "total_changes": len(changes),
+        "changes": changes,
+    }
+
+    print(json.dumps(output, indent=2))
+    if not from_file:
+        save_state(rev_id, timestamp, content)
+
+
+def cmd_prompt(from_file: str | None = None) -> None:
+    """Output a Claude Code integration prompt."""
+    rev_id, timestamp, content = get_wikitext(from_file)
+    state = load_state()
+
+    new_sections = parse_wikitext(content)
+
+    if state is None:
+        old_sections: list[ParsedSection] = []
+    else:
+        old_sections = parse_wikitext(state["last_content_snapshot"])
+
+    changes = compute_diff(old_sections, new_sections)
+    prompt = generate_prompt(changes, new_sections)
+
+    print(prompt)
+    if not from_file:
+        save_state(rev_id, timestamp, content)
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Sync unslop rules with Wikipedia's 'Signs of AI writing' page."
+    )
+    subparsers = parser.add_subparsers(dest="command")
+
+    commands = {
+        "check": cmd_check,
+        "diff": cmd_diff,
+        "prompt": cmd_prompt,
+    }
+    for name in commands:
+        sub = subparsers.add_parser(name)
+        sub.add_argument(
+            "--from-file",
+            metavar="PATH",
+            help=(
+                "read wikitext from PATH instead of fetching from Wikipedia "
+                "(skips the network call and skips writing sync state)"
+            ),
+        )
+
+    if len(sys.argv) < 2:
+        print("Usage: wiki_sync.py <check|diff|prompt>", file=sys.stderr)
+        sys.exit(2)
+
+    if sys.argv[1] not in commands:
+        print(f"Unknown command: {sys.argv[1]}", file=sys.stderr)
+        print(f"Available: {', '.join(commands)}", file=sys.stderr)
+        sys.exit(2)
+
+    args = parser.parse_args()
+    commands[args.command](args.from_file)
+
+
+if __name__ == "__main__":
+    main()

agentforge_framework/skills/write-plainly/SKILL.md

@@ -0,0 +1,94 @@
+---
+name: write-plainly
+description: The tells three deterministic scanners count, and how to get past them on the first attempt. Use before drafting anything a human reads at the end of a Run.
+---
+
+# Write plainly
+
+Whatever you produce here is scanned before anybody sees it. Three scripts count
+things: phrases from a fixed list, sentence rhythms, and the arrangement of the
+whole document. None of them can judge whether your review is any good. They can
+tell that it was assembled rather than written, and their report is attached to
+your work either way, so a person sees the verdict beside the prose.
+
+You get two rewrites, and a rewrite can only reach a phrase. The tells that
+matter most are further down this page, in the arrangement, where no
+find-and-replace will reach them. Spend the attempt now instead.
+
+## Words already on a fixed list
+
+Corporate verbs with an abstract object are the largest group: `leverage` our
+capabilities, `harness` the power of, `foster` collaboration, `delve into` the
+implications, `navigate` the complex landscape, `unpack` the argument. Reach for
+the plainest verb that fits — use, build, handle, read.
+
+Then the ones that inflate, hedge, or credit nobody:
+
+- `robust`, `comprehensive`, `game changer`, `synergy`, `treasure trove`
+- `plays a crucial role`, `underscore the importance`, `boasts a rich array of`
+- `research shows` and `analysts predict`, with no person or paper named
+- `the data tells a story`, `the numbers speak for themselves`
+- `could potentially`, which hedges twice for one hedge's worth of doubt
+- `in conclusion`, `at the end of the day`, `here's the thing`, `in today's`
+- `as an AI language model`, `as of my last update`
+
+Each of those is a sentence that has stopped saying anything. A claim about the
+diff carries a file and a line; a claim that some part of it matters carries the
+effect on somebody who runs this code. Say things of that kind and the report is
+worth the minute it takes to read.
+
+## Sentence shapes it counts
+
+Several constructions are matched on sight, whatever they are about:
+
+- `not only X but also Y`, and `it's not just X — it's Y`
+- `serves as a testament to`, `functions as a solution`, `constitutes a shift`
+- a contrast split across two sentences: `Not because X. Because Y.`
+- a single word standing in for emphasis: `Full stop.`
+- a question you then answer yourself: `Why does this matter?`
+- an -ing tail bolted to the end, `, ensuring reliability`, past roughly one
+  sentence in seven
+
+Two more are counted rather than matched, and both are about rhythm. Sentences
+of near-identical length across a passage read as generated, so let some run
+long and cut others to four words. Stacked short fragments read as generated
+too — clipped, punchy, hard-boiled — and that register is itself on the list, so
+the cure for padding is not telegraphese. Whether a given line survives is the
+wrong question to ask. What reads evenly for ten sentences is caught by the
+spread, not by any one of them.
+
+## The arrangement of the whole document
+
+This is the part a rewrite cannot reach, and the reason to get it right in the
+draft. A single scan can burn all three of your attempts here while every
+individual phrase in the prose passes on its own. The tell is structural, so
+settle the structure first and let the wording follow it instead of leading.
+
+Openers first. A paragraph beginning `However` or `Moreover` or `Additionally`
+spends its opening words on its relationship to the paragraph above instead of
+on its own claim. Three such paragraphs flag, and rotating through several
+different cues flags harder than repeating one. So does narrating your own
+structure — `First,` then `Next,` then `As mentioned above` — and so does
+opening four sentences in a row on one word, or two paragraphs on `Every ___
+is`.
+
+Then the outline. Do not announce what a document will cover and then cover it.
+An intro that lists the topics below, headings that restate that list, and body
+paragraphs that open on the intro's words are three separate counts of a single
+habit. The ending is counted the same way: a last paragraph that circles back to
+the vocabulary of the first reads as a recap loop rather than a finish. Stop on
+the most specific thing you have.
+
+Formatting is counted too. Three or more lines of a bold label followed by a
+colon read as a filled-in template, whatever is in them.
+
+## Say it once
+
+Report what changed, where, and whether it does what the Plan said. Put what
+matters most at the top, because somebody may stop reading after a paragraph.
+Where something does not match, quote the line and give its file. Where the Run
+did what it promised, say so once and move on.
+
+Prose somebody can act on tends to clear these scans without being aimed at
+them. Every tell above is what writing does when it has run out of things to
+say, and you have something to say: you have just read the diff.

agentforge_framework/workflows/bugfix.yaml

@@ -0,0 +1,8 @@
+# A fix, verified, and reported on. No Security Step: a bug fix that touches
+# auth is a Task the Orchestrator routes to `feature` instead, which is a
+# judgement about the Task rather than a check that can be automated here.
+name: bugfix
+steps:
+  - role: implementer
+  - role: tester
+  - role: reviewer

agentforge_framework/workflows/feature.yaml

@@ -0,0 +1,16 @@
+# The default Workflow: build something that was not there before.
+#
+# The Reviewer speaks last because it reports on what everything before it did.
+#
+# No Gate is declared here on purpose: a Gate suspends the Run until it clears,
+# and the default Workflow stopping to wait on somebody is a choice a project
+# makes rather than one it inherits. Add `gate: human` to a step to insert
+# yourself after it, `gate: tests` to hold it on the repository's own suite, or
+# `gate: security` to hold it on a clean audit; the kinds are registered in
+# `core/gates.py`.
+name: feature
+steps:
+  - role: implementer
+  - role: tester
+  - role: security
+  - role: reviewer

agentforge_framework/workflows/review.yaml

@@ -0,0 +1,10 @@
+# An audit and a write-up of a diff AgentForge did not produce: point it at a
+# branch somebody else wrote and it reports on that.
+#
+# The only shipped Workflow with no Implementer, which is what makes it worth
+# shipping twice over — it is the check on whether the runtime has quietly
+# assumed it wrote the diff itself.
+name: review
+steps:
+  - role: security
+  - role: reviewer