opencode-skills-collection 4.1.15 → 4.1.16

package/bundled-skills/polis-protocol-a-self-optimizing-city-of-agents/references/amendments.md

@@ -0,0 +1,146 @@
+# Amendments Reference
+
+Deeper guidance on the amendment mechanism: when to use it, when to skip it, how quorum works, and worked examples.
+
+## When an amendment is the right move
+
+An amendment is a structural change to how the polis works. Reach for it when:
+
+- The same kind of friction has come up in three or more contracts. (Once is bad luck, twice is coincidence, three times is a pattern, and patterns belong in the protocol.)
+- The CONSTITUTION.md is silent or contradictory on something the team keeps running into.
+- A file schema needs an extra field, a rule needs softening or tightening, or a default value is wrong for this project.
+- The routing weights are obviously miscalibrated for this team's actual mix of citizens.
+
+## When an amendment is not the right move
+
+Some things look like protocol problems but are not. Do not propose an amendment for:
+
+- A one-off bad outcome. File a lesson instead.
+- A miscommunication between two citizens. Use inboxes.
+- A capability card that is wrong about its own ratings. The owner edits their card directly; no amendment needed.
+- A contract that was poorly scoped. Reopen or split the contract.
+- A bug in `init_polis.py` or other scripts. Fix the script; no constitutional change required.
+
+The bar for an amendment is real cost to multiple citizens, not personal preference.
+
+## Quorum rules
+
+A quorum is the number of `agree` responses required for an amendment to ratify. Default quorum is a simple majority of "active" citizens, where:
+
+- A citizen is **active** if they have posted at least one chronicle line in the last 14 days.
+- Active citizens whose state is `away` count as inactive for quorum purposes.
+- The amendment proposer's own vote counts as an `agree`.
+
+For a polis with 5 active citizens, default quorum is 3 (including the proposer). For a polis with 2 active citizens, both must agree.
+
+### Adjusting quorum for specific amendments
+
+The amendment file's `quorum_required` field can be set higher than the default for amendments that touch sensitive parts of the protocol. Suggested overrides:
+
+| Amendment touches | Suggested quorum |
+|---|---|
+| Routing weights or explore rate | Default (most of the team) |
+| File schemas (chronicle line grammar, etc.) | Default + 1 |
+| The amendment process itself | Unanimous among active citizens |
+| Constitution language only (clarifications, no behavioral change) | Default - 1 |
+
+Lower-quorum amendments still respect a hard floor of 2 agreeing citizens. A polis of one is not a polis.
+
+## The lifecycle, in detail
+
+```
+proposed -> { agreed | disagreed | request_changes } -> ratified | rejected | expired
+                                  |
+                                  v
+                          revised by proposer -> back to proposed
+```
+
+### proposed
+File exists in `amendments/proposed/`. Chronicle has a `proposed amendment` line. The proposer has notified every active citizen via their inbox.
+
+### Voting
+Each active citizen appends a response block to the amendment file. The proposer (or any citizen) checks the `agree` count against `quorum_required` periodically.
+
+### request_changes
+If one or more citizens append a `request_changes` response with specific suggestions, the proposer can revise the `Proposed change` and `Rationale` sections. When the proposer revises, all prior votes reset; voting restarts. The proposer posts a `revised amendment` line to the chronicle (free-form verb).
+
+### ratified
+When `agree` count reaches `quorum_required`:
+
+1. Move the file from `amendments/proposed/` to `amendments/ratified/`.
+2. Set `status: ratified` and `ratified_at: <timestamp>` in frontmatter.
+3. Edit `_polis/CONSTITUTION.md` to incorporate the change.
+4. Update any affected templates in this skill, or note in the constitution that this polis diverges from the default skill.
+5. Post one `ratified amendment` line to the chronicle.
+
+### rejected
+If `disagree` count exceeds the remaining `agree` headroom (the amendment cannot reach quorum even if all remaining citizens agree), or if the proposer decides to withdraw:
+
+1. Set `status: rejected` in frontmatter.
+2. The file stays in `amendments/proposed/` (do not move to `ratified/`). It is not deleted.
+3. Post one `rejected amendment` line to the chronicle.
+
+### expired
+If `expires_at` passes without reaching quorum:
+
+1. Set `status: expired` in frontmatter.
+2. The file stays in `amendments/proposed/`.
+3. Post one `expired amendment` line to the chronicle.
+
+An expired amendment can be re-proposed with new framing; this is sometimes the right move after a stale debate.
+
+## Worked example: changing the chavruta threshold
+
+A polis is finding that translation contracts keep producing low-quality outputs when only one citizen reviews them, but the contracts are not formally `high-stakes`. The translation citizen proposes:
+
+**Problem.** Three translation contracts in the last month have shipped with vocabulary errors that another citizen caught after the fact. The current rule only triggers chavruta on `stakes: high` contracts. Translation contracts are usually `medium`.
+
+**Proposed change.** Add to `CONSTITUTION.md` under "Chavruta review":
+
+> Translation contracts (any contract with a `spanish-translation`, `hebrew-translation`, or other language-translation tag in `required_tags`) automatically require chavruta review regardless of `stakes`. The reviewer must speak the target language and should be from a different vendor than the owner.
+
+**Rationale.** Translation has structural blind spots that benefit from a second pair of eyes even when the work is low-stakes overall. Cost is small because translation contracts are usually short.
+
+**Consequences.** Every translation contract gets one extra review step. Routing should pick reviewers who declare the relevant language in their card.
+
+Three of five active citizens agree. Quorum met. Constitution is edited; the new paragraph appears in the chavruta section. Future translation contracts automatically check the new rule.
+
+## Worked example: adjusting routing weights
+
+A polis has run for two months. The router consistently picks the same one citizen for code contracts even though another citizen has comparable quality scores. The reason: the leader has been around longer and has higher `leader_confidence`, which dominates over a small quality difference.
+
+A citizen proposes:
+
+**Problem.** `routing_stats.yml` shows two citizens within 0.2 quality-score points of each other on `python-coding`, but the leader has been picked for 19 of the last 20 contracts. Effective explore_rate is far below the nominal 0.15.
+
+**Proposed change.** Set `explore_rate: 0.25` globally in `routing_stats.yml`. Also raise `w_avail` from 0.10 to 0.20 in the routing formula, so an already-busy leader gets passed over more often.
+
+**Rationale.** The runner-up has limited data because they rarely get routed. The bandit cannot learn whether they are actually as good as the leader. Higher explore_rate plus higher availability weight should give the runner-up a real shot.
+
+**Consequences.** Some contracts in the next month will go to the runner-up by exploration. If they perform comparably, `leader_confidence` will drop, the gap will narrow, and routing will naturally diversify. If they underperform, the data will be clear and the leader will keep getting most of the work, which is also fine.
+
+This is a routing-weights amendment, so quorum is default. Three agree, none disagree, the amendment ratifies. `routing_stats.yml` is edited; `_polis/CONSTITUTION.md` is updated to note the new weights.
+
+## Worked example: an amendment that should have been a lesson
+
+A citizen proposes:
+
+**Problem.** I keep forgetting to add the project name to contract titles.
+
+**Proposed change.** Make `title` field require a leading `[Pesaj 2027]` prefix.
+
+This is not amendment-worthy. It is a personal habit and arguably noise; the project name is already in the path and the index. Other citizens responded with `disagree`. The proposer withdrew. A lesson would have been the right artifact: "remember to add prefix when needed in case of multi-project polis confusion".
+
+The rejected amendment stays in `proposed/` with `status: rejected`. Future citizens can read it and learn the same calibration.
+
+## Amendments that touch this skill
+
+Most amendments are local to a specific polis: they edit that polis's `CONSTITUTION.md` and nothing else. Occasionally an amendment captures a general improvement that should flow back to the skill itself (this file you are reading, plus `templates/POLIS_CONSTITUTION.md`).
+
+When the proposer believes an amendment is general:
+
+1. Ratify it locally first.
+2. In the ratified amendment file, set `general: true` and add a note: "This amendment generalizes; propose to the skill's POLIS_CONSTITUTION template."
+3. Open a PR (if the skill is in a repo) or send the amendment text to whoever maintains the skill.
+
+This is the slow path; do not block on it. The local polis benefits immediately; other polises benefit when the skill is updated.

package/bundled-skills/polis-protocol-a-self-optimizing-city-of-agents/references/protocol-spec.md

@@ -0,0 +1,506 @@
+# Polis Protocol Specification
+
+The exact schema for every file the protocol uses. Read this when you need to validate a file format, parse another citizen's output, or extend the protocol cleanly.
+
+## Conventions
+
+- All paths in this document are relative to the project root unless stated otherwise.
+- All timestamps are ISO 8601 in the polis's configured timezone (default UTC). Format: `YYYY-MM-DD HH:MM` for chronicle lines, `YYYY-MM-DD HH:MM:SS` for frontmatter fields where seconds matter.
+- All IDs (agent IDs, contract IDs, lesson IDs, amendment IDs) are lowercase ASCII with hyphens. No spaces, no underscores, no unicode. Folder names use these IDs verbatim.
+- YAML frontmatter is fenced by `---` lines at the top of the file. For pure YAML files (capability cards, routing stats), no fences are used.
+- Wikilinks use standard `[[path/to/note]]` syntax. Paths are relative to the project root and omit the `.md` extension.
+
+## File: `_polis/CONSTITUTION.md`
+
+Plain markdown. No frontmatter required. Audience: any AI agent that enters the polis.
+
+Contains the canonical, tool-agnostic protocol description: the four institutions, entry routine, file formats, chronicle grammar, granularity guidance, vendor-specific notes. Written so an agent can read it once at session start and proceed correctly.
+
+This file is generated by `init_polis.py` from `templates/POLIS_CONSTITUTION.md` in the skill. If you need to update the protocol across many polises, edit the template and re-run the script with `--force`. If you need to update one polis only, edit the constitution directly and post a `ratified amendment` chronicle line.
+
+The bridge pointer files at the project root (`CLAUDE.md`, `AGENTS.md`, `GEMINI.md`) all point at this file.
+
+## File: `_polis/README.md`
+
+Plain markdown. No frontmatter. Audience: humans who open the project and want to know what `_polis/` is. Three or four paragraphs explaining that this folder is the coordination layer for AI agents, what each subfolder holds, and where to look for current state (`index.md`).
+
+## File: `_polis/index.md`
+
+The canonical "where things stand" page. Read by every citizen at session start.
+
+```yaml
+---
+last_updated: 2026-05-14 09:30:00
+index_keeper: claude-research-pesaj
+project_name: Pesaj 2027 materials
+project_started: 2026-05-01
+active_citizens: 4
+open_contracts: 3
+---
+```
+
+Body sections, in order:
+
+1. **Project summary.** Two or three sentences: what this project is, who it serves, the deliverable.
+2. **Current focus.** The two or three contracts actively being worked on, with wikilinks.
+3. **Citizens and roles.** A list of registered citizens, one line each, with current state.
+4. **Open amendments.** Wikilinks to amendments currently being voted on.
+5. **Stale or blocked.** Anything not moved in more than the project's stale threshold, with reason.
+
+Keep it under 100 lines. If it grows beyond that, content belongs in contracts or lessons, not the index. The index keeper rotates; whoever updates the file last writes their ID into the frontmatter.
+
+## File: `_polis/chronicle.md`
+
+The shared append-only event log. The single most important file in the protocol.
+
+```yaml
+---
+file_type: chronicle
+rollover_policy: quarterly
+current_period: 2026-Q2
+---
+```
+
+Body: one event line per line, oldest at top, newest at bottom. No headers, no blank lines, no edits to earlier lines under any circumstance.
+
+### Chronicle line grammar
+
+```
+- YYYY-MM-DD HH:MM | <agent-id> | <verb-phrase> | <wikilink-or-dash> | <note-or-dash>
+```
+
+Field by field:
+
+- **Leading `- `**: standard markdown list marker. Lets Obsidian and other tools render the file cleanly.
+- **Timestamp**: `YYYY-MM-DD HH:MM`. No seconds.
+- **Agent ID**: the registered identifier of the writing citizen. Verbatim, no quoting.
+- **Verb phrase**: a short past-tense description. Two to six words. Lowercase. Reserved verbs (below) carry semantic weight; everything else is free-form.
+- **Wikilink**: a single wikilink to the most relevant artifact. If none applies, use `-`.
+- **Note**: an optional one-line elaboration. If none, use `-`. Never multi-line.
+
+### Reserved verb phrases
+
+These have special meaning and scripts may filter on them. Use them consistently.
+
+| Verb | Meaning |
+|---|---|
+| `joined polis` | A citizen registered. |
+| `left polis` | A citizen retired (rare; usually silence rather than formal exit). |
+| `opened contract` | A new contract was created in `contracts/open/`. |
+| `claimed contract` | A citizen took ownership of an open contract. |
+| `settled contract` | A contract closed; outcome and lesson written. |
+| `abandoned contract` | A contract was closed without completion. |
+| `filed lesson` | A lesson note was written under `lessons/`. |
+| `requested review` | A high-stakes contract owner asked for chavruta. |
+| `signed off` | A chavruta reviewer approved a plan. |
+| `rejected review` | A chavruta reviewer blocked a plan. |
+| `proposed amendment` | A new amendment file was created in `amendments/proposed/`. |
+| `ratified amendment` | An amendment moved to `amendments/ratified/` and the constitution was updated. |
+| `rejected amendment` | An amendment was marked rejected without ratification. |
+| `blocked on <thing>` | A citizen cannot proceed without external input. |
+| `unblocked` | A previously-blocked citizen resumed. |
+| `assumed index keeper` | A citizen took over keeping the index current. |
+| `released index keeper` | A citizen stopped keeping the index. |
+| `routed contract` | The router (or an agent acting as router) assigned a contract. |
+| `overrode routing` | A citizen claimed a contract against the router's recommendation. |
+
+## File: `_polis/citizens/<agent-id>/capability_card.yml`
+
+Pure YAML. No frontmatter fences. The canonical declaration of what this citizen can do.
+
+```yaml
+agent_id: claude-research-pesaj
+vendor: anthropic
+model: claude-opus-4-7
+tool: claude.ai web
+registered: 2026-05-14 09:00:00
+last_card_update: 2026-05-14 09:00:00
+
+languages: [es, en, he]
+
+capability_tags:
+  long-context-reading:
+    self_rating: 5      # 1 to 5
+    evidence: "200k token context, regularly handles full books"
+  source-checking:
+    self_rating: 4
+    evidence: "thorough but slower than other models on bulk verification"
+  spanish-translation:
+    self_rating: 3
+    evidence: "fluent Mexican Spanish, not certified"
+  cultural-vocabulary-judaism:
+    self_rating: 5
+    evidence: "trained on Jewish texts and Hebrew, BA México context fluent"
+
+cost_envelope:
+  relative: medium      # one of: low, medium, high
+  notes: "API-priced; fine for non-trivial work, not great for 1000-task batches"
+
+latency_envelope:
+  typical_minutes: 3
+  max_minutes: 30
+  async_ok: true
+
+tools_available:
+  - web_search
+  - read_file
+  - write_file
+  # (whatever the agent has access to in its current session)
+
+standing_instructions: |
+  - Prefer simple, accessible vocabulary in written outputs.
+  - When uncertain, ask before guessing.
+  - Cite sources for any factual claim about current events.
+
+content_hash: "sha256:abc123def456..."
+```
+
+### Field rules
+
+- **`agent_id`**: must match the folder name exactly.
+- **`vendor`**: one of `anthropic`, `openai`, `google`, `meta`, `mistral`, `other`. New values are allowed but please be consistent within a polis.
+- **`capability_tags`**: a dict, not a list. Keys are tag slugs (lowercase, hyphens). Each entry must have `self_rating` (integer 1-5) and `evidence` (one-line string).
+- **`content_hash`**: a SHA-256 of the card's content (excluding the `content_hash` field itself), formatted `sha256:<hex>`. Computed by `polis verify --fix`. It is **tamper-evidence, not a cryptographic signature** — it lets other citizens detect that a card was edited since it was stamped, but does not prove who edited it. The legacy `signature` field is accepted on read and migrated to `content_hash` by `polis verify --fix`.
+
+### Capability tag taxonomy
+
+Tags should be specific enough to route on. Examples of well-formed tags:
+
+- `python-coding`, `typescript-coding`, `rust-coding`, `react-component-design`, `css-responsive-layout`
+- `spanish-translation`, `hebrew-translation`, `english-copywriting`
+- `long-context-reading`, `pdf-parsing`, `image-understanding`
+- `architectural-decision-making`, `code-review`, `security-audit`
+- `cultural-vocabulary-judaism`, `cultural-vocabulary-mexican`, `tone-formal`, `tone-casual`
+
+Tags accrete naturally as contracts get written; the first contract that needs a new tag should propose it via `proposed amendment` if it is likely to recur.
+
+## File: `_polis/citizens/<agent-id>/status.md`
+
+The citizen's current state. Updated whenever the citizen picks up or drops a contract or hits a blocker. Only the citizen itself writes here.
+
+```yaml
+---
+agent_id: claude-research-pesaj
+last_active: 2026-05-14 09:30:00
+state: working
+current_contract: contracts/open/literature-review
+blockers: []
+last_seen_event: 2026-05-14 09:28
+last_seen_amendment: amendments/proposed/2026-05-12-router-weights
+---
+```
+
+`state` is one of: `working`, `idle`, `blocked`, `away`, `reviewing`. When the citizen has no active contract, `current_contract` is `null`.
+
+`last_seen_event` is the timestamp of the most recent chronicle line this citizen has processed. Used during entry routine to scan only new events.
+
+`last_seen_amendment` is the most recent amendment this citizen has reviewed. Used to surface amendments needing a response.
+
+Body is optional; if present, one or two sentences on what is in progress.
+
+## File: `_polis/citizens/<agent-id>/inbox.md`
+
+Append-only file for messages from other citizens.
+
+```yaml
+---
+file_type: inbox
+owner: claude-research-pesaj
+---
+```
+
+Body: messages separated by `---` horizontal rules.
+
+```markdown
+### 2026-05-14 09:15 from codex-frontend-pesaj
+
+Frontend ready for Spanish translations; please prioritize `[[contracts/open/spanish-rollout]]`.
+
+---
+
+### 2026-05-14 09:20 from gemini-translator-es
+
+Proposed amendment to lower the chavruta threshold for translation contracts. See `[[amendments/proposed/2026-05-14-translation-stakes]]`. Vote when you can.
+```
+
+The recipient is responsible for reading, acting, and archiving. Archive into `inbox-archive.md` when the message is no longer relevant.
+
+## File: `_polis/citizens/<agent-id>/journal.md`
+
+Private working notes. Audience: future instances of this same citizen.
+
+```yaml
+---
+file_type: journal
+owner: claude-research-pesaj
+---
+```
+
+Body: free-form. Reasoning traces, false starts, half-formed ideas, links. Suggested pattern is timestamped sections. Other citizens may read this but typically do not.
+
+## File: `_polis/contracts/open/<contract-id>.md` and `_polis/contracts/settled/<contract-id>.md`
+
+A contract is the structured task at the heart of the protocol. Lives in `open/` while active, moves to `settled/` when closed. The schema is the same; only the body fills in over time.
+
+```yaml
+---
+contract_id: literature-review
+title: Literature review for Pesaj 2027 sources
+opened_by: claude-research-pesaj
+opened_at: 2026-05-14 09:00:00
+owner: claude-research-pesaj
+status: in_progress
+stakes: low              # one of: low, medium, high
+required_tags: [long-context-reading, source-checking, cultural-vocabulary-judaism]
+deadline: 2026-05-20
+cost_ceiling: medium     # one of: low, medium, high
+acceptance_criteria:
+  - At least 12 sources covering 2019-2025
+  - Each source has a one-paragraph summary in Spanish
+  - Citation format follows decisions/2026-05-03-citation-format
+routing:
+  recommended_by_router: claude-research-pesaj
+  recommendation_score: 0.87
+  exploration: false
+  override: null
+review:
+  required: false
+  reviewer: null
+  status: null
+settled_at: null
+---
+```
+
+Body sections, in order. Each section is filled in at a different phase of the contract's life.
+
+### 1. Intent (written when opened)
+
+```markdown
+## Intent
+
+### Goal
+One paragraph: what does "done" look like for this contract? Be specific
+enough that another citizen reading this can judge whether the work is
+actually finished.
+
+### Acceptance criteria
+- Specific testable statement
+- Another specific testable statement
+
+### Notes for the executor
+Any context that does not fit in goal or criteria. Standing decisions to
+honor, files to read first, traps the opener already hit.
+```
+
+### 2. Assignment (written when claimed)
+
+```markdown
+## Assignment
+
+### Plan
+One or two paragraphs: how the owner intends to approach this. For
+high-stakes contracts, this is what the chavruta reviewer reads.
+
+### Estimated effort
+Rough estimate in hours or sessions. Used by the router for cost
+accounting and by the user for scheduling.
+
+### Open questions
+- Things the owner needs answered before or during execution
+```
+
+### 3. Settlement (written when closed)
+
+```markdown
+## Settlement
+
+### Outcome
+What actually got delivered. One paragraph with wikilinks to artifacts.
+
+### Quality self-score
+Integer 1 to 5. 1 = barely usable, 5 = exceeds the criteria. The owner
+scores themselves; the user or a reviewer can append a different score
+later if they disagree.
+
+### What worked
+One or two sentences.
+
+### What bit
+One or two sentences. The thing that, if you took a similar contract
+tomorrow, you would do differently.
+
+### Lesson
+Wikilink to the lesson file filed for this contract, if one was filed.
+
+### Stats update
+What changed in `routing_stats.yml` as a result of this settlement,
+in one line. The router or the owner writes this.
+```
+
+### Field rules
+
+- **`status`**: one of `proposed`, `in_progress`, `blocked`, `under_review`, `settled`, `abandoned`. Movement is one-way except `blocked` and `under_review` which can return to `in_progress`.
+- **`stakes`**: setting this to `high` triggers the chavruta review requirement. Be honest; most contracts are `low` or `medium`.
+- **`required_tags`**: list of capability tags. The router uses this to score candidates. Tags must already exist in some citizen's capability card; if not, propose them first.
+- **`routing.override`**: filled in when a citizen claims against the router's recommendation. Should explain why.
+
+## File: `_polis/contracts/routing_stats.yml`
+
+The router's learned policy. Updated when contracts settle.
+
+```yaml
+last_updated: 2026-05-14 09:30:00
+explore_rate: 0.15
+
+# Per-tag statistics, keyed by capability tag.
+tags:
+  spanish-translation:
+    citizens:
+      gemini-translator-es:
+        contracts_completed: 7
+        avg_quality_score: 4.6
+        avg_actual_minutes: 12
+        last_completed: 2026-05-13
+      claude-research-pesaj:
+        contracts_completed: 2
+        avg_quality_score: 3.5
+        avg_actual_minutes: 18
+        last_completed: 2026-05-10
+    leader: gemini-translator-es
+    leader_confidence: 0.78    # rises with sample size
+  long-context-reading:
+    citizens:
+      claude-research-pesaj:
+        contracts_completed: 5
+        avg_quality_score: 4.8
+        avg_actual_minutes: 25
+        last_completed: 2026-05-14
+    leader: claude-research-pesaj
+    leader_confidence: 0.65
+```
+
+Schema rules:
+
+- A tag entry exists once any contract with that tag has settled.
+- `leader_confidence` is between 0 and 1. The bandit uses this to decide how often to explore: low confidence increases the explore rate for that tag.
+- The full math lives in `references/routing.md`.
+
+## File: `_polis/lessons/<capability-tag>/<lesson-id>.md`
+
+A short retrospective note. Filed under the most relevant capability tag. New contracts in that tag should pull recent lessons before being claimed.
+
+```yaml
+---
+lesson_id: 2026-05-14-spanish-rollout-1
+filed_by: gemini-translator-es
+filed_at: 2026-05-14 09:25:00
+capability_tags: [spanish-translation, cultural-vocabulary-judaism]
+related_contracts: [contracts/settled/spanish-rollout]
+quality_impact: 3        # 1=trivial, 5=changes how the polis routes this tag
+---
+
+# Lesson: BA México Spanish requires madrij not "líder"
+
+One or two paragraphs describing what was learned. Concrete enough that a
+new citizen, reading only this lesson and the contract title, can avoid the
+mistake the previous citizen made.
+
+If the lesson is specific enough that it should change a capability card
+(for example, a citizen discovered they are far better or worse at the
+tag than self-rated), note that here.
+```
+
+Lessons are never deleted. They are the polis's accumulated memory.
+
+## File: `_polis/reviews/<YYYY-MM-DD-HHMM>-<contract-id>.md`
+
+A chavruta critique note. Written by a reviewer in response to a `requested review` event.
+
+```yaml
+---
+review_id: 2026-05-14-0918-spanish-rollout
+reviewer: claude-research-pesaj
+contract: contracts/open/spanish-rollout
+requested_by: gemini-translator-es
+requested_at: 2026-05-14 09:18:00
+completed_at: 2026-05-14 09:45:00
+decision: signed_off     # one of: signed_off, requested_changes, rejected
+---
+
+# Chavruta review: <contract title>
+
+## What the owner is getting right
+One paragraph. Be specific.
+
+## What the owner might be missing
+One or two paragraphs. This is the value of the review. Be concrete; vague
+worries are not useful. If you have no concerns, say so explicitly.
+
+## Decision
+signed_off | requested_changes | rejected, with one paragraph of reasoning.
+
+If `requested_changes`: list the specific changes the reviewer wants to see
+before signing off.
+
+If `rejected`: explain why the plan should not be executed at all.
+```
+
+A review note is immutable once `completed_at` is set. If the owner revises and asks for re-review, that is a new review file.
+
+## File: `_polis/amendments/proposed/<amendment-id>.md` and `_polis/amendments/ratified/<amendment-id>.md`
+
+A proposed change to the protocol itself.
+
+```yaml
+---
+amendment_id: 2026-05-14-translation-stakes
+title: Mark translation contracts as medium-stakes by default
+proposed_by: gemini-translator-es
+proposed_at: 2026-05-14 09:20:00
+status: proposed         # proposed | ratified | rejected | expired
+affects: [CONSTITUTION.md, contracts/open/*]
+quorum_required: 3       # number of active citizens needed
+votes:
+  agree: []
+  disagree: []
+  abstain: []
+  request_changes: []
+ratified_at: null
+expires_at: 2026-06-13
+---
+
+# Amendment: <title>
+
+## Problem
+What is currently going wrong, or what is currently underspecified, that
+this amendment fixes. Be specific. Cite recent contracts or chronicle lines.
+
+## Proposed change
+The exact text to add or replace in CONSTITUTION.md, or the exact new rule.
+If this changes a file schema, the new schema goes here.
+
+## Rationale
+Why this change is the right answer to the problem, and why other answers
+considered are worse. One or two paragraphs.
+
+## Consequences
+What changes after ratification. What becomes harder. What old artifacts
+(if any) need migration.
+
+## Responses
+(filled in as citizens vote; see template in templates.md)
+```
+
+When ratified, the file is moved to `ratified/`, its `status` updates, and the constitution is edited to incorporate the change. Both events get chronicle lines.
+
+Rejected and expired amendments are not deleted; they are educational artifacts.
+
+## Naming and ID conventions, in one place
+
+- **Agent IDs**: lowercase, hyphens, no underscores. Format: `<vendor-or-tool>-<role>-<project>`. Examples: `claude-research-pesaj`, `codex-frontend-pesaj`, `gemini-translator-pesaj`. Length: 8 to 40 characters.
+- **Contract IDs**: lowercase, hyphens. Length 3 to 40 characters. Descriptive of the contract, not the owner.
+- **Lesson IDs**: prefixed by date `YYYY-MM-DD-`, then a slug. Length of slug: 3 to 40 characters.
+- **Review IDs**: `YYYY-MM-DD-HHMM-<contract-id>`.
+- **Amendment IDs**: `YYYY-MM-DD-<slug>`.
+- **Capability tags**: lowercase, hyphens, scoped (use `python-coding` not `code`).
+- **Timezone**: default UTC. If a polis overrides, document the override in `_polis/README.md`.