ENH: ratify project constitution v1.0.0 + add AGENTS.md

Populate .specify/memory/constitution.md (previously template placeholders
only) with five principles centred on the project's actual ideals:
comprehensive contributor acknowledgement, named-contributor fields are
sacred, pluggable parsers + shared .tributors cache, automation across
equivalent surfaces (library/CLI/container/Action), and identity
resolution with human-in-the-loop.

Add AGENTS.md at the repository root as the canonical guidance file for
AI agents (Claude Code, Codex, Cursor, Aider, …) and humans wanting a
quick orientation — preserves the prior build/test/code-style content,
adds a spec-kit command cheat-sheet, and points to the constitution as
required reading. CLAUDE.md (locally excluded) is symlinked to AGENTS.md.

Principle II is intentionally scoped to the *named* contributor fields
(`name`, `email`, `affiliation`, `orcid`, `blog`/`profile`, `bio`) — the
exact set the codebase currently protects in its merge logic. List
ordering across runs is a SHOULD, not a MUST.

The Quality Gates "Style" item notes that `black`/`pyflakes` are
operator-installed today; promoting the gate to a MUST in CI is the only
listed deferred TODO.

Co-Authored-By: Claude Code 2.1.143 / Claude Opus 4.7 <noreply@anthropic.com>

Author: yarikoptic

.specify/memory/constitution.md

@@ -1,50 +1,171 @@
-# [PROJECT_NAME] Constitution
-<!-- Example: Spec Constitution, TaskFlow Constitution, etc. -->
+<!--
+Sync Impact Report
+==================
+Version change: TEMPLATE → 1.0.0 (initial ratification)
+
+Templates requiring updates:
+  ✅ .specify/templates/plan-template.md — "Constitution Check" gate
+     references this file generically; gate items are determined per-
+     feature by /speckit.plan from the principles below. No edit required.
+  ✅ .specify/templates/{spec,tasks,checklist}-template.md — no edits.
+Top-level AI-agent guidance:
+  ✅ AGENTS.md created at repository root as canonical guidance file.
+  ✅ CLAUDE.md (locally excluded) symlinked → AGENTS.md.
+Deferred TODOs: declare `black`/`pyflakes` as dev extras + wire into CI;
+  the Quality Gates "Style" item promotes from operator-installed to a
+  MUST gate at that point (next PATCH bump).
+-->
+
+# Tributors Constitution
+
+Tributors pays tribute to every contributor by automating bookkeeping
+across `all-contributors`, `Zenodo`, `CodeMeta`, `mailmap`, and
+ORCID-backed identity. This constitution sets the non-negotiable rules
+every change MUST follow.
 
 ## Core Principles
 
-### [PRINCIPLE_1_NAME]
-<!-- Example: I. Library-First -->
-[PRINCIPLE_1_DESCRIPTION]
-<!-- Example: Every feature starts as a standalone library; Libraries must be self-contained, independently testable, documented; Clear purpose required - no organizational-only libraries -->
+### I. Comprehensive Contributor Acknowledgement
+
+Every person who has made a verifiable contribution to a downstream project
+that exceeds the user-configured threshold MUST be representable in the
+output formats Tributors supports. The default behaviour is *inclusive*: an
+operator opts contributors *out* (via skip lists or a higher threshold), not
+*in*. Bots are excluded by default because they are not people, not because
+their work doesn't count.
+
+**Rationale**: The whole purpose of the project is to make sure no
+contributor falls through the cracks. A silent omission is a worse failure
+than a noisy one.
+
+### II. Named Contributor Fields Are Sacred (NON-NEGOTIABLE)
+
+Once truthy, the named contributor fields — `name`, `email`, `affiliation`,
+`orcid`, `blog`/`profile`, `bio` — in `.tributors`, `.zenodo.json`,
+`.all-contributorsrc`, `codemeta.json`, and any future contributor file
+MUST NOT be overwritten by an automated run. New information may be added;
+existing values may not be silently replaced.
+
+**Rationale**: operators hand-curate this exact set of fields; destroying
+that work breaks trust. New parsers and update paths route through the
+shared merge logic; unconditional assignment to a populated named field is
+a violation that MUST be justified in Complexity Tracking or rejected.
+
+**Known scope limit**: the codebase rebuilds container structures (e.g.,
+`.all-contributorsrc` `contributors`, `.zenodo.json` `creators`) on each
+run, so list *order* is not preserved. Order preservation is a SHOULD, not
+a MUST, until a parser explicitly opts in.
+
+### III. Pluggable Parsers & Shared Cache
+
+Each input source and each output format MUST be implemented as a parser
+deriving from `ParserBase` (`tributors/main/parsers/base.py`). Cross-parser
+state MUST flow through the single shared cache file `.tributors`, indexed
+by the canonical identity (the GitHub login when available; otherwise the
+most stable identifier the parser exposes). Parsers MUST NOT reach across
+into each other's file formats directly.
 
-### [PRINCIPLE_2_NAME]
-<!-- Example: II. CLI Interface -->
-[PRINCIPLE_2_DESCRIPTION]
-<!-- Example: Every library exposes functionality via CLI; Text in/out protocol: stdin/args → stdout, errors → stderr; Support JSON + human-readable formats -->
+**Rationale**: The shared cache is what makes "update Zenodo from data the
+all-contributors run discovered" cheap and consistent. Bypassing it
+re-introduces the manual-bookkeeping problem the project was built to solve.
 
-### [PRINCIPLE_3_NAME]
-<!-- Example: III. Test-First (NON-NEGOTIABLE) -->
-[PRINCIPLE_3_DESCRIPTION]
-<!-- Example: TDD mandatory: Tests written → User approved → Tests fail → Then implement; Red-Green-Refactor cycle strictly enforced -->
+**How to apply**: A new format (e.g., a new author file standard) is added
+by writing a parser, not by patching an existing one. A new identity source
+updates `.tributors` via `update-lookup`; it does not write directly into a
+contributor file.
 
-### [PRINCIPLE_4_NAME]
-<!-- Example: IV. Integration Testing -->
-[PRINCIPLE_4_DESCRIPTION]
-<!-- Example: Focus areas requiring integration tests: New library contract tests, Contract changes, Inter-service communication, Shared schemas -->
+### IV. Automation Across Equivalent Surfaces
 
-### [PRINCIPLE_5_NAME]
-<!-- Example: V. Observability, VI. Versioning & Breaking Changes, VII. Simplicity -->
-[PRINCIPLE_5_DESCRIPTION]
-<!-- Example: Text I/O ensures debuggability; Structured logging required; Or: MAJOR.MINOR.BUILD format; Or: Start simple, YAGNI principles -->
+Every contributor-management capability MUST be reachable from the Python
+library API, the `tributors` CLI, the published container image, and the
+GitHub Action (`action.yml`), with matching options (CLI dashes ↔ Action
+underscores) and equivalent results. A feature is not "done" until the CLI
+and (where applicable) the Action expose it, and its output is a
+deterministic, diff-friendly file reviewable in a pull request.
 
-## [SECTION_2_NAME]
-<!-- Example: Additional Constraints, Security Requirements, Performance Standards, etc. -->
+### V. Identity Resolution with Human-in-the-Loop
 
-[SECTION_2_CONTENT]
-<!-- Example: Technology stack requirements, compliance standards, deployment policies, etc. -->
+When automatic identity resolution is ambiguous (e.g., multiple ORCID
+records match a name), Tributors MUST NOT silently pick one. The default
+behaviour is to skip the ambiguous entry; under `--interactive` mode, the
+operator is prompted with each candidate's distinguishing fields and
+selects (or skips). External authoritative sources (ORCID, mailmap, the
+shared cache) take precedence over heuristic guesses.
 
-## [SECTION_3_NAME]
-<!-- Example: Development Workflow, Review Process, Quality Gates, etc. -->
+**Rationale**: A wrong attribution is worse than a missing one — it
+misrepresents a real person. Ambiguity is a signal that human judgement is
+required, not that the tool should pick the first match.
 
-[SECTION_3_CONTENT]
-<!-- Example: Code review requirements, testing gates, deployment approval process, etc. -->
+## Metadata & Standards Compliance
+
+Output files MUST conform to the upstream schemas they target:
+
+- `.all-contributorsrc` follows the all-contributors specification, including
+  the documented contribution-type emoji keys.
+- `.zenodo.json` follows Zenodo's metadata schema; ORCID IDs are stored in
+  their canonical format.
+- `codemeta.json` follows the CodeMeta specification.
+- `.mailmap` follows git's mailmap syntax.
+
+Tributors MUST NOT invent new fields inside these files, MUST NOT reorder
+or rewrite content beyond what is necessary to apply an update, and MUST
+preserve any keys it does not understand so that hand-edits and
+out-of-band tooling continue to work.
+
+## Development Workflow & Quality Gates
+
+The following gates apply to every change (human-authored or AI-assisted)
+and MUST be checked by `/speckit.plan` for any new feature:
+
+1. **Principle compliance**: every Functional Requirement in the spec is
+   mapped to one or more principles above; any deviation appears in
+   Complexity Tracking with explicit justification.
+2. **Parser discipline**: new behaviour for an existing format goes into
+   that format's parser; cross-format flow goes through `.tributors`.
+3. **Surface parity**: behaviour added to the library is reflected in the
+   CLI and (where applicable) the GitHub Action with matching options.
+4. **Tests**: unit tests for parser logic (`tests/test_parsers.py` and
+   peers) and CLI tests (`tests/test_client.sh`) MUST cover the new path;
+   the merge-without-overwriting invariant MUST be exercised whenever a
+   parser's write path is touched.
+5. **Style**: Python source is formatted with `black` and passes
+   `pyflakes`; both are operator-installed today and not yet wired into
+   CI (the gate promotes to MUST when they are). New files MUST carry the
+   MPL-2.0 license header in the form used across the codebase.
+6. **No silent network calls in tests**: parser tests MUST be runnable
+   offline; live API interaction goes behind an explicit fixture/flag.
 
 ## Governance
-<!-- Example: Constitution supersedes all other practices; Amendments require documentation, approval, migration plan -->
 
-[GOVERNANCE_RULES]
-<!-- Example: All PRs/reviews must verify compliance; Complexity must be justified; Use [GUIDANCE_FILE] for runtime development guidance -->
+This constitution supersedes ad-hoc conventions in the codebase and other
+guidance documents (including `AGENTS.md` / `CLAUDE.md`, README, and per-
+parser docs). Where any of those conflict with this file, this file wins
+and the conflicting document MUST be reconciled.
+
+**Amendment procedure**: amendments are proposed in a pull request that
+edits this file and, when applicable, the affected templates under
+`.specify/templates/`. The PR description MUST include the version bump
+(see below) and a Sync Impact Report at the top of this file describing
+what changed and which downstream artifacts (templates, AGENTS.md,
+parsers, docs) require follow-up. The PR MUST be reviewed by a project
+maintainer before merge.
+
+**Versioning policy**: the constitution itself uses semantic versioning.
+
+- MAJOR: a principle is removed or redefined in a backward-incompatible way
+  (e.g., relaxing the "manual edits are sacred" invariant).
+- MINOR: a new principle or normative section is added, or existing
+  guidance is materially expanded.
+- PATCH: clarifications, wording fixes, typo repairs, non-semantic
+  refinements.
+
+**Compliance review**: every pull request that adds or modifies behaviour
+MUST verify against the Quality Gates above. AI agents (Claude Code,
+Codex, Cursor, Aider, and any future assistant) MUST read this
+constitution and `AGENTS.md` before proposing changes, and MUST surface
+principle violations rather than silently work around them.
+`AGENTS.md` (and its `CLAUDE.md` symlink) is this constitution's delegate
+for day-to-day conventions — build/test commands, code style specifics,
+pointers back here. Principles are added here, not there.
 
-**Version**: [CONSTITUTION_VERSION] | **Ratified**: [RATIFICATION_DATE] | **Last Amended**: [LAST_AMENDED_DATE]
-<!-- Example: Version: 2.1.1 | Ratified: 2025-06-13 | Last Amended: 2025-07-16 -->
+**Version**: 1.0.0 | **Ratified**: 2026-05-18 | **Last Amended**: 2026-05-18

AGENTS.md

@@ -0,0 +1,92 @@
+# AGENTS.md
+
+Canonical guidance for AI coding agents (Claude Code, Codex, Cursor, Aider,
+and any future assistant) and for humans who want a quick orientation.
+`CLAUDE.md` in this directory is a symlink to this file.
+
+## Read these first — every session
+
+1. **`.specify/memory/constitution.md`** — the project's constitution. It
+   defines the non-negotiable principles (most importantly: named
+   contributor fields, once set, MUST NOT be overwritten — see principle
+   II). Any change you propose MUST be consistent with it; surface a
+   conflict rather than working around one.
+2. **This file** — for build/test commands and code-style conventions.
+3. The plan for the current feature, if one is active under `specs/`.
+
+## Spec-Kit Workflow
+
+This project uses [spec-kit](https://github.com/github/spec-kit) for
+feature work. The relevant slash commands and the artifacts they
+produce/consume:
+
+| Command                 | Reads                     | Writes                                          |
+| ----------------------- | ------------------------- | ----------------------------------------------- |
+| `/speckit.constitution` | repo context              | `.specify/memory/constitution.md`               |
+| `/speckit.specify`      | constitution              | `specs/<###-name>/spec.md`                      |
+| `/speckit.clarify`      | spec                      | spec (updated)                                  |
+| `/speckit.plan`         | spec, constitution        | `plan.md`, Phase 0/1 artifacts, agent context   |
+| `/speckit.tasks`        | plan + Phase 1 artifacts  | `tasks.md`                                      |
+| `/speckit.implement`    | tasks, plan, constitution | source / tests                                  |
+
+Each command is bounded — do not silently progress into the next one.
+
+## Build and Test Commands
+
+- Install: `pip install .[all]` (`pytest` is not pulled in by `[all]`; add
+  it explicitly for the test suite, e.g. `pip install -e .[all] pytest`)
+- Run tests: `pytest -sv tests/*.py`
+- Run CLI tests: `/bin/bash tests/test_client.sh`
+- Run a single test: `pytest -sv tests/test_parsers.py::test_parser_zenodo`
+- Format code: `black tributors`
+- Check formatting: `black --check tributors`
+- Check imports: `pyflakes tributors`
+
+Parser tests MUST be runnable offline; do not introduce live network
+calls without an explicit opt-in fixture/flag.
+
+## Code Style Guidelines
+
+### Python
+
+- Format with Black; follow PEP 8 for everything Black does not enforce.
+- Public classes and functions get a docstring (`"""triple quotes"""`).
+- Import order: standard library, then third-party, then local — separated
+  by blank lines. Use relative imports within the `tributors` package.
+- `snake_case` for variables and functions; `PascalCase` for classes.
+- Catch specific exceptions, not bare `except:`.
+- New `.py` files MUST start with the MPL-2.0 header used across the
+  codebase (see `tributors/main/parsers/base.py` for the canonical form).
+
+### Markdown
+
+- Markdown tables MUST be column-aligned in source: every cell padded to
+  the column's widest content, separator dashes matching, outer pipes
+  vertical. The raw `.md` is read as often as the rendered view.
+
+## Architecture in One Paragraph
+
+`tributors` is a Python library + CLI + container + GitHub Action. Each
+input source or output format is a *parser* deriving from `ParserBase`
+(`tributors/main/parsers/base.py`). Parsers exchange information through a
+single shared cache file, `.tributors`, indexed by GitHub login when
+available. `update-lookup` populates the cache from sources (GitHub API,
+mailmap, ORCID, etc.); `update` writes from the cache into per-format
+files (`.all-contributorsrc`, `.zenodo.json`, `codemeta.json`, …) without
+overwriting populated fields. New formats are added by writing new
+parsers, not by patching existing ones — see the constitution, principle
+III, for the rationale.
+
+## What Counts as "Done"
+
+See `.specify/memory/constitution.md` § "Development Workflow & Quality
+Gates" for the authoritative checklist. Short form: parser/cache
+discipline (III), surface parity (IV), tests covering the no-overwrite
+invariant (II), `black` + `pyflakes` clean, deterministic diff-friendly
+output.
+
+<!-- SPECKIT START -->
+For additional context about technologies to be used, project structure,
+shell commands, and other important information, read the current plan
+under `specs/<active-feature>/plan.md`.
+<!-- SPECKIT END -->