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)