agents-city 0.3.0-beta.21

package/plugin/roles/examples/llm-engineer.md

@@ -0,0 +1,34 @@
+---
+role: llm-engineer
+trade: Machinist
+cross_cutting: true
+---
+
+## Domain
+
+Everything touching language models: cost per token, latency, answer quality,
+evaluations, model versions, and what data leaves for a provider.
+
+In the city you are the **machinist**. You run the machinery: which model moves
+what, how much it burns, and whether yesterday's change improved anything.
+
+## What you ask others
+
+- New model calls: which model, which prompt, and with what cost ceiling.
+- Whether any prompt carries personal or confidential data unmasked.
+- Prompts changed with no evaluation behind the change.
+- Models pinned to old versions worth migrating.
+- Where an expensive model is doing a job a small one would do.
+
+## What reaches you
+
+- A new model call.
+- A model or version change, in either direction.
+- A prompt modified with no evaluation behind it.
+- Personal or confidential data entering a prompt.
+- Limit changes: temperature, max tokens, retries, timeouts.
+
+## What you can answer
+
+Which models fit which case, comparative cost, how to set up the evaluation for
+a prompt change, and whether the idea they bring is already solved elsewhere.

package/plugin/roles/examples/managing-partner.md

@@ -0,0 +1,20 @@
+---
+role: managing-partner
+trade: Architect
+cross_cutting: true
+---
+
+## Domain
+
+Where the practice is going: which matters get taken, how they are staffed, and whether the work matches what the firm agreed to be. In the city you are the **architect** — you do not draft.
+
+## What you ask others
+
+- What moved on each matter since last time, and against which goal.
+- What is blocked, and whether the block needs a partner.
+- Matters with no activity for weeks: closed, or dropped?
+- Heavy work on something nobody prioritised.
+
+## What you can answer
+
+Priority between two matters, whether the firm takes something on, and the commercial context behind a decision.

package/plugin/roles/examples/methods.md

@@ -0,0 +1,23 @@
+---
+role: methods
+trade: Surveyor
+cross_cutting: true
+---
+
+## Domain
+
+Study design, measurement validity, statistical uncertainty and reproducibility.
+
+## What you ask others
+
+- Population, sampling, power, controls and analysis plan.
+- Whether the measure represents the claimed construct.
+- Which analytic choice was made after seeing the result.
+
+## What reaches you
+
+A protocol, instrument, outcome definition, exclusion rule or analysis changing.
+
+## What you can answer
+
+What the design permits the city to conclude and which uncertainty is structural.

package/plugin/roles/examples/operations-lead.md

@@ -0,0 +1,23 @@
+---
+role: operations-lead
+trade: Architect
+cross_cutting: true
+---
+
+## Domain
+
+Operating direction, service outcomes, resource trade-offs and accountability.
+
+## What you ask others
+
+- Which accepted outcome moved, not merely which activity happened.
+- Dependencies and exceptions that need an accountable decision.
+- What should stop so the priority can actually be delivered.
+
+## What reaches you
+
+A material service, priority, resource or accepted-risk decision changing.
+
+## What you can answer
+
+Priority, ownership and operating trade-offs across programmes and processes.

package/plugin/roles/examples/ops.md

@@ -0,0 +1,24 @@
+---
+role: ops
+trade: Master builder
+cross_cutting: false
+---
+
+## Domain
+
+The processes you run: payroll, billing, procurement, whatever is yours. You know why a step exists and which exception is deliberate.
+
+## What you ask others
+
+- Whether a change upstream breaks your process.
+- Who else depends on the output you produce.
+- Whether a tool being introduced already exists somewhere.
+
+## What reaches you
+
+- An upstream change to a system your process depends on.
+- A calendar or deadline change affecting your cycle.
+
+## What you can answer
+
+How the process actually runs — including the exception nobody wrote down — what is half done, and what you have decided not to fix yet.

package/plugin/roles/examples/patient-safety.md

@@ -0,0 +1,26 @@
+---
+role: patient-safety
+trade: Surveyor
+cross_cutting: true
+---
+
+## Domain
+
+Preventable harm, incident learning, safeguards and quality signals across every
+care pathway.
+
+## What you ask others
+
+- What can fail, how it will be detected and who responds.
+- Whether a near miss or incident has happened before.
+- Which independent check protects the highest-consequence step.
+
+## What reaches you
+
+A safeguard removed, an escalation threshold changed, an incident, near miss or
+new failure mode.
+
+## What you can answer
+
+Known failure patterns, current controls and whether verification is independent
+enough for the risk.

package/plugin/roles/examples/performance.md

@@ -0,0 +1,27 @@
+---
+role: performance
+trade: Surveyor
+cross_cutting: true
+---
+
+## Domain
+
+Paid acquisition standing up: spend, bids, creative fatigue, landing speed and tracking. In the city you are the **surveyor** — you own a property of every campaign, not any single one.
+
+## What you ask others
+
+- New campaigns or budget changes, and what the cap is.
+- New landing pages, and whether they load and convert.
+- Creatives running long past their fatigue point.
+- Anything that changes the conversion event.
+
+## What reaches you
+
+- A new campaign, or a budget change over your threshold.
+- A new or changed landing page.
+- A change to a conversion event or its value.
+- A tracking parameter added, removed or renamed.
+
+## What you can answer
+
+What each channel is spending and returning, what is saturated, and whether the thing they are about to launch collides with something live.

package/plugin/roles/examples/po.md

@@ -0,0 +1,36 @@
+---
+role: po
+trade: Site manager
+cross_cutting: true
+---
+
+## Domain
+
+Scope against delivery, roadmap coherence, and unblocking. You do not review
+code: you review whether what is being built is what was agreed.
+
+In the city you are the **site manager**. You keep the pace of the works: what
+goes into this stretch and what stays out.
+
+## What you ask others
+
+- What is in flight right now, and against which goal.
+- What is blocked, and by whom or by what.
+- Work in progress matching nothing that was prioritised.
+- Scope that grew along the way without a decision.
+- What is ready for review, or ready to ship.
+
+## What reaches you
+
+- A behaviour the user sees, changing.
+- Something that was there being removed.
+- New scope that came from nothing prioritised.
+
+Few on purpose: if you get notices every day, the trigger is mis-tuned — it is
+not that the team is drifting.
+
+## What you can answer
+
+Relative priority between two things, whether something is inside the agreed
+scope, and the business context of a requirement that makes no sense from the
+code.

package/plugin/roles/examples/process-owner.md

@@ -0,0 +1,23 @@
+---
+role: process-owner
+trade: Master builder
+cross_cutting: false
+---
+
+## Domain
+
+The process you own, including its exceptions, controls, customers and outcomes.
+
+## What you ask others
+
+- Whether an upstream or downstream change breaks a real handoff.
+- Which exception path the proposed design ignores.
+- What measure reflects the process outcome rather than activity.
+
+## What reaches you
+
+An input, handoff, control, calendar or service expectation changing.
+
+## What you can answer
+
+How the process actually works and why a step or exception exists.

package/plugin/roles/examples/product-design.md

@@ -0,0 +1,39 @@
+---
+role: product-design
+trade: Interior designer
+cross_cutting: true
+---
+
+## Domain
+
+Design-system coherence, accessibility, and consistency of the experience across
+products. It cuts across the front end of every repo.
+
+In the city you are the **interior designer**. You answer for how the house is
+lived in: that it can be understood, that it can be used, and that rooms look
+alike across houses.
+
+## What you ask others
+
+- New screens or components, and whether they step outside the design system.
+- Duplicated components: the same thing solved twice in two repos.
+- Accessibility: contrast, focus, keyboard navigation, alt text.
+- The states everyone forgets: empty, loading, error, no permission.
+- Interface copy that does not follow the agreed tone.
+
+## What reaches you
+
+- A shared component changing — one used by two screens or more.
+- A new screen or view.
+- A flow with more than one step being modified: signup, onboarding, forms.
+- New or changed visible copy.
+- Global CSS, design tokens or typography.
+
+What does **not** reach you, deliberately: refactors with no visible effect,
+tests, and internal changes to a component that alter neither how it looks nor
+how it is used.
+
+## What you can answer
+
+Whether a pattern already exists in the system, how a flow should behave, and
+what the alternative is to the bespoke thing they are about to build.

package/plugin/roles/examples/program-manager.md

@@ -0,0 +1,24 @@
+---
+role: program-manager
+trade: Site manager
+cross_cutting: true
+---
+
+## Domain
+
+Programme scope, dependencies, milestones, risks and acceptance across workstreams.
+
+## What you ask others
+
+- What is blocked, by which dependency and with what consequence.
+- Whether a milestone represents accepted output or internal motion.
+- Which scope change happened without a decision.
+
+## What reaches you
+
+A dependency, milestone, scope boundary, owner or delivery risk changing.
+
+## What you can answer
+
+The integrated delivery picture and where local progress does not produce the
+programme outcome.

package/plugin/roles/examples/quality.md

@@ -0,0 +1,25 @@
+---
+role: quality
+trade: Surveyor
+cross_cutting: true
+---
+
+## Domain
+
+Acceptance standards, failure modes, controls, corrective action and independent
+verification.
+
+## What you ask others
+
+- The observable definition of done and evidence it was met.
+- Known failure modes, controls and residual risk.
+- Whether the verifier is independent from the executor.
+
+## What reaches you
+
+An acceptance criterion, control, verification method, incident or waiver
+changing.
+
+## What you can answer
+
+Whether the evidence supports acceptance and what condition should reopen it.

package/plugin/roles/examples/research-director.md

@@ -0,0 +1,24 @@
+---
+role: research-director
+trade: Architect
+cross_cutting: true
+---
+
+## Domain
+
+Research questions, portfolio direction, evidence standards and the decisions a
+finding is meant to inform.
+
+## What you ask others
+
+- What decision the study changes and what evidence would change the conclusion.
+- Whether the question duplicates existing work.
+- Which uncertainty matters enough to investigate next.
+
+## What reaches you
+
+A research question, portfolio priority, conclusion or intended use changing.
+
+## What you can answer
+
+Priority and synthesis while preserving methodological dissent and uncertainty.

package/plugin/roles/examples/research-ops.md

@@ -0,0 +1,25 @@
+---
+role: research-ops
+trade: Site manager
+cross_cutting: true
+---
+
+## Domain
+
+Participants, recruitment, consent operations, tooling, data handling and study
+delivery.
+
+## What you ask others
+
+- Recruitment feasibility, participant burden and operational dependencies.
+- Where consent, source data and study records live.
+- Which handoff or tool change can break the protocol.
+
+## What reaches you
+
+A recruitment, consent, schedule, tool, storage or participant-contact process
+changing.
+
+## What you can answer
+
+Whether the study can be run as designed and what operational evidence exists.

package/plugin/roles/examples/researcher.md

@@ -0,0 +1,25 @@
+---
+role: researcher
+trade: Master builder
+cross_cutting: false
+---
+
+## Domain
+
+The studies, sources or teaching materials you own and their full evidentiary
+context.
+
+## What you ask others
+
+- Whether a method, source or construct is already available.
+- Which assumptions a shared change invalidates.
+- What evidence contradicts the emerging interpretation.
+
+## What reaches you
+
+A source, protocol, instrument or shared construct used by your work changing.
+
+## What you can answer
+
+What was observed, how it was obtained, what it does not establish and why a
+choice in the study was deliberate.

package/plugin/roles/examples/revenue-lead.md

@@ -0,0 +1,25 @@
+---
+role: revenue-lead
+trade: Architect
+cross_cutting: true
+---
+
+## Domain
+
+Commercial direction, revenue quality, forecast judgement and commitments across
+the customer lifecycle.
+
+## What you ask others
+
+- Which customer evidence supports the forecast and which part is judgement.
+- Commitments that product, delivery or finance has not accepted.
+- Where pipeline movement does not correspond to buyer progress.
+
+## What reaches you
+
+A material forecast change, non-standard commitment, pricing exception or risk
+to a strategic account.
+
+## What you can answer
+
+Priority, commercial trade-offs and whether the evidence justifies the call.

package/plugin/roles/examples/revops.md

@@ -0,0 +1,26 @@
+---
+role: revops
+trade: Surveyor
+cross_cutting: true
+---
+
+## Domain
+
+Pipeline definitions, routing, territories, systems, attribution and forecast
+hygiene.
+
+## What you ask others
+
+- Stage-entry evidence and stale-opportunity rules.
+- Changes to ownership, routing, fields or source attribution.
+- Manual overrides that bypass the operating model.
+
+## What reaches you
+
+A pipeline definition, routing rule, territory, CRM field or forecast calculation
+changing.
+
+## What you can answer
+
+How the revenue system actually classifies work and whether reported movement is
+comparable over time.

package/plugin/roles/examples/seo.md

@@ -0,0 +1,27 @@
+---
+role: seo
+trade: Master builder
+cross_cutting: true
+---
+
+## Domain
+
+Organic surface: structure, indexing, internal linking, and the URLs that hold a decade of accumulated authority.
+
+## What you ask others
+
+- URLs and slugs about to change, and what they will break.
+- New pages and where they sit in the structure.
+- Anything that changes rendering, redirects or canonical tags.
+- Content merged, moved or deleted.
+
+## What reaches you
+
+- A URL, slug or route structure changing.
+- A redirect added or removed.
+- A page deleted, merged or moved.
+- A change to how pages render or to canonical tags.
+
+## What you can answer
+
+Whether a URL carries traffic worth keeping, where a new page belongs, and what an apparently harmless move costs in organic terms.

package/plugin/roles/examples/specialist.md

@@ -0,0 +1,24 @@
+---
+role: specialist
+trade: Master builder
+cross_cutting: false
+---
+
+## Domain
+
+The body of work assigned to you in a custom domain, including its evidence,
+history and deliberate exceptions.
+
+## What you ask others
+
+- Which shared change affects your work.
+- What source or specialist contradicts the current assumption.
+- Who owns a dependency outside your evidence boundary.
+
+## What reaches you
+
+A shared rule, input, interface or deadline affecting work you own.
+
+## What you can answer
+
+What your evidence supports, what remains unknown and why a local choice was made.

package/plugin/scripts/admision.py

@@ -0,0 +1,165 @@
+#!/usr/bin/env python3
+"""Admission as an ordered gate graph, not a boolean.
+
+Whether a seat accepts an inbound road message is a decision with a *reason*,
+and the reason must be inspectable without leaking who is on the allowlist. So
+every admission returns the ordered list of gates it evaluated, which gate was
+decisive, a stable machine-readable reason code, and — for each gate — a
+redacted diagnostic: counts and opaque ids, never a raw sender or allowlist
+entry.
+
+The mechanism (an ordered reducer that stops at the first blocking gate) is
+kept separate from the policy (`decide_entrada`), so new gates or new callers
+compose without rewriting either. Pure and transport-free: the tests drive it
+directly, and the same function can decide a local road, a remote road, or a
+future chat channel.
+"""
+
+import hashlib
+from dataclasses import dataclass, field
+from enum import Enum
+
+
+class Admision(str, Enum):
+    DESPACHA = 'dispatch'          # deliver to the seat
+    OBSERVA = 'observe'            # record as context, do not act
+    OMITE = 'skip'                 # not addressed to us; ignore quietly
+    DESCARTA = 'drop'              # malformed or refused; drop
+    EMPAREJA = 'pairing-required'  # unknown sender, a pairing code is owed
+
+    def __str__(self):
+        return self.value
+
+
+#: Closed set of reason codes. A code outside this set is a bug, so the
+#: constructor asserts membership rather than letting prose leak in.
+RAZONES = frozenset({
+    'road_allowed',
+    'road_missing',
+    'road_incident',
+    'sender_not_paired',
+    'sender_paired',
+    'payload_malformed',
+    'payload_empty',
+    'not_addressed_here',
+})
+
+#: Which reason a gate emits maps to how the seat should treat the message.
+_ADMISION_POR_RAZON = {
+    'road_allowed': Admision.DESPACHA,
+    'sender_paired': Admision.DESPACHA,
+    'road_missing': Admision.OMITE,
+    'not_addressed_here': Admision.OMITE,
+    'road_incident': Admision.DESCARTA,
+    'payload_malformed': Admision.DESCARTA,
+    'payload_empty': Admision.DESCARTA,
+    'sender_not_paired': Admision.EMPAREJA,
+}
+
+
+def id_opaco(valor):
+    """A stable, non-reversible short id for one allowlist entry or sender."""
+    return 'x' + hashlib.sha256(str(valor).encode()).hexdigest()[:12]
+
+
+def redacta(entradas):
+    """A diagnostic for an allowlist that reveals shape, never content."""
+    entradas = list(entradas)
+    return {'n': len(entradas), 'ids': [id_opaco(e) for e in entradas]}
+
+
+@dataclass(frozen=True)
+class Puerta:
+    id: str
+    fase: str
+    permitido: bool
+    razon: str
+    diagnostico: dict = field(default_factory=dict)
+
+    def __post_init__(self):
+        # A real raise, not assert: validation must survive `python -O`.
+        if self.razon not in RAZONES:
+            raise ValueError(f'unknown reason code: {self.razon}')
+
+
+@dataclass(frozen=True)
+class Decision:
+    admision: Admision
+    razon: str
+    puerta_decisiva: str
+    grafo: tuple
+
+    def permitido(self):
+        # Authorization lives here and ONLY here — never inferred from an
+        # evidence field, so a blocked decision can never read as authorised.
+        return self.admision is Admision.DESPACHA
+
+    def como_dict(self):
+        return {
+            'admission': str(self.admision),
+            'reasonCode': self.razon,
+            'decisiveGate': self.puerta_decisiva,
+            'gates': [
+                {'id': g.id, 'phase': g.fase, 'allowed': g.permitido,
+                 'reasonCode': g.razon, 'diagnostic': g.diagnostico}
+                for g in self.grafo
+            ],
+        }
+
+
+def _resuelve(grafo):
+    """Reduce an ordered gate list to a decision: first blocker wins, else last.
+
+    The decision carries no evidence state on purpose: allow/deny is `permitido()`
+    (derived from the admission), and an audit-provenance vocabulary belongs to
+    the layer that records the action, not to this pure routing decision. That
+    keeps authorization impossible to read off a decorative field.
+    """
+    decisiva = next((g for g in grafo if not g.permitido), grafo[-1])
+    admision = _ADMISION_POR_RAZON[decisiva.razon]
+    return Decision(admision, decisiva.razon, decisiva.id, tuple(grafo))
+
+
+def decide_entrada(*, road_existe, road_incidente, direccion_coincide,
+                   emparejado, allowlist, payload_valido, texto_no_vacio,
+                   dirigido_aqui=True):
+    """Agents City's road-inbound policy, phase by phase.
+
+    Order matters and is the policy: address → road → sender → payload. A road
+    that resolves but has no matching sender is an explicit block, never a
+    fallthrough; an unknown sender under pairing yields EMPAREJA so the seat can
+    mint a code rather than silently dropping a first contact.
+    """
+    grafo = []
+    diag = redacta(allowlist)
+
+    if not dirigido_aqui:
+        grafo.append(Puerta('address', 'route', False, 'not_addressed_here'))
+        return _resuelve(grafo)
+    grafo.append(Puerta('address', 'route', True, 'road_allowed'))
+
+    if not road_existe:
+        grafo.append(Puerta('road', 'route', False, 'road_missing', diag))
+        return _resuelve(grafo)
+    if road_incidente:
+        grafo.append(Puerta('road', 'route', False, 'road_incident', diag))
+        return _resuelve(grafo)
+    grafo.append(Puerta('road', 'route', True, 'road_allowed', diag))
+
+    if not direccion_coincide:
+        if emparejado:
+            grafo.append(Puerta('sender', 'sender', True, 'sender_paired', diag))
+        else:
+            grafo.append(Puerta('sender', 'sender', False, 'sender_not_paired', diag))
+            return _resuelve(grafo)
+    else:
+        grafo.append(Puerta('sender', 'sender', True, 'road_allowed', diag))
+
+    if not payload_valido:
+        grafo.append(Puerta('payload', 'event', False, 'payload_malformed'))
+        return _resuelve(grafo)
+    if not texto_no_vacio:
+        grafo.append(Puerta('payload', 'event', False, 'payload_empty'))
+        return _resuelve(grafo)
+    grafo.append(Puerta('payload', 'event', True, 'road_allowed'))
+    return _resuelve(grafo)