Add 10 cognition-introspection patterns (204 -> 214) (#5)

* Add 6 patterns from Liu et al. 2025 + Anthropic, new cognition-introspection category, redundancy fixes, patterns.graph.json

# Patterns added (6, catalog 198 → 204)

From Liu et al., "Agent design pattern catalogue", J. Syst. Softw. 220, 112278
(https://doi.org/10.1016/j.jss.2024.112278):
  - passive-goal-creator       (planning-control-flow)
  - proactive-goal-creator     (planning-control-flow)
  - prompt-response-optimiser  (structure-data)
  - voting-based-cooperation   (multi-agent)
  - tool-agent-registry        (tool-use-environment)

From Anthropic, "Building Effective Agents"
(https://www.anthropic.com/research/building-effective-agents):
  - augmented-llm              (tool-use-environment) — the foundational
                                LLM + tools + retrieval + memory block

Liu / Anthropic references added to 14 existing patterns that map to
their catalogues (evaluator-optimizer, react, human-in-the-loop,
agent-as-judge, translation-layer, tool-discovery, input-output-guardrails,
tree-of-thoughts, plan-and-execute, naive-rag, self-refine, reflection,
debate, role-assignment).

# New category: cognition-introspection

Reorganise 9 patterns covering self-awareness, affect, transitional
state, and dream/consolidation cycles into a dedicated category:
awareness, dream-consolidation-cycle, emotional-state-persistence,
interrupt-resumable-thought, intra-agent-memo-scheduling,
mode-adaptive-cadence, preoccupation-tracking, self-archaeology,
world-model-separation. Adds entries in schema.json (enum),
docs/taxonomy.md, .github/scripts/render_html.py (CAT_LABEL).

# Redundancy fixes from a graph audit

- Drop bogus alias: lineage-tracking no longer claims "Prompt Versioning"
  as an alias (it's a different first-class pattern).
- goal-decomposition ↔ least-to-most: edge changed from alternative-to
  to complements (they sit at different layers — planner architecture vs
  prompting tactic, usable together).
- Add explicit "Distinct from X:" boundary lines to the Context slot of
  tool-discovery ↔ tool-agent-registry and orchestrator-workers ↔
  supervisor, where adjacent patterns sit close to each other.
- Mirror/inverse edges added across 26 pattern pairs so the typed graph
  balances (lint A4 passes).
- Constrains slot reworded for proactive-goal-creator and
  voting-based-cooperation to use explicit restriction wording.

# New derived artefact: patterns.graph.json

A typed-graph view of the catalog (nodes = patterns; edges = related[]
relations). 204 nodes, 1068 edges. Built by .github/scripts/build_graph.py
from patterns-src/ shards or patterns.json. Patterns.graph.schema.json
defines the shape. The .json output is gitignored alongside patterns.json
(both are derived from patterns-src/).

# Source verification

All 6 new patterns verified against upstream sources and marked
verified=true in verification-todo.json. Per-aspect walkthrough recorded:
intent <35 words, context/problem/solution prose match source, constrains
restriction-shaped, example_scenario + diagram + applicability populated,
URLs alive (incl. fixing Bedrock URL from old advanced-prompts-configure
to canonical prompt-management page), no undefined jargon, edges balance.

# Lint

All 15 rules pass (A6.3 URL liveness occasionally flags arxiv on transient
DNS failure — URLs content-verified alive on retry).

* Add 10 cognition-introspection patterns (204 -> 214, 14 categories)

# Patterns added (10, all in cognition-introspection)

  - open-question-tension-store       append-only ledger of unresolved pulls
                                       driving inquiry; intrusiveness gates
                                       ask-now vs store
  - cognitive-move-selector           idle-tick router over a small
                                       agent-vetted menu of named moves
  - parallel-voice-proposer           multi-voice candidates in one call,
                                       self-selected, losers logged as audit
  - pre-generative-loop-gate          pre-tick divergence detection that
                                       injects a steering hint, not a veto
  - multi-axis-promotion-scoring      six-axis weighted gate for short-to-
                                       long memory tier promotion;
                                       consolidation weighted over frequency
  - cluster-capped-insight-store      mechanical mtime-based dedup of
                                       insight files per stem-token cluster
  - meditation-mode                   runtime mode: external I/O paused,
                                       inner-only tool allowlist, bounded
                                       window with self/operator exit
  - partial-output-salvage            tmp+rename stream-to-disk + typed
                                       recovery marker propagates into the
                                       next prompt
  - typed-tool-loop-detector          dispatch-boundary veto with five typed
                                       failure modes and per-tool caps;
                                       returns a formatted refusal
  - affect-coupled-plan-lifecycle     bounded affect deltas on plan events
                                       plus age-bucketed stale-pain

# Supporting changes

  - 16 reverse edges added across 6 other shards so symmetric/inverse
    relations stay paired (A4 lint passes)
  - 10 verification-todo entries appended (sort order preserved by id)
  - INDEX.md regenerated; Cognition & Introspection now lists 19 patterns
    (10 new + 9 migrated by d5ba975)
  - README.md count: 179 -> 214, 13 -> 14 categories, 850 -> 1118 edges
  - pages.yml landing page count: 179 -> 214
  - lint.py allowlist extended for patterns.graph.schema.json (cleared
    pre-existing A2.2 carried in from d5ba975)

# Lint

All 15 lint rules pass; URL liveness clean on all 22 new references.

Author: luxxyarns

.github/scripts/build_graph.py

@@ -0,0 +1,93 @@
+#!/usr/bin/env python3
+"""Generate patterns.graph.json — a derived, machine-readable view of the catalog as a typed graph.
+
+Nodes: one per pattern (id, name, category, status_in_practice, aliases).
+Edges: one per related[] entry (source, target, relation).
+
+Consumers (graph queries, CI checks, architecture review tools) can build on this without
+parsing the full pattern shapes. Source of truth remains patterns-src/ shards / patterns.json.
+
+Run locally: python3 .github/scripts/build_graph.py [out_dir]
+Reads:  patterns-src/*.json (via build_patterns_json structure) or patterns.json if present.
+Writes: <out_dir>/patterns.graph.json  (default: repo root)
+"""
+from __future__ import annotations
+
+import json
+import sys
+from datetime import date
+from pathlib import Path
+
+ROOT = Path(__file__).resolve().parent.parent.parent
+SRC_PATTERNS_JSON = ROOT / "patterns.json"
+SRC_DIR = ROOT / "patterns-src"
+
+
+def load_patterns() -> tuple[list[dict], str, str]:
+    """Prefer patterns.json if available; else build from shards in patterns-src/."""
+    if SRC_PATTERNS_JSON.exists():
+        data = json.loads(SRC_PATTERNS_JSON.read_text())
+        return data["patterns"], data.get("version", "0.0.0"), data.get("license", "CC-BY-4.0")
+    patterns: list[dict] = []
+    seen_ids: set[str] = set()
+    for shard_path in sorted(SRC_DIR.glob("*.json")):
+        shard = json.loads(shard_path.read_text())
+        for p in shard["patterns"]:
+            if p["id"] in seen_ids:
+                raise SystemExit(f"duplicate pattern id: {p['id']}")
+            seen_ids.add(p["id"])
+            patterns.append(p)
+    patterns.sort(key=lambda p: (p["category"], p["id"]))
+    return patterns, "0.0.0", "CC-BY-4.0"
+
+
+def build(out_dir: Path) -> None:
+    out_dir.mkdir(parents=True, exist_ok=True)
+    patterns, version, license_ = load_patterns()
+
+    nodes = [
+        {
+            "id": p["id"],
+            "name": p["name"],
+            "category": p["category"],
+            "status": p.get("status_in_practice", "unknown"),
+            "aliases": p.get("aliases", []),
+        }
+        for p in patterns
+    ]
+
+    seen_ids = {p["id"] for p in patterns}
+    edges = [
+        {
+            "source": p["id"],
+            "target": r["pattern"],
+            "relation": r["relation"],
+        }
+        for p in patterns
+        for r in p.get("related", [])
+        if r["pattern"] in seen_ids
+    ]
+
+    out = {
+        "$schema": "./patterns.graph.schema.json",
+        "version": version,
+        "updated": date.today().isoformat(),
+        "license": license_,
+        "source": "patterns.json",
+        "node_count": len(nodes),
+        "edge_count": len(edges),
+        "nodes": nodes,
+        "edges": edges,
+    }
+    out_path = out_dir / "patterns.graph.json"
+    out_path.write_text(json.dumps(out, indent=2, ensure_ascii=False) + "\n")
+    print(f"wrote {out_path.relative_to(ROOT)}  ({len(nodes)} nodes, {len(edges)} edges)")
+
+
+def main() -> None:
+    out_dir = Path(sys.argv[1]) if len(sys.argv) > 1 else ROOT
+    build(out_dir)
+
+
+if __name__ == "__main__":
+    main()

.github/scripts/lint.py

@@ -266,6 +266,7 @@ def rule_a2() -> list[Violation]:
         "glossary.schema.json",
         "verification-todo.json",
         "verification-todo.schema.json",
+        "patterns.graph.schema.json",
     }
     allowed_dirs = {"patterns-src", "patterns", "docs", ".github"}
     for f in root_files:

.github/scripts/render_html.py

@@ -33,6 +33,7 @@
     "governance-observability": "Governance & Observability",
     "structure-data": "Structure & Data",
     "streaming-ux": "Streaming & UX",
+    "cognition-introspection": "Cognition & Introspection",
     "anti-patterns": "Anti-Patterns",
 }
 

.github/workflows/pages.yml

@@ -57,7 +57,7 @@ jobs:
             <h1>Agentic Patterns Catalog</h1>
             <p>Machine-readable reference of agentic design patterns in GoF/POSA form.</p>
             <ul>
-              <li><a href="patterns/"><code>patterns/</code></a> &mdash; browse the 179 patterns (rendered HTML, Mermaid diagrams)</li>
+              <li><a href="patterns/"><code>patterns/</code></a> &mdash; browse the 214 patterns (rendered HTML, Mermaid diagrams)</li>
               <li><a href="recipes/"><code>recipes/</code></a> &mdash; browse the named cross-category compositions</li>
               <li><a href="frameworks/"><code>frameworks/</code></a> &mdash; browse the framework coverage matrix</li>
             </ul>

.gitignore

@@ -26,5 +26,6 @@ NOTES.md
 SCRATCH.md
 TODO.local.md
 
-# Generated build artifact — patterns-src/ is the source of truth
+# Generated build artifacts — patterns-src/ is the source of truth
 patterns.json
+patterns.graph.json