Agency/CHANGELOG.md

Changelog

Each entry records what changed, why, and what it means for the system going forward. This log is for humans and AI alike — assume the reader has not seen prior commits.

---

[0.1.25] — 2026-05-14 — ADR 008: platform weight governance

Added

• docs/decisions/008-platform-weight-governance.md — defines how platform weights are set and changed: founding vote (initiator defines eligible members, averaged proposals), annual community vote (all platforms simultaneously, median of submitted distributions summing to 100%), and structural change tier (adding/removing platforms, changing the mechanism)

Changed

• docs/decisions/002-weighted-scoring.md — starting weights now reference ADR 008 as the formal governance mechanism; direct config.yaml edits for weights are prohibited
• docs/decisions/007-web-interaction-layer.md — weight proposals section updated to describe ballot UI (sliders summing to 100%) rather than incorrect PR-based flow
• docs/ARCHITECTURE.md — community weight governance section updated from "future direction" to current design, with link to ADR 008

Why

Weight governance was an open question — weights were effectively maintainer-set with no formal community process. ADR 008 closes that gap by making weights a community decision from day one, consistent with the project's core premise that legitimacy comes from participation, not structure.

---

[0.1.24] — 2026-05-12 — Wire bd (beads) Claude Code hook; ignore CLAUDE.md

Added

• .claude/settings.json — project-level Claude Code hooks: bd prime runs at session start and pre-compact; any Claude Code contributor gets this automatically on clone (analogous to .vscode/settings.json)

Changed

• .gitignore — CLAUDE.md added; it is generated locally by bd setup claude and is Claude-specific; AGENTS.md is the committed tool-agnostic equivalent

Why

bd setup claude generates a CLAUDE.md containing beads workflow instructions for Claude Code agents. Committing it would introduce a Claude-specific file into a repo designed to be tool-agnostic. The SessionStart hook in .claude/settings.json is the functional part — it injects bd prime context at the start of every session without encoding any agent-specific instructions in the repo itself.

---

[0.1.23] — 2026-05-12 — Add bd (beads) for agent issue tracking

Added

• AGENTS.md — minimal beads pointer; agents run bd prime for full workflow context
• .beads/ — beads configuration, hooks, and embedded Dolt database (committed config; database itself is gitignored)

Changed

• .beads/hooks/pre-commit — beads merged its integration block into our existing pre-commit hook; all three existing checks are preserved; core.hooksPath now points to .beads/hooks/ instead of .githooks/
• README.md — Contributing setup updated: bd init replaces git config core.hooksPath .githooks; each contributor runs bd setup <their-agent> locally — no agent-specific files committed to the repo

Why

Beads provides a dependency-aware issue graph for AI agents working in this repo — replacing ad-hoc markdown task lists with a structured, persistent store. Using AGENTS.md (not CLAUDE.md) keeps the setup tool-agnostic: any agent that reads AGENTS.md gets the same workflow pointer. The hooks integration is additive — existing pre-commit checks are unchanged.

---

[0.1.22] — 2026-05-12 — ADR 007: web interaction layer over git backend

Added

• docs/decisions/007-web-interaction-layer.md — records the decision to keep git as the canonical backend while building a web layer on top; covers what the web layer handles (proposals, voting, scores, config), the thin centralization tradeoff, the progressive enhancement principle, and why a database-backed app was rejected

Changed

• README.md — "Web-based dashboard" roadmap item expanded to reflect the broader scope: score dashboard, proposal submission, and voting UI, with a link to ADR 007

Why

The system is git-native by design, but git is a poor interaction layer for non-technical communities. Keeping git as the storage and audit layer while abstracting it behind a web UI preserves tamper-evidence, fork-ability, and auditability — the web server holds no data of its own. Documenting this before the web layer is built ensures the decision is made explicitly rather than discovered later when a database-backed implementation would be harder to undo.

---

[0.1.21] — 2026-05-11 — Drop commit hashes from changelog entries

Changed

• CHANGELOG.md — commit hashes removed from all version headers; format is now ## [version] — date — description

Why

Including the hash required a follow-up commit after every entry to backfill the hash once the commit existed — because the hash depends on the file contents, which would need to include the hash (circular). The hash is also redundant: git log --oneline finds any commit in seconds. Version number + date + description is sufficient.

---

[0.1.20] — 2026-05-11 — Guard new top-level doc files; fix README after STYLE.md

Added

• .githooks/pre-commit — third check: if a new file is staged directly under docs/ (e.g. docs/STYLE.md), README.md must also be staged; prompts contributor to verify the project structure diagram is current

Changed

• README.md — project structure diagram now includes docs/STYLE.md; it was committed in 0.1.19 but the diagram was not updated at that time (the gap this commit closes)
• README.md — Documentation system section updated: docs/STYLE.md is now listed as a fourth standing reference document; the paragraph previously said "read those three things"
• README.md — AI agent note now includes an explicit "Project structure diagram" reminder: when adding any file directly under docs/, check the diagram proactively before staging
• .gitmessage — checklist item for the structure diagram now explicitly names the "new file directly under docs/" case alongside new directories

Why

docs/STYLE.md was committed in 0.1.19 without updating the README structure diagram or documentation overview — caught only after the fact. The hook check for new directories (added in 0.1.17) did not fire because docs/ already existed. This commit closes that gap: the hook now checks depth-1 files under docs/ as a distinct case, and the AI agent note makes the rule explicit so the hook is a backstop, not the first line of defence.

---

[0.1.19] — 2026-05-11 — Documentation style guide; community-agnostic principle

Added

• docs/STYLE.md — documentation conventions for all contributors (human and AI): community-agnostic writing, changelog entry format, ADR conventions, and the test for whether a document is written for any community vs. OSArch specifically

Changed

• docs/ARCHITECTURE.md — added "OSArch is the reference implementation, not the intended audience" as a named design principle, linking to docs/STYLE.md
• README.md — Contributing section now links to docs/STYLE.md before listing contribution paths

Why

Documentation kept drifting toward OSArch-specific framing — specific contributor names, hardcoded platform lists, examples that only make sense with OSArch context. Rather than catching this case-by-case, the convention is now written down in one place and surfaced at every contributor entry point. The test is simple: does this document make sense to someone from a community that has never heard of OSArch?

---

[0.1.18] — 2026-05-11 — ADR 005 + 006: git-native voting and identity attestation

Added

• docs/decisions/005-git-native-voting-system.md — records the decision to use linkable ring signatures for anonymous, verifiable voting; covers the full vote lifecycle (proposal → snapshot → create → submit → tally → result), the returning officer submission norm, eligibility model, trust surface, and bootstrap problem
• docs/decisions/006-cross-platform-identity-attestation.md — records the decision to use human attestation for cross-platform identity linking; covers contributor profile files, attestation tiers, revocation, sybil resistance, and the relationship to the voting key

Why

The governance design emerged from an extended discussion about how communities should make binding decisions about what the system collects and how it weights contributions. The two ADRs capture that reasoning before implementation begins — so future contributors understand why the system looks the way it does, not just what it does. Both are marked Proposed; implementation is future work.

---

[0.1.17] — 2026-05-11 — Extend hook and checklist to guard README structure

Changed

• .githooks/pre-commit — added a second check: if a staged commit introduces a new directory (not present in HEAD), README.md must also be staged; prompts the collaborator to verify the project structure diagram is current
• .gitmessage — added checklist item: README.md project structure diagram current?

Why

The README structure diagram fell behind when docs/sites/platforms/ and .githooks/ were added — caught only after the fact. The new hook check catches this mechanically at commit time whenever a new directory is introduced.

---

[0.1.16] — 2026-05-11 — Update README project structure diagram

Changed

• README.md — project structure diagram now includes docs/sites/ (with platforms/, active/, proposed/, retired/, templates) and .githooks/; both were missing after recent additions

---

[0.1.15] — 2026-05-11 — Pre-commit hook: enforce CHANGELOG.md on substantive commits

Added

• .githooks/pre-commit — blocks commits that stage substantive files (docs/, src/, data/, config.yaml, main.py, requirements.txt, README.md, .gitmessage) without also staging CHANGELOG.md; bypass available via git commit --no-verify

Changed

• README.md — Contributing section now includes one-time setup step: git config core.hooksPath .githooks

Why

Two recent commits (README table consolidation, community forum addition) were pushed without a changelog entry — caught only after the fact. The .gitmessage checklist already included a CHANGELOG reminder but is easy to bypass when committing with -m. A pre-commit hook enforces the rule mechanically for all collaborators regardless of tool or workflow. Hooks live in .githooks/ (tracked) rather than .git/hooks/ (untracked) so all collaborators get them.

---

[0.1.14] — 2026-05-11 — Split site docs into platform docs + site docs

Added

• docs/sites/platforms/ — new directory; one file per platform (GitHub, MediaWiki, Vanilla Forums, Matrix, Open Collective) covering API mechanics, available signals, rate limits, and general concerns; reusable by any community without OSArch-specific context

Changed

• All docs/sites/active/*.md — stripped of platform mechanics; now cover only: inclusion rationale, OSArch-specific weight justification, and a Platform: link to the relevant platform doc
• docs/sites/active/github.md → renamed github-osarch.md for naming consistency with other site files
• docs/sites/active/README.md — GitHub links updated; platforms directory linked at the foot of the page

Why

Platform mechanics (API endpoints, auth, rate limits) have a different lifecycle than site inclusion decisions. Separating them makes the platform docs reusable by other communities adopting this system, and keeps site docs focused on the governance question: why is this specific instance included?

---

[0.1.13] — 2026-05-11 — Add OSArch Community Forum as active data source

Added

• docs/sites/active/community-osarch.md — OSArch Community Forum at community.osarch.org (Vanilla Forums); signals: posts, topics created, likes received; weight forum_posts: 0.2; documents decision not to use Vanilla's built-in gamification

Changed

• docs/sites/active/README.md — Community Forum row added to active sources table

Why

The forum is the primary discussion venue for the OSArch community and was missing from the active sources list. Likes received added as a quality signal alongside raw post count. Vanilla's opaque built-in gamification system explicitly excluded — the community should own the weighting, not inherit it from the platform.

---

[0.1.12] — 2026-05-11 — Consolidate active sources into a single table

Changed

• docs/sites/active/README.md — two separate tables (GitHub repos; other platforms) merged into one unified table with Source, URL, Signal, Weight, and Details columns; GitHub repos now show signal type and weight inline

Why

Two tables with different columns made it harder to compare sources at a glance. A single table with consistent columns makes the full picture immediately readable.

---

[0.1.11] — 2026-05-11 — AI agent guard: no exploratory artifacts in commits

Changed

• README.md — added "Exploratory work must not leak into commits" rule to the AI agent note: before staging, grep for any concept explored but rejected this session; nothing from a rejected approach should appear outside the ADR that records it
• .gitmessage — added pre-commit checklist item to verify exploratory artifacts have been cleared before staging

Why

During this session, a tier-weighting system was prototyped and rejected. The working directory accumulated artifacts (column headers, config keys, doc sections) that had to be manually hunted down before the commit was clean. This guard ensures future agents — and humans — run that check explicitly rather than catching it after the fact.

---

[0.1.10] — 2026-05-11 — ADR 004; CHANGE_TEMPLATE; GitHub repo scope in config

Added

• docs/decisions/004-no-per-repo-tier-weighting.md — all GitHub repos weighted equally; records the reasoning so the question is not re-litigated from scratch
• docs/sites/CHANGE_TEMPLATE.md — template for any modification to an active site: weight adjustments, scope changes, or full retirement

Changed

• config.yaml — added github.repos list to define collection scope explicitly
• docs/sites/active/README.md — GitHub section notes equal weighting with link to ADR 004
• docs/ARCHITECTURE.md — CHANGE_TEMPLATE linked from site governance section

---

[0.1.9] — 2026-05-11 — Add README to active sites directory

Added

• docs/sites/active/README.md — table of all active data sources with URL, signal type, weight, and link to detail file; links to proposal and retirement templates

---

[0.1.8] — 2026-05-11 — Rename TEMPLATE.md; link templates from docs

Changed

• docs/sites/TEMPLATE.md → renamed to docs/sites/PROPOSAL_TEMPLATE.md (names the process step, not just the outcome; pairs with CHANGE_TEMPLATE.md)
• docs/ARCHITECTURE.md — site governance section now links directly to both PROPOSAL_TEMPLATE.md and CHANGE_TEMPLATE.md
• README.md — Contributing section now links to both templates

---

[0.1.7] — 2026-05-11 — Cross-link docs using section anchors + AI agent guidance

Changed

• README.md — expanded "Note for AI agents" with guidance on cross-linking: when to add anchor links, how anchors are formatted, and that loose "see X" references should be treated as technical debt to be replaced with direct section links
• docs/ARCHITECTURE.md — bold section titles converted to ### headers throughout, enabling anchor links; plain file references replaced with markdown links
• docs/decisions/001-python-and-json.md — linked to ARCHITECTURE.md "Git as the distributed database" and "Distributed database" future direction
• docs/decisions/002-weighted-scoring.md — linked to "Correctability over precision" and "Community weight governance" sections
• docs/decisions/003-public-data-only.md — linked back to "Public data only" principle
• docs/sites/active/github.md — vague ADR 003 reference replaced with link
• docs/sites/active/opencollective-osarch.md — vague ARCHITECTURE.md references replaced with links to specific funding open question sections
• docs/sites/active/opencollective-opensourcebim.md — same as above

---

[0.1.6] — 2026-05-11 — Add site retirement template

Added

• docs/sites/CHANGE_TEMPLATE.md — standard format for retiring a data source; captures reason category, evidence, dissenting views, handling of historical data, and whether the site should ever be reconsidered

Why

A site retired due to gaming is very different from one retired because the community moved platforms. The retirement record is permanent and future contributors need the full context, not just the outcome.

---

[0.1.5] — 2026-05-11 — Seed active sites at genesis

Added

• docs/sites/active/github.md — GitHub, with full repo list: IfcOpenShell/IfcOpenShell, brunopostle/ifcurl, brunopostle/ifcmerge, brunopostle/homemaker-addon, falken10vdl/bonsaiPR
• docs/sites/active/opencollective-osarch.md — opencollective.com/osarch
• docs/sites/active/opencollective-opensourcebim.md — opencollective.com/opensourcebim
• docs/sites/active/matrix-osarch.md — #OSArch:matrix.org (via Element)
• docs/sites/active/wiki-osarch.md — wiki.osarch.org (MediaWiki public API)
• docs/sites/PROPOSAL_TEMPLATE.md — standard format for future site proposals
• docs/sites/proposed/ and docs/sites/retired/ — empty, ready for use

Why seeded directly as active

These sites represent the obvious starting set. Rather than run a formal proposal process before any collector exists, they are bootstrapped at genesis. All are marked "bootstrapped at genesis — community may remove or amend." The community can retire any of these through the normal process once it is established.

Notes

Individual contributor repos included alongside org repos — meaningful OSArch technical work happens across accounts, not just within a single org. Matrix flagged as needing public accessibility verification before a collector is built.

---

[0.1.4] — 2026-05-11 — Open question: site inclusion governance + sites scaffold

Added

• docs/sites/PROPOSAL_TEMPLATE.md — standard format for proposing a new data source
• docs/sites/proposed/github.md — first site proposal: GitHub, using unauthenticated public API, scoped to OSArch-affiliated repositories
• docs/sites/active/ and docs/sites/retired/ — empty directories ready for use as proposals are approved or retired

Changed

• docs/ARCHITECTURE.md — added open question on how the community should govern which platforms are collected from, with one possible approach outlined: criteria-first (public data, active use, genuine signal, stability, relevance), then a proposal + discussion + vote process; voting requires a minimum agency score threshold (active participant gate), equal vote above that threshold; permanent record of retired sites and reasons for removal

Why

The list of platforms the system collects from defines what "participation" means. That is a form of power — it should be community-governed, not owner-governed. Seeding the structure now makes the process real and ready to use, not merely theoretical. GitHub is the natural first proposal given it hosts the community's primary technical work.

Changed

• docs/ARCHITECTURE.md — added open question on how the community should govern which platforms are collected from, with one possible approach outlined: criteria-first (public data, active use, genuine signal, stability, relevance), then a proposal + discussion + vote process; voting requires a minimum agency score threshold (active participant gate), equal vote above that threshold; permanent record of retired sites and reasons for removal

Why

The list of platforms the system collects from defines what "participation" means. That is a form of power — it should be community-governed, not owner-governed. Documenting this as an open question before any real collector is built ensures the community decides the process before it becomes consequential.

---

[0.1.3] — 2026-05-11 — ADR: public data only

Added

• docs/decisions/003-public-data-only.md — collectors may only use publicly accessible data; no API keys, authentication, or platform permission required

Changed

• docs/ARCHITECTURE.md — added "Public data only" as a core design principle

Why

As collector design began, a choice emerged between authenticated APIs and public data. Restricting to public data only keeps the system independent of platform gatekeepers, immediately forkable without setup, auditable by anyone, and aligned with open source values. A less complete signal that anyone can verify is more valuable than a more complete signal that depends on platform permission. See ADR 003 for the full argument.

---

[0.1.2] — 2026-05-10 — README, open questions, framing refinements

Added

• README.md — introduces the project to first-time visitors: what it is, the core idea, quickstart, how scores work, how to fork it for another community, and the doc system
• Note in README directing AI agents to keep the file at a high overview level
• Funding collectors (Open Collective, Funders) added to roadmap
• Hint in README that weight changes may eventually have a community governance process

Changed

• docs/ARCHITECTURE.md — two new open questions added to Future Directions:
  1. Should funding signals be merged across platforms or kept separate, given that transparency of the funding act may matter as much as the funding itself?
  2. Should funding have representation beyond a score weight, or is the existing low-weighted score sufficient? Left genuinely unresolved for community debate.
• docs/ARCHITECTURE.md — added weight governance as a future direction: lightweight proposal process, open to active participants, equal say regardless of agency rank

Framing decisions

The README was revised several times to sharpen the language:

• Agency does confer authority over time — this was initially disclaimed, then corrected; the language was tightened to match reality
• "People hesitate to act because participation is real but untracked — and what isn't tracked can always be contested" replaces an earlier framing that implied people already had the right but lacked confidence; the stronger point is that the system makes the right explicit
• Example output clearly labeled as sample data, not real community figures

---

[0.1.1] — 2026-05-10 — Multi-community framing + future database directions

Changed

• docs/ARCHITECTURE.md — clarified that OSArch is the reference implementation, not the only intended user; any community can fork, adjust weights, and run this for their context
• docs/ARCHITECTURE.md — added "Future directions" section covering the path toward a distributed, tamper-evident data layer

Why (multi-community framing)

The system was always meant to be generalizable, but the early docs wrote as if OSArch was the only audience. That framing was corrected early — before any real integrations exist — so the architecture doesn't accidentally bake in OSArch-specific assumptions. The fork-to-adopt model (replace data, adjust weights) is now explicit.

Why (future database)

The current git-tracked JSON approach is a deliberate starting point, not the end goal. Blockchain was raised as a candidate for the eventual data layer. Rather than build it now (too complex, gas costs, wallet friction), the reasoning and alternatives are documented so the decision can be revisited with full context later. Alternatives noted: IPFS, Hypercore/Dat, signed append-only logs, private consortium chains.

---

[0.1.0] — 2026-05-10 — Genesis

Added

• Initial project scaffold: main.py, src/scoring/, src/outputs/, data/, config.yaml
• Weighted scoring system with configurable weights in config.yaml
• Sample participation data in data/sample.json with five OSArch community members
• CLI entry point: python main.py produces a ranked agency signal table
• docs/ARCHITECTURE.md — living architecture overview
• docs/decisions/001-python-and-json.md — why Python and git-tracked JSON
• docs/decisions/002-weighted-scoring.md — why simple weighted scoring

Why this structure

The system starts minimal and observable. No real API integrations yet — only mock data. The goal of this commit is to establish the scoring model and make it immediately runnable and arguable. Every subsequent commit builds on this foundation.

What's next

• First real data collector (OSArch forum API is the likely candidate)
• Community review of weights in config.yaml
• Normalization of scores (deferred until the signal is socially validated)