From 4c639d2223622b94e52f2664ea0ade175e16d35a Mon Sep 17 00:00:00 2001 From: Jammy2211 Date: Sun, 11 Oct 2026 18:41:42 +0100 Subject: [PATCH] Present communication resources with project context and evidence --- AGENTS.md | 10 +- CHECKIN.md | 6 + README.md | 8 +- broca/board.py | 14 +- broca/resources.py | 51 +++ dashboard.html | 82 +++- docs/communication.md | 43 ++ resources.json | 845 ++++++++++++++++++++++++++++++++++++++++ tests/test_resources.py | 37 ++ 9 files changed, 1086 insertions(+), 10 deletions(-) create mode 100644 broca/resources.py create mode 100644 docs/communication.md create mode 100644 resources.json create mode 100644 tests/test_resources.py diff --git a/AGENTS.md b/AGENTS.md index 398a0c1..3f59543 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,7 +1,9 @@ # PyAutoBroca -Broca owns assistant evaluation records, collection receipts and the operational -board. Brain interprets evidence and routes changes; Mind owns development state; +Broca covers communication and documentation: documentation, tutorials, user-facing +workspaces and assistants are first-class resources. Projects own their source. +Broca owns communication inventory views, assistant evaluation records, collection +receipts and the operational board. Brain interprets evidence and routes changes; Mind owns development state; Cortex owns science records; Heart owns readiness. Public assistants remain independently usable and do not depend on Broca. @@ -63,3 +65,7 @@ body and hands them to the human (sessions cannot create Discussions). Only the development flow — Mind prompt → `/start_dev` → `/create_issue` → one issue per task → PR — opens issues here. Why: `PyAutoMind/policy/community_surface.md`. + +Expanded resource ownership is documented in docs/communication.md. The public +resources.json is generated from Scientist relationships and Mind identities; do +not hand-maintain another resource registry or infer quality from a build result. diff --git a/CHECKIN.md b/CHECKIN.md index bfa1ab4..32a60a4 100644 --- a/CHECKIN.md +++ b/CHECKIN.md @@ -20,3 +20,9 @@ Brain owns interpretation. Route accepted implementation work through Mind and start-dev. Cortex retains science records; Heart retains readiness. Keep raw transcripts, credentials and private project data out of public outputs. Finish with the current evidence and the next action. Do not arm background monitoring. + +Also inspect the communication resource inventory: documentation, HowTo tutorials, +user-facing workspaces and assistants. Start with purpose/audience and source +ownership. Keep missing evidence unknown, separate technical validation from +explanatory quality, and route bounded improvements through Mind. Do not run +paid evaluations, publish or send external messages as part of this check-in. diff --git a/README.md b/README.md index 4432c79..276643a 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,10 @@ # PyAutoBroca -Assistant evaluation history, upkeep evidence and a shared-format dashboard. -Broca answers which assistant needs attention, what evidence supports that, and -which evaluation would be useful next. Brain interprets; Mind tracks fixes. +Communication and documentation resources, assistant evaluation history and upkeep evidence. +The dashboard gives documentation, HowTo tutorials, workspaces and assistants +their own project-linked dropdowns. Projects retain their source material; +Brain interprets evidence and Mind tracks fixes. See the +[communication contract](docs/communication.md) for ownership and catalogue refresh. ## Local check-in diff --git a/broca/board.py b/broca/board.py index 5f0ecd3..281d739 100644 --- a/broca/board.py +++ b/broca/board.py @@ -44,6 +44,7 @@ def render(root, brain): rows = {r["assistant"]: r for r in snapshot["assistants"]} esc = lambda value: html.escape(str(value), quote=True) panels, attention, history, maintenance = [], [], [], [] + assistant_evidence = {} for name in cfg["assistants"]: row = rows.get(name, {}) runs = sorted((r for r in records if r["assistant"] == name and r["kind"] == "benchmark"), @@ -61,6 +62,10 @@ def render(root, brain): if re.fullmatch(r"[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+", repo) else esc(name)) when = latest["observed_at"] if latest else "No run recorded" revision = (row.get("revision") or "Unknown")[:12] + assistant_evidence[name] = {"state": state, "collection": collected, + "github": repo, "revision": revision, + "collected_at": snapshot.get("refreshed_at") or "Unknown", + "observed_at": when} definitions = len(row.get("benchmarks", [])) if collected != "unavailable" else "Unknown" panels.append(f'

{link}

{esc(state)}

' f'
Latest evidence day
{esc(when)}
Runs recorded
{len(runs)}
' @@ -100,7 +105,10 @@ def render(root, brain): f'{esc(record["reason"] or "—")}
{esc(delta)}' f'{esc(record["run_id"])}
{esc(record["source"]["path"])}')) prompt = (Path(root) / "CHECKIN.md").read_text() - navigation = [{"href": "#assistants", "label": "Assistants", "count": len(cfg["assistants"])}, + from .resources import render as render_resources + resource_html = render_resources(root, assistant_evidence) + navigation = [{"href": "#communication", "label": "Communication resources"}, + {"href": "#assistants", "label": "Assistants", "count": len(cfg["assistants"])}, {"href": "#attention", "label": "Next actions"}, {"href": "#history", "label": "Evaluations", "count": len(history)}, {"href": "#maintenance", "label": "Maintenance"}] @@ -111,13 +119,13 @@ def render(root, brain): '' + ''.join(row for _, row in sorted(history, key=lambda item: item[0], reverse=True)) + '
Assistant / benchmarkDate / modelOutcome / scoreEvidence / comparisonRecord
') if history else '

No benchmark runs recorded.

' page = ('' - 'PyAutoBroca · Assistants
''' + theme.hero("broca", "Assistants", navigation=navigation) + panel + +
''' + theme.hero("broca", "Communication", navigation=navigation) + panel + resource_html + '

Assistants

' + ''.join(panels) + '
' + '

Next actions

    ' + ''.join(attention) + '
' + '

Evaluation history

' + table + '
' + diff --git a/broca/resources.py b/broca/resources.py new file mode 100644 index 0000000..a1d184c --- /dev/null +++ b/broca/resources.py @@ -0,0 +1,51 @@ +"""Communication inventory projected from Scientist; never a quality verdict.""" +import html +import json +from pathlib import Path +from urllib.parse import urlsplit + +TYPES = {'documentation': 'Documentation', 'tutorials': 'Tutorials', + 'workspaces': 'Workspace', 'assistants': 'Assistant'} +PURPOSE = {'documentation': 'Reference and explanations for using the software.', + 'tutorials': 'Guided learning: start with the tutorial introduction.', + 'workspaces': 'Runnable user examples: start with its README and setup guidance.', + 'assistants': 'A project-owned assistant: read its scope and setup instructions.'} + + +def link(url, label): + parsed = urlsplit(str(url)) + if parsed.scheme != 'https' or not parsed.hostname or parsed.username or parsed.password: + return html.escape(str(label)) + return f'{html.escape(str(label))}' + + +def render(root, assistant_evidence): + path = Path(root) / 'resources.json' + if not path.is_file(): + return '

Communication resources

Public resource inventory unavailable.

' + catalogue = json.loads(path.read_text()) + if catalogue.get('schema_version') != 1 or not isinstance(catalogue.get('resources'), list): + raise ValueError('invalid public resource catalogue') + esc = lambda value: html.escape(str(value), quote=True) + cards = [] + for resource in catalogue['resources']: + kinds = [k for k in TYPES if k in resource.get('relations', [])] + if not kinds: + continue + evidence = assistant_evidence.get(resource.get('repo')) if 'assistants' in kinds else None + # Bind assistant evidence to the exact canonical remote, not a similar name. + if evidence and evidence.get('github') != resource.get('github'): + evidence = None + state = evidence['state'] if evidence else 'Inventory only — quality not evaluated' + projects = ', '.join(p['name'] for p in resource['projects']) + links = ' · '.join(link(l['url'], l['label']) for l in resource['links']) + details = ('

Collection: ' + esc(evidence['collection']) + ' · collected ' + esc(evidence['collected_at']) + + '

Current commit: ' + esc(evidence['revision']) + ' · latest evaluation day: ' + + esc(evidence['observed_at']) + '

') if evidence else '

Revision, collection time and upkeep evidence: unavailable for this resource.

' + cards.append(f'''
{esc(resource['name'])} · {esc(' / '.join(TYPES[k] for k in kinds))} · {esc(projects)} · {esc(state)} +

{esc(' '.join(PURPOSE[k] for k in kinds))}

{links}

+

Used by: {esc(projects)}. Shared resources retain one identity; no assistant is required.

{details} +

Technical validation belongs to Heart. A successful build or runnable example does not establish explanatory quality or scientific correctness.

+

Next: inspect this resource's introduction, intended audience and known gaps with Broca before proposing a bounded documentation or evaluation task.

''') + return ('

Communication resources

Documentation, tutorials, user workspaces and assistants. Project repositories own the source; Broca presents communication context and available upkeep evidence.

' + + ''.join(cards) + ('' if cards else '

No public communication resources configured.

') + '
') diff --git a/dashboard.html b/dashboard.html index f83ee99..68be726 100644 --- a/dashboard.html +++ b/dashboard.html @@ -1,4 +1,4 @@ -PyAutoBroca · Assistants