diff --git a/examples/basic-case/phase-0-activation.json b/examples/basic-case/phase-0-activation.json index 449dd10..c8cba0d 100644 --- a/examples/basic-case/phase-0-activation.json +++ b/examples/basic-case/phase-0-activation.json @@ -4,9 +4,9 @@ "phase": "0", "mode": "sensemaking", "generated_at": "2026-03-29T10:00:00Z", - "validated_by_human": true, + "validated_by_human": false, "related_artifacts": [], - "decision_rationale": "Activation of Specula Method for a community library seeking to formalize governance around collection curation and community voice in decision-making.", + "decision_rationale": "Activation of the Specula Method for a community library seeking to formalize governance around collection curation and community voice in decision-making.", "evidence_refs": [ "Library board meeting notes (2026-03-15)", "Community survey on collection preferences (n=127)" diff --git a/examples/basic-case/phase-1-scenarios.json b/examples/basic-case/phase-1-scenarios.json index f1fe19a..4010913 100644 --- a/examples/basic-case/phase-1-scenarios.json +++ b/examples/basic-case/phase-1-scenarios.json @@ -4,9 +4,11 @@ "phase": "1", "mode": "exploration", "generated_at": "2026-03-29T11:15:00Z", - "validated_by_human": true, - "related_artifacts": ["basic-case-phase-0"], - "decision_rationale": "Four scenarios explore the library's evolution across 10 years under different cultural/economic/tech drivers. Essential for understanding which governance model protects against which futures.", + "validated_by_human": false, + "related_artifacts": [ + "basic-case-phase-0" + ], + "decision_rationale": "Four scenarios explore the library's evolution across 10 years under different cultural/economic/tech drivers, to understand which governance model protects against which futures.", "evidence_refs": [ "Local demographic trends (city planning dept)", "Digital library adoption rates in peer libraries", @@ -42,7 +44,7 @@ } ], "scenario_type": "preferred", - "description": "Library becomes true civic hub: expanded programs, robust collection, active community governance, financial stability.", + "description": "Library becomes a true civic hub: expanded programs, robust collection, active community governance, financial stability.", "maieutic_question": "What governance structure would best enable and protect this scenario?", "user_response": "A transparent, community-inclusive governance model that formalizes input from patrons and staff" }, @@ -57,16 +59,16 @@ }, { "type": "economic", - "description": "City budget cuts; library funding reduced by 40%" + "description": "City budget cuts reduce library funding by 40%" }, { "type": "cultural", - "description": "Cultural shift toward private (corporate) gathering spaces" + "description": "Cultural shift toward private, corporate gathering spaces" } ], "scenario_type": "feared", "description": "Library becomes marginal: reduced hours, minimal collection, volunteer-dependent, declining relevance.", - "maieutic_question": "What governance guardrails would allow the library to survive and eventually thrive even in this scenario?", + "maieutic_question": "What governance guardrails would let the library survive and eventually thrive even here?", "user_response": "Explicit commitment to core values (accessibility, equity, community voice) that survive budget cuts" }, { @@ -80,7 +82,7 @@ }, { "type": "tech", - "description": "Open-source tools allow libraries to offer services previously locked in corporate platforms" + "description": "Open-source tools let libraries offer services previously locked in corporate platforms" }, { "type": "economic", @@ -88,8 +90,8 @@ } ], "scenario_type": "wild_card", - "description": "Library becomes a node in a federated, community-controlled information network. Unexpected opportunity.", - "maieutic_question": "What governance principles would allow us to seize this opportunity while staying accountable to our community?", + "description": "Library becomes a node in a federated, community-controlled information network.", + "maieutic_question": "What governance principles would let us seize this opportunity while staying accountable?", "user_response": "Governance must be interoperable with other libraries while maintaining local autonomy" }, { @@ -103,7 +105,7 @@ }, { "type": "cultural", - "description": "Library becomes battleground for culture war issues" + "description": "Library becomes a battleground for culture-war issues" }, { "type": "economic", @@ -111,9 +113,9 @@ } ], "scenario_type": "negative", - "description": "Library loses independence; becomes tool of political faction; community loses trust.", - "maieutic_question": "What governance structures would protect democratic values and intellectual freedom even under political pressure?", - "user_response": "Clear separation between governance (community) and collection decisions; explicit intellectual freedom commitments" + "description": "Library loses independence; becomes a tool of a political faction; community loses trust.", + "maieutic_question": "What governance structures would protect intellectual freedom under political pressure?", + "user_response": "Clear separation between governance (community) and collection decisions; explicit intellectual-freedom commitments" } ] } diff --git a/examples/basic-case/phase-1.5-competitive-map.json b/examples/basic-case/phase-1.5-competitive-map.json index acaeb3e..88eec6b 100644 --- a/examples/basic-case/phase-1.5-competitive-map.json +++ b/examples/basic-case/phase-1.5-competitive-map.json @@ -2,50 +2,76 @@ "meta": { "artifact_id": "basic-case-phase-1.5", "phase": "1.5", - "mode": "exploration", + "mode": "convergence", "generated_at": "2026-03-29T12:30:00Z", - "validated_by_human": true, - "related_artifacts": ["basic-case-phase-1"], - "decision_rationale": "Competitive map identifies how the library differentiates from digital platforms and corporate community spaces. Critical for positioning collection and governance model.", + "validated_by_human": false, + "related_artifacts": [ + "basic-case-phase-1" + ], + "decision_rationale": "The competitive map identifies how the library differentiates from digital platforms and corporate community spaces, and where the strategic white spaces are.", "evidence_refs": [ "Amazon/Google services analysis", - "Competing bookstores and cafes in area", + "Competing bookstores and cafes in the area", "Other library governance models (3 case studies)" ], "tradeoffs": [ "May reveal uncomfortable truths about competitive disadvantage", - "Requires honest assessment of library's actual vs. perceived value" + "Requires honest assessment of the library's actual vs. perceived value" ], "rejected_alternatives": [ - "Ignoring competitive landscape (risk of obsolescence)", - "Competing on features where we'll always lose (speed, convenience)" + "Ignoring the competitive landscape (risk of obsolescence)", + "Competing on features where we always lose (speed, convenience)" ] }, "payload": { - "competitors": [ + "competitive_map": [ + { + "competitor": "Amazon & Digital Commerce", + "future_trajectory": "Deeper algorithmic personalization and on-demand delivery become the default way people discover content.", + "occupied_territory": "Convenience, infinite selection, instant access.", + "ignored_territories": [ + "Human curation", + "Community trust", + "Serendipitous discovery", + "Equity of access" + ], + "confidence_level": "high" + }, { - "competitor_id": "amazon-market", - "name": "Amazon & Digital Commerce", - "positioning": "On-demand, infinite selection, convenience, personalized algorithms", - "strengths": ["Instant delivery", "Perfect personalization", "24/7 access"], - "weaknesses": ["No community", "Algorithm-driven curation", "Corporate ownership"], - "library_differentiation": "Human curation, community values, local trust, serendipity" + "competitor": "Coffee Shop & Bookstore", + "future_trajectory": "Premiumized social spaces monetize aesthetics and curated selection for paying customers.", + "occupied_territory": "Ambiance, social gathering, curated retail experience.", + "ignored_territories": [ + "Free access", + "Comprehensive collection", + "Community-driven curation" + ], + "confidence_level": "medium" }, { - "competitor_id": "coffee-shop", - "name": "Coffee Shop & Bookstore", - "positioning": "Aesthetics, social gathering, experience", - "strengths": ["Pleasant ambiance", "Curated selection", "Integrated commerce"], - "weaknesses": ["Expensive", "Selection limited", "Profit-driven"], - "library_differentiation": "Free access, comprehensive collection, community-driven collection, equity focus" + "competitor": "Parks & Community Centers", + "future_trajectory": "Civic gathering spaces expand but remain disconnected from knowledge and learning resources.", + "occupied_territory": "Low-cost accessible community gathering.", + "ignored_territories": [ + "Knowledge resources", + "Intellectual freedom", + "Diverse perspectives" + ], + "confidence_level": "medium" + } + ], + "white_spaces": [ + { + "white_space_id": "ws-curation-trust", + "description": "Human-curated, community-governed knowledge with transparent, non-algorithmic collection decisions.", + "strategic_risk": "low", + "alignment_with_brand": "high" }, { - "competitor_id": "civic-space", - "name": "Parks, Community Centers, Civic Spaces", - "positioning": "Community gathering, free/low-cost, accessible", - "strengths": ["Low cost", "Accessible", "Community focus"], - "weaknesses": ["No information/learning resources", "Fragmented purpose"], - "library_differentiation": "Knowledge + community integration, intellectual freedom, diverse perspectives" + "white_space_id": "ws-federated-autonomy", + "description": "Interoperable governance across libraries that preserves local autonomy and community accountability.", + "strategic_risk": "medium", + "alignment_with_brand": "high" } ] } diff --git a/examples/basic-case/phase-2-brand-dna.json b/examples/basic-case/phase-2-brand-dna.json index 1b8a450..5ce02a5 100644 --- a/examples/basic-case/phase-2-brand-dna.json +++ b/examples/basic-case/phase-2-brand-dna.json @@ -2,11 +2,14 @@ "meta": { "artifact_id": "basic-case-phase-2", "phase": "2", - "mode": "synthesis", + "mode": "brand_archaeology", "generated_at": "2026-03-29T14:00:00Z", - "validated_by_human": true, - "related_artifacts": ["basic-case-phase-1", "basic-case-phase-1.5"], - "decision_rationale": "Brand DNA synthesizes library's essential identity from scenarios and competitive position. Guides all downstream governance and collection decisions.", + "validated_by_human": false, + "related_artifacts": [ + "basic-case-phase-1", + "basic-case-phase-1.5" + ], + "decision_rationale": "Brand DNA synthesizes the library's essential identity from scenarios and competitive position, guiding all downstream governance and collection decisions.", "evidence_refs": [ "Phase 1 scenarios (esp. Civic Hub preferred, Politicized feared)", "Phase 1.5 competitive map (library's unique strengths)", @@ -22,38 +25,44 @@ ] }, "payload": { - "brand_name": "Community Library Collective", - "tagline": "Knowledge, trust, and community voice at the center", - "core_values": [ - { - "value": "Intellectual Freedom", - "definition": "We protect the right to seek, share, and challenge ideas—without censorship or algorithmic control.", - "governance_implication": "Collection decisions made by community, not corporate algorithms or political pressure" - }, - { - "value": "Equity & Access", - "definition": "We ensure everyone—regardless of income, education, or ability—can access knowledge and community.", - "governance_implication": "Free access, materials in multiple formats, staff trained in accessibility" - }, - { - "value": "Community Voice", - "definition": "We are governed by and accountable to the community we serve, not distant corporate or political entities.", - "governance_implication": "Formal governance structure with community representation; transparent decision-making" - }, - { - "value": "Serendipity & Discovery", - "definition": "We believe unexpected encounters with books, people, and ideas enrich life in ways algorithms can't replicate.", - "governance_implication": "Diverse collection curated by humans, community curation alongside expert curation" + "brand_dna": { + "radical_values": [ + { + "value": "Intellectual freedom", + "tested_in": "A 2025 challenge to remove several titles from the shelves after political pressure.", + "cost_paid": "Lost a conditional grant tied to removing the contested titles." + }, + { + "value": "Equity of access", + "tested_in": "Debate over introducing paid premium services to close a budget gap.", + "cost_paid": "Forwent recurring premium-subscription revenue to keep all services free." + }, + { + "value": "Community voice", + "tested_in": "Pressure to let a single donor dictate collection priorities.", + "cost_paid": "Declined a major earmarked donation to preserve community governance." + } + ], + "accepted_biases": [ + "Preference for local and independent authors over bestseller optimization", + "Bias toward physical and hybrid gathering over purely digital delivery" + ], + "moral_entity": "A community-accountable steward of knowledge that treats access to information as a public good rather than a product.", + "refusal_zones": [ + "Algorithmic collection decisions driven by engagement metrics", + "Censorship of lawful materials under political or commercial pressure", + "Selling or brokering patron data" + ], + "tensions": { + "acceptable": [ + "Slower decisions in exchange for transparent community deliberation", + "Narrower bestseller selection in exchange for diverse, curated breadth" + ], + "unacceptable": [ + "Trading intellectual freedom for funding", + "Trading equity of access for short-term revenue" + ] } - ], - "brand_archetype": "The Mentor / Sage (trusted guide to knowledge) + The Everyman (for everyone, no gatekeepers)", - "tone_voice": { - "tone": "Warm, accessible, intellectually serious but not elitist", - "voice_elements": [ - "We speak directly, not in jargon", - "We admit what we don't know", - "We center community perspective, not expert authority" - ] } } } diff --git a/examples/basic-case/phase-3-prototypes.json b/examples/basic-case/phase-3-prototypes.json index e93f12d..ad75db0 100644 --- a/examples/basic-case/phase-3-prototypes.json +++ b/examples/basic-case/phase-3-prototypes.json @@ -1,51 +1,91 @@ { "meta": { - "artifact_id": "basic-case-phase-3-proto", + "artifact_id": "basic-case-phase-3-prototypes", "phase": "3", - "mode": "validation", + "mode": "prototyping", "generated_at": "2026-03-29T15:30:00Z", - "validated_by_human": true, - "related_artifacts": ["basic-case-phase-2"], - "decision_rationale": "Three governance prototypes test different approaches to community voice while protecting core values (intellectual freedom, equity, accessibility).", + "validated_by_human": false, + "related_artifacts": [ + "basic-case-phase-1", + "basic-case-phase-2" + ], + "decision_rationale": "Prototypes translate the preferred and wild-card scenarios into concrete services, each passed through the ethical gate before adoption.", "evidence_refs": [ - "Comparison of 5 public library governance models", - "Community input on preferred decision-making styles", - "Staff capacity assessment" + "Phase 1 scenarios", + "Phase 2 brand DNA", + "Volunteer capacity assessment (2026-03)" ], "tradeoffs": [ - "More inclusive governance takes longer initially", - "Testing multiple models extends timeline before final choice" + "Ambitious prototypes strain volunteer capacity", + "Federation increases interoperability but reduces unilateral control" ], "rejected_alternatives": [ - "Single approach (no opportunity for community learning)", - "Governance without explicit ethical gates (risks value compromise)" + "Corporate discovery platform (violates refusal zones)", + "Donor-directed collection (violates community voice)" ] }, "payload": { "prototypes": [ { - "prototype_id": "lib-proto-delegated", - "name": "Delegated Curation Model", - "description": "Expert librarians make collection decisions; community provides input via surveys and reviews; governance council monitors for alignment with brand values.", - "how_tested": "3-month pilot with 50 community members on advisory board", - "expected_insight": "How much community involvement is optimal? Where does scale break?", - "governance_question": "Can we maintain community voice while keeping decisions efficient?" - }, - { - "prototype_id": "lib-proto-participatory", - "name": "Participatory Curation Model", - "description": "Community members vote on contested titles; librarians curate foundational collection; mixed governance board has equal community/staff representation.", - "how_tested": "6-month pilot with voting mechanism for 20 contested titles", - "expected_insight": "What level of community participation can we sustain without overwhelm?", - "governance_question": "Does participatory curation strengthen community ownership or create conflict?" + "prototype_id": "proto-civic-hub", + "scenario_id": "lib-pref", + "description": "A community-governed programming calendar where patrons propose and vote on events and acquisitions.", + "role_in_future": "Anchors the library as an active civic hub with formalized community input.", + "stakeholder_impact": { + "winners": [ + "Patrons", + "Local authors", + "Volunteers" + ], + "losers": [ + "Staff who preferred informal, faster decisions" + ] + }, + "ethical_gate": { + "status": "PASS", + "violated_values": [], + "systemic_impact": "aligned", + "question_1_value_violation_rationale": "No radical value is violated; community voice and equity are strengthened.", + "question_2_harmful_practice_rationale": "No harmful practice: voting is transparent and open to all patrons.", + "question_3_unacceptable_dependency_rationale": "No unacceptable dependency; the tool is open-source and self-hosted.", + "reviewer_decision_refs": [ + { + "validator_role": "Library board chair", + "decision": "approve", + "reference": "board-min-2026-03-29#civic-hub" + } + ] + } }, { - "prototype_id": "lib-proto-algorithmic", - "name": "Algorithmic Curation Model", - "description": "Use open-source tools (not corporate algorithms) to recommend titles based on community reading patterns; community/librarian council maintains ethical override capability.", - "how_tested": "3-month pilot with recommendation tool in library app", - "expected_insight": "Can we get algorithmic benefits without losing community voice or intellectual freedom?", - "governance_question": "Does algorithmic assistance improve discovery or erode human judgment?" + "prototype_id": "proto-federated-network", + "scenario_id": "lib-wild", + "description": "A federated catalog letting peer libraries share holdings and governance patterns while retaining local autonomy.", + "role_in_future": "Positions the library as a node in a community-controlled information network.", + "stakeholder_impact": { + "winners": [ + "Patrons", + "Peer libraries" + ], + "losers": [ + "Vendors of proprietary catalog software" + ] + }, + "ethical_gate": { + "status": "HOLD", + "violated_values": [], + "systemic_impact": "aligned", + "question_1_value_violation_rationale": "No value violated, but data-sharing terms across libraries need review.", + "question_2_harmful_practice_rationale": "No harmful practice, provided patron data is not shared across nodes.", + "question_3_unacceptable_dependency_rationale": "Held pending confirmation that no single node can control others' collections.", + "reviewer_decision_refs": [ + { + "validator_role": "Data governance reviewer", + "decision": "hold", + "reference": "review-2026-03-29#federation-data" + } + ] + } } ] } diff --git a/examples/basic-case/phase-3-refusals.json b/examples/basic-case/phase-3-refusals.json index e909a18..85ad552 100644 --- a/examples/basic-case/phase-3-refusals.json +++ b/examples/basic-case/phase-3-refusals.json @@ -1,55 +1,69 @@ { "meta": { - "artifact_id": "basic-case-phase-3-refusal", + "artifact_id": "basic-case-phase-3-refusals", "phase": "3", - "mode": "validation", - "generated_at": "2026-03-29T15:45:00Z", - "validated_by_human": true, - "related_artifacts": ["basic-case-phase-2", "basic-case-phase-3-proto"], - "decision_rationale": "Explicit refusals clarify what the library will NOT do, even under pressure. These refusals protect core identity and prevent drift.", + "mode": "refusal_register", + "generated_at": "2026-03-29T16:00:00Z", + "validated_by_human": false, + "related_artifacts": [ + "basic-case-phase-2", + "basic-case-phase-3-prototypes" + ], + "decision_rationale": "Refusals record prototypes rejected at the ethical gate, preserving the identity signal each refusal sends.", "evidence_refs": [ - "Community value commitments (Phase 2)", - "Feared scenarios (Phase 1: Politicized & Captured)", - "Case studies of libraries that compromised values" + "Phase 2 brand DNA refusal zones", + "Phase 3 prototype reviews" ], "tradeoffs": [ - "Explicit refusals create rigid commitments", - "But lack of refusals risks slow value erosion" + "Refusing revenue-generating options constrains the budget", + "Documenting refusals invites external scrutiny" ], "rejected_alternatives": [ - "No formal refusals (risk of incremental compromise)", - "Conditional refusals (defeat the purpose)" + "Silently dropping rejected ideas (loses the learning signal)", + "Deferring all refusals to staff discretion (loses accountability)" ] }, "payload": { "refusals": [ { - "refusal_id": "lib-refuse-censorship", - "violated_value": "Intellectual Freedom", - "refusal": "We refuse to remove books based on political, religious, or cultural pressure—from any source.", - "boundary": "We DO respond to legitimate content errors (factual corrections, accessibility); we DO NOT remove books for ideology.", - "escalation": "If pressured to censor: (1) document request, (2) convene ethics committee, (3) explain decision publicly, (4) appeal to library association for support" - }, - { - "refusal_id": "lib-refuse-algorithmic-control", - "violated_value": "Intellectual Freedom + Community Voice", - "refusal": "We refuse to use corporate algorithms (Google, Amazon, Apple) to curate or recommend library collection.", - "boundary": "We DO use open-source, community-controlled tools; we DO preserve human librarian judgment; we DO maintain community override.", - "escalation": "If tempted by corporate partnerships: (1) audit for value alignment, (2) require community vote, (3) keep human librarians in decision loop" - }, - { - "refusal_id": "lib-refuse-user-surveillance", - "violated_value": "Equity + Community Trust", - "refusal": "We refuse to track, profile, or monetize patron reading habits.", - "boundary": "We DO collect aggregate usage stats for planning; we DO NOT create individual patron profiles or sell data.", - "escalation": "If facing budget pressure to monetize data: (1) explore alternative funding, (2) convene board, (3) prefer to reduce hours rather than compromise trust" + "refusal_id": "refusal-engagement-ranking", + "prototype_id": "proto-engagement-feed", + "violated_value": "Intellectual freedom", + "opportunity_cost": "Higher circulation numbers from an engagement-optimized recommendation feed.", + "identity_signal": "The library does not let engagement metrics decide what knowledge is visible.", + "date": "2026-03-29T16:05:00Z", + "ethical_gate_assessment": { + "question_1_value_violation_rationale": "Ranking by engagement violates intellectual freedom by suppressing low-engagement but important works.", + "question_2_harmful_practice_rationale": "It reproduces filter-bubble dynamics the library exists to counter.", + "question_3_unacceptable_dependency_rationale": "It would create dependency on an opaque ranking model outside community control.", + "reviewer_decision_refs": [ + { + "validator_role": "Library board chair", + "decision": "reject", + "reference": "board-min-2026-03-29#engagement-feed" + } + ] + } }, { - "refusal_id": "lib-refuse-unequal-access", - "violated_value": "Equity & Access", - "refusal": "We refuse to create tiered access (premium collections for paid members, restricted collections for low-income patrons).", - "boundary": "We DO have specialized collections for experts; they are free to ALL patrons. We DO NOT segregate by ability to pay.", - "escalation": "If facing budget cuts that might force tiering: (1) convene board and community, (2) reduce scope before reducing equity, (3) seek alternative funding" + "refusal_id": "refusal-donor-collection", + "prototype_id": "proto-donor-directed", + "violated_value": "Community voice", + "opportunity_cost": "A major earmarked donation contingent on donor-directed acquisitions.", + "identity_signal": "Collection priorities are set by the community, not by individual funders.", + "date": "2026-03-29T16:10:00Z", + "ethical_gate_assessment": { + "question_1_value_violation_rationale": "Donor-directed collection violates community voice by transferring curation authority to a single funder.", + "question_2_harmful_practice_rationale": "It normalizes pay-to-curate influence over a public institution.", + "question_3_unacceptable_dependency_rationale": "It creates financial dependency that could be withdrawn to coerce future decisions.", + "reviewer_decision_refs": [ + { + "validator_role": "Governance committee", + "decision": "reject", + "reference": "review-2026-03-29#donor-directed" + } + ] + } } ] } diff --git a/examples/basic-case/phase-4-narrative.json b/examples/basic-case/phase-4-narrative.json index 84c825d..afac5a1 100644 --- a/examples/basic-case/phase-4-narrative.json +++ b/examples/basic-case/phase-4-narrative.json @@ -2,53 +2,56 @@ "meta": { "artifact_id": "basic-case-phase-4", "phase": "4", - "mode": "synthesis", + "mode": "narrative_synthesis", "generated_at": "2026-03-29T17:00:00Z", - "validated_by_human": true, - "related_artifacts": ["basic-case-phase-2", "basic-case-phase-3-refusal"], - "decision_rationale": "Narrative system translates brand DNA and refusals into language that resonates with different community audiences (patrons, city council, donors, staff).", + "validated_by_human": false, + "related_artifacts": [ + "basic-case-phase-2", + "basic-case-phase-3-prototypes" + ], + "decision_rationale": "The narrative system aligns products, services, AI agents, and community around a single meta-narrative rooted in the brand DNA.", "evidence_refs": [ - "Community survey on values (Phase 2)", - "Refusal decisions (Phase 3)", - "Messaging analysis of peer libraries" + "Phase 2 brand DNA", + "Phase 3 prototypes and refusals" ], "tradeoffs": [ - "Multiple narratives require consistent underlying values", - "Different audiences need different language, same substance" + "A strong meta-narrative can feel constraining to some staff", + "Explicit dynamic rules reduce ad-hoc flexibility" ], "rejected_alternatives": [ - "Single narrative (doesn't speak to diverse stakeholders)", - "Inconsistent narratives across audiences (erodes trust)" + "Marketing-led tagline with no governance grounding", + "Separate, uncoordinated narratives per channel" ] }, "payload": { - "core_narrative": "We are a community library reimagined as a democratic institution. We protect intellectual freedom, guarantee equitable access, and govern ourselves through community voice—not corporate algorithms or political control.", - "audience_narratives": [ - { - "audience": "Patrons & Community Members", - "narrative": "This is YOUR library. We exist to serve your curiosity, your research, your joy in reading—not to profit from you or control what you think. Your voice shapes our decisions.", - "proof_points": ["Community governance board", "Free for all", "No surveillance", "Transparent collection decisions"] - }, - { - "audience": "City Council & Budget Decision Makers", - "narrative": "We are a cost-effective civic institution that builds social cohesion, supports literacy, and strengthens democratic participation. We're fiscally responsible stewards of public investment.", - "proof_points": ["Transparent budget", "Clear metrics for impact", "Engaged governance", "Strong community support"] + "narrative_system": { + "meta_narrative": { + "statement": "Knowledge is a public good, and the community that shares it decides how it is kept, curated, and grown.", + "supported_values": [ + "Intellectual freedom", + "Equity of access", + "Community voice", + "Serendipity and discovery" + ] }, - { - "audience": "Donors & Philanthropists", - "narrative": "Invest in a library that proves democracy can work at the local level. We're building a model of community governance that protects intellectual freedom while building trust.", - "proof_points": ["Innovative governance", "Strong values alignment", "Community impact", "Transparent spending"] + "storylines": { + "products": "The physical and digital collection is framed as a shared commons, curated by humans and accountable to patrons.", + "services": "Programs and access services are described as invitations to participate in governing the commons, not consumer transactions.", + "ai_agents": "Any AI assistant surfaces options, assumptions, and trade-offs for human decision, and never ranks knowledge by engagement.", + "community": "Patrons are co-stewards: they propose, deliberate, and vote on acquisitions and programs." }, - { - "audience": "Library Staff & Volunteers", - "narrative": "You are not order-takers. You are partners in a governance experiment that respects professional expertise, community input, and your own intellectual growth.", - "proof_points": ["Staff on governance board", "Professional development funding", "Clear values", "Democratic decision-making"] - } - ], - "key_messages": [ - "Intellectual freedom isn't luxury—it's essential infrastructure for democracy", - "Community-governed institutions can be more responsive than corporate or purely top-down models", - "Equity and efficiency aren't opposed; shared decision-making builds sustainable community support" - ] + "dynamic_rules": [ + { + "if": "A collection decision faces political or commercial pressure", + "then": "escalate to transparent community deliberation", + "while": "protecting intellectual freedom and documenting the refusal if applicable" + }, + { + "if": "An AI feature is proposed", + "then": "require it to expose assumptions and trade-offs rather than prescribe a single answer", + "while": "keeping ranking models out of collection visibility" + } + ] + } } } diff --git a/examples/basic-case/phase-5-cocreation.json b/examples/basic-case/phase-5-cocreation.json index a83898d..3d87620 100644 --- a/examples/basic-case/phase-5-cocreation.json +++ b/examples/basic-case/phase-5-cocreation.json @@ -2,98 +2,56 @@ "meta": { "artifact_id": "basic-case-phase-5", "phase": "5", - "mode": "emergence", - "generated_at": "2026-03-29T18:30:00Z", - "validated_by_human": true, - "related_artifacts": ["basic-case-phase-4"], - "decision_rationale": "Community co-creation operationalizes governance promises. Specific mechanisms, roles, and decision-making processes that transform Phase 4 narrative into lived practice.", + "mode": "community_cocreation", + "generated_at": "2026-03-29T18:00:00Z", + "validated_by_human": false, + "related_artifacts": [ + "basic-case-phase-4" + ], + "decision_rationale": "A community workshop tested the narrative system and governance model, recording consensus, divergences, and dissent.", "evidence_refs": [ - "Phase 4 narrative commitments", - "Governance model examples from other libraries", - "Community input on preferred participation methods" + "Community co-creation workshop notes (2026-03-28)", + "Phase 4 narrative system" ], "tradeoffs": [ - "Formal co-creation mechanisms take time and resources", - "Without them, narrative commitments remain aspirational" + "Recording dissent slows sign-off", + "Honoring minority voices can delay consensus" ], "rejected_alternatives": [ - "Narrative without mechanisms (theater, not real governance)", - "Mechanisms without narrative (people don't understand why)" + "Consultation theater with no recorded dissent", + "Board-only approval without community input" ] }, "payload": { - "governance_structure": { - "council_name": "Community Governance Council", - "composition": [ - { - "role": "Community Members", - "count": 7, - "selection": "Elected annually by community vote (24-month term possible)", - "responsibility": "Represent patron interests; vote on major collection and budget decisions" - }, - { - "role": "Library Staff Representatives", - "count": 2, - "selection": "Elected by staff", - "responsibility": "Represent staff expertise and operational constraints" - }, - { - "role": "Library Director", - "count": 1, - "selection": "Hired by Council; reports to Council", - "responsibility": "Execute Council decisions; manage day-to-day operations" - } + "co_creation": { + "consensus_areas": [ + "Free access must remain non-negotiable", + "Collection decisions belong to the community, not funders or algorithms", + "AI must assist deliberation, not replace it" ], - "decision_types": [ - { - "decision": "Annual budget allocation", - "authority": "Council votes; majority required", - "timeline": "3 months before fiscal year" - }, - { - "decision": "Contested collection items", - "authority": "Community vote (advisory); Council decides with community input", - "timeline": "30-day comment period" - }, + "divergences": [ { - "decision": "Major policy changes (hours, fees, partnerships)", - "authority": "Council votes; 2/3 majority required", - "timeline": "30-day notice and community comment" - }, - { - "decision": "Hiring/firing Director", - "authority": "Council votes; unanimous on firing", - "timeline": "Annual performance review; 60 days for change process" + "topic": "Speed vs. deliberation in acquisitions", + "positions": [ + "Faster staff-led acquisition for time-sensitive titles", + "All acquisitions through community voting" + ], + "minority_voices": [ + "A subgroup wanted a fast-track lane capped at 10% of the budget" + ] } + ], + "accepted_changes": [ + "Introduce a transparent fast-track lane capped at 10% of the acquisition budget", + "Publish quarterly refusal summaries to patrons" + ], + "rejected_changes": [ + "Fully staff-controlled acquisitions", + "Engagement-based recommendation ranking" + ], + "dissent_log": [ + "Two participants formally dissented from any fast-track lane, citing risk of eroding community voice; dissent recorded for review at Phase 6." ] - }, - "participation_mechanisms": [ - { - "mechanism": "Open Council Meetings", - "frequency": "Monthly, open to public", - "purpose": "Transparency; community observation and input" - }, - { - "mechanism": "Community Comment Period", - "frequency": "Before major decisions", - "purpose": "Structured input on policies, collection, budget" - }, - { - "mechanism": "Annual Community Assembly", - "frequency": "Once per year", - "purpose": "Strategic direction-setting; open discussion of vision" - }, - { - "mechanism": "Specialty Advisory Committees", - "frequency": "Monthly or as needed", - "purpose": "Deep input on collections (youth, seniors, multilingual, etc.)" - } - ], - "accountability_mechanisms": [ - "Annual public report on governance decisions", - "Community feedback survey", - "Council performance review by community", - "Conflict resolution process (mediation before escalation)" - ] + } } } diff --git a/examples/basic-case/phase-6-guardian.json b/examples/basic-case/phase-6-guardian.json index 0576d13..edab8ef 100644 --- a/examples/basic-case/phase-6-guardian.json +++ b/examples/basic-case/phase-6-guardian.json @@ -2,75 +2,54 @@ "meta": { "artifact_id": "basic-case-phase-6", "phase": "6", - "mode": "governance", - "generated_at": "2026-03-29T19:45:00Z", - "validated_by_human": true, - "related_artifacts": ["basic-case-phase-5"], - "decision_rationale": "Guardian mechanisms detect and respond to drift from core values. Enables self-correction without external intervention, protecting long-term institutional identity.", + "mode": "guardian", + "generated_at": "2026-06-29T09:00:00Z", + "validated_by_human": false, + "related_artifacts": [ + "basic-case-phase-1", + "basic-case-phase-5" + ], + "decision_rationale": "The first quarterly Guardian review checks the governance model against the scenarios and flags any drift.", "evidence_refs": [ - "Refusals (Phase 3): what we protect against", - "Governance structure (Phase 5): how we decide", - "Case studies of institutions losing values over time" + "Q2 2026 circulation and program data", + "Phase 1 scenarios", + "Phase 5 co-creation outcomes" ], "tradeoffs": [ - "Guardian processes can feel bureaucratic", - "But without them, values drift is nearly inevitable in institutional aging" + "Quarterly review adds overhead", + "Acting on weak signals risks overcorrection" ], "rejected_alternatives": [ - "No Guardian (values erode slowly)", - "External Guardian (loses local accountability)" + "Annual-only review (misses early drift)", + "No formal monitoring (identity drift goes unnoticed)" ] }, "payload": { - "guardian_mandate": "Detect, document, and escalate any drift from core values (Intellectual Freedom, Equity, Community Voice, Serendipity) and trigger correction processes.", - "monitoring_mechanisms": [ - { - "mechanism": "Annual Values Audit", - "frequency": "Once per year", - "question": "Are we living our four core values? Where are we drifting?", - "owner": "Governance Council + community committee", - "output": "Values report with findings and recommendations" - }, - { - "mechanism": "Refusal Registry", - "frequency": "Continuous monitoring", - "question": "Have any of our core refusals been violated or pressured?", - "owner": "Director + Council", - "output": "Incident log; escalation to Council if violations occur" + "guardian_report": { + "quarter": "2026-Q2", + "scenario_alignment": { + "confirming": [ + "Community governance participation rose, consistent with the Civic Hub scenario" + ], + "contradicting": [ + "Digital-only usage grew faster than expected, echoing the Irrelevance scenario" + ], + "emerging": [ + "Interest from two peer libraries in a federated catalog, echoing the Hyperlocal Powerhouse scenario" + ] }, - { - "mechanism": "Community Feedback Loop", - "frequency": "Quarterly surveys + annual comment period", - "question": "Do community members feel heard? Do they trust our values?", - "owner": "Governance Council", - "output": "Feedback report; comparison to previous years" - } - ], - "escalation_protocol": [ - { - "level": 1, - "trigger": "Minor drift detected (e.g., single complaint about censorship attempt)", - "response": "Document incident; discuss in Council; communicate decision publicly", - "timeline": "30 days" + "coherence": { + "consistent": [ + "Free access maintained", + "No engagement-based ranking introduced", + "Refusal summaries published as agreed" + ], + "inconsistent": [ + "Fast-track lane briefly exceeded its 10% budget cap in one month" + ] }, - { - "level": 2, - "trigger": "Pattern of drift (e.g., multiple complaints; staff concerns about erosion)", - "response": "Convene special governance committee; audit decisions; report to community", - "timeline": "60 days" - }, - { - "level": 3, - "trigger": "Fundamental violation (e.g., major censorship; removal of Director without due process)", - "response": "Community assembly; consider reconstitution of Council; possible external arbitration", - "timeline": "90 days" - } - ], - "long_term_value_preservation": { - "mechanism": "Constitution Document", - "description": "Written library constitution (reviewed every 5 years) that codifies values, governance structure, and refusals", - "purpose": "Survives individual Council members; provides continuity across generations", - "protected_by": "Community vote required to amend (2/3 majority); constitutional convention every 10 years" + "divergence_level": "drift", + "recommended_action": "correct" } } } diff --git a/tests/test_examples.py b/tests/test_examples.py new file mode 100644 index 0000000..cfd3c51 --- /dev/null +++ b/tests/test_examples.py @@ -0,0 +1,56 @@ +"""Contract test: every basic-case example must validate against its phase schema. + +This closes the gap where the runtime test-suite exercised the orchestrator but +never validated the shipped `examples/` against `schemas/`. See governance: +schemas are the declared "single source of truth", so examples are contracts too. +""" +import json +from pathlib import Path + +import pytest +from jsonschema import Draft202012Validator + +REPO = Path(__file__).resolve().parent.parent +EXAMPLES = REPO / "examples" / "basic-case" +SCHEMAS = REPO / "schemas" + +# example filename -> schema filename +EXAMPLE_SCHEMA_MAP = { + "phase-0-activation.json": "phase0_activation.schema.json", + "phase-1-scenarios.json": "phase1_scenarios.schema.json", + "phase-1.5-competitive-map.json": "phase1_5_competitive_map.schema.json", + "phase-2-brand-dna.json": "phase2_brand_dna.schema.json", + "phase-3-prototypes.json": "phase3_prototypes.schema.json", + "phase-3-refusals.json": "phase3_refusals.schema.json", + "phase-4-narrative.json": "phase4_narrative_system.schema.json", + "phase-5-cocreation.json": "phase5_cocreation.schema.json", + "phase-6-guardian.json": "phase6_guardian.schema.json", +} + + +def _load(path: Path): + with path.open(encoding="utf-8") as fh: + return json.load(fh) + + +@pytest.mark.parametrize("example_name,schema_name", sorted(EXAMPLE_SCHEMA_MAP.items())) +def test_example_validates_against_schema(example_name, schema_name): + example_path = EXAMPLES / example_name + schema_path = SCHEMAS / schema_name + assert example_path.exists(), f"missing example: {example_path}" + assert schema_path.exists(), f"missing schema: {schema_path}" + + validator = Draft202012Validator(_load(schema_path)) + errors = sorted(validator.iter_errors(_load(example_path)), key=lambda e: list(e.path)) + if errors: + details = "\n".join( + f" - {'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in errors + ) + pytest.fail(f"{example_name} fails {schema_name} ({len(errors)} errors):\n{details}") + + +def test_every_example_is_mapped(): + """Guard: a new example file without a schema mapping should fail loudly.""" + on_disk = {p.name for p in EXAMPLES.glob("*.json")} + unmapped = on_disk - set(EXAMPLE_SCHEMA_MAP) + assert not unmapped, f"examples without a schema mapping: {sorted(unmapped)}"