ai-profile-cli 0.3.0__py3-none-any.whl

ai_profile_cli-0.3.0.dist-info/METADATA

@@ -0,0 +1,215 @@
+Metadata-Version: 2.4
+Name: ai-profile-cli
+Version: 0.3.0
+Summary: Local-first, profile-level AI collaboration analytics for GitHub: aggregate explicit AI provenance across repositories into privacy-safe SVG/JSON README assets.
+Project-URL: Homepage, https://github.com/WenyuChiou/ai-profile
+Project-URL: Repository, https://github.com/WenyuChiou/ai-profile
+Project-URL: Issues, https://github.com/WenyuChiou/ai-profile/issues
+Project-URL: Changelog, https://github.com/WenyuChiou/ai-profile/blob/main/CHANGELOG.md
+License-Expression: MIT
+License-File: LICENSE
+Keywords: ai,attribution,git,github-profile,provenance
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.11
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Requires-Dist: ruff>=0.4; extra == 'dev'
+Description-Content-Type: text/markdown
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/banner-dark.svg">
+  <img alt="ai-profile - prove your AI collaboration, privately" src="docs/assets/banner-light.svg" width="100%">
+</picture>
+
+# ai-profile
+
+[![tests](https://github.com/WenyuChiou/ai-profile/actions/workflows/ci.yml/badge.svg)](https://github.com/WenyuChiou/ai-profile/actions/workflows/ci.yml)
+[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![python 3.11–3.14](https://img.shields.io/badge/python-3.11%E2%80%933.14-blue.svg)](pyproject.toml)
+
+English · [繁體中文](README.zh-TW.md)
+
+Local-first, profile-level **AI collaboration analytics** for your GitHub
+README. `aiprofile` scans your local Git repositories for *explicit* AI
+provenance — `AI-*` commit trailers and known AI co-author trailers (Claude
+Code, Codex, Cursor, Copilot, Aider, …) — normalizes it into a common event
+schema (ACE), stores it in a local SQLite database, and renders privacy-safe
+SVG cards + a JSON summary you can embed in a GitHub Profile README.
+
+## What it looks like
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/summary-sample-dark.svg">
+  <img alt="Sample AI collaboration summary card rendered from synthetic data" src="docs/assets/summary-sample-light.svg">
+</picture>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/heatmap-sample-dark.svg">
+  <img alt="Sample collaboration heatmap: intensity is total commits including your own, hue is the day's AI share" src="docs/assets/heatmap-sample-light.svg">
+</picture>
+
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="docs/assets/badge-sample-dark.svg">
+  <img alt="AI-assisted share badge, verified from git provenance" src="docs/assets/badge-sample-light.svg">
+</picture>
+
+Samples rendered from a synthetic showcase fixture; no real repository
+data. The heatmap is the view no other tool draws: intensity is your
+whole commit rhythm (your own commits included), hue is how much of
+each day was AI collaboration.
+
+It is **not** an AI code detector: nothing is ever inferred from code style.
+Commits without explicit evidence are honestly reported as `unknown` —
+never silently counted as human, never guessed into a provider.
+
+As far as we know it is the only free, local-first, cross-repository,
+explicit-provenance profile aggregation tool (line-level attribution
+belongs to tools like git-ai; full analysis:
+[landscape & positioning](docs/landscape.md)).
+
+Status: **v0.3** — the v0.1 vertical slice (one repo → trailers → SQLite →
+aggregate → summary card) plus provider brand identity (15 marks, two
+icon sources), the publishable-only isometric daily calendar, and the
+collaboration-ratio heatmap + badge. Design docs live in
+[`docs/`](docs/):
+[architecture](docs/architecture.md) · [ACE schema](docs/schema.md) ·
+[MVP boundary](docs/mvp.md) · [landscape & non-duplication](docs/landscape.md)
+· [decision records](docs/decisions/).
+
+## Install
+
+Compatibility: Python 3.11–3.14 · git ≥ 2.17 · SHA-1 repositories
+(SHA-256 object format fails with a clear error in v0.1) · Windows,
+macOS, Linux. Zero runtime dependencies.
+
+```bash
+pip install git+https://github.com/WenyuChiou/ai-profile
+```
+
+The PyPI package will be **`ai-profile-cli`** (upload in progress;
+PyPI's name-similarity rule blocks `ai-profile` because an unrelated
+project already holds `aiprofile` — and `pip install aiprofile` gets
+you that other project, not this one). Once live:
+`pip install ai-profile-cli`.
+
+From a clone (development):
+
+```bash
+pip install -e ".[dev]"   # dev extras = pytest + ruff + hypothesis
+```
+
+## Quickstart
+
+```bash
+aiprofile init            # run from INSIDE one of your repos - seeds your
+                          #   identity from that repo's git config user.email
+aiprofile scan ~/my/repo  # register + scan (replace with a real path;
+                          #   private-safe default)
+aiprofile aggregate       # print the published stats = privacy preview
+aiprofile render          # write dist/: summary + heatmap + badge SVG
+                          #   pairs (light/dark) + profile.json
+```
+
+Run **one `render` at a time per output directory** — concurrent renders
+into the same directory are unsupported and can publish assets from
+different scans.
+
+Only commits authored by your configured identities count (seeded from
+`git config user.email` at init; add more emails in
+`~/.aiprofile/config.json`).
+
+Run `aiprofile init` **from inside one of your own repos**: identity
+seeding reads `git config user.email` in the directory where you run
+it, so running from an unrelated folder can seed your global email
+instead of the one you actually commit with (or none at all). Check
+the seeded identities in `~/.aiprofile/config.json` after init.
+
+Embed in your profile README:
+
+```html
+<picture>
+  <source media="(prefers-color-scheme: dark)" srcset="dist/summary-dark.svg">
+  <img alt="AI collaboration summary" src="dist/summary-light.svg">
+</picture>
+```
+
+## Declaring AI participation (trailers)
+
+**If you commit through Claude Code, Codex, Cursor, Copilot, Aider, or
+Amp, you likely have nothing to do**: tools that add their own
+co-author trailer (e.g. Claude Code's
+`Co-Authored-By: Claude <noreply@anthropic.com>`) are recognized
+automatically via a verified identity registry.
+
+For everything else — or for richer detail (model, role, review
+status) — declare explicitly with `AI-*` trailers; product names like
+`Kimi`, `Claude`, or `Gemini` resolve too:
+
+```text
+feat: add aggregation service
+
+AI-Provider: Anthropic
+AI-Model: Claude-Sonnet
+AI-Tool: Claude-Code
+AI-Role: implementation, documentation
+AI-Mode: AI-Assisted
+AI-Reviewed-By: Human
+```
+
+One commit can carry
+several **AI actor presences** ("Claude implements, Codex reviews" =
+1 unique commit, 2 presences — the two metrics are never conflated; a
+presence means "this provider/tool appeared in this commit", so Claude
+implementing AND reviewing one commit counts once, honestly). A commit
+that is explicitly yours alone: `AI-Mode: Human-Only`.
+
+## Privacy model (defaults are safe)
+
+- Everything stays on your machine; no network calls, no telemetry.
+- Every scanned repository defaults to `aggregate_only`: it contributes
+  counts, never its name. `scan --full` is the explicit opt-in that marks
+  a repository's counts as explicitly publishable (a policy decision you
+  make — NOT a claim about GitHub visibility); `excluded` removes a repository entirely.
+- Publication policy lives in `config.json` only — edit it and the next
+  `aggregate`/`render` respects it, no rescan needed.
+- Public outputs contain counts, provider names, evidence totals, and a
+  UTC date. Never: repository names/paths, org names, branches, commit
+  SHAs or messages, raw trailer strings, emails, or timestamps finer than
+  a date. Unrecognized provider spellings are bucketed as "Unrecognized"
+  in public assets (see the raw values locally with `aggregate -v`).
+- `aiprofile aggregate` prints exactly what would be published — it *is*
+  the privacy preview.
+- Honest limit: aggregate-only publication is **identity redaction, not
+  anonymity**. Repository names never appear, but repeatedly published
+  exact counts let an observer infer *when* your aggregate-only activity
+  changed and which provider appeared. Full threat model:
+  [`docs/PRIVACY.md`](docs/PRIVACY.md). Output labels are policy-based
+  ("explicitly publishable" / "aggregate-only"), never claims about
+  GitHub visibility.
+- Do not sync `~/.aiprofile` into published dotfiles (it holds a salt and
+  private repository paths). Deleting that directory deletes all local
+  data; generated `dist/` files are yours to remove separately. On
+  POSIX the directory and files are owner-only (0700/0600); Windows
+  has no equivalent permission bits, so there `os.chmod` is a
+  documented no-op — the data still never leaves your machine.
+
+## Metrics, honestly labeled
+
+- **AI-attributed commits** — unique commits with ≥1 explicit AI actor
+  presence. Per-provider counts may sum to more than this (multi-AI
+  commits) and are labeled as provider-attributed commits, never as
+  unique totals. Evidence chips state their population; percentages state
+  their denominator; active days are commit author dates.
+- **Evidence quality** is first-class: `verified > declared > imported >
+  inferred > unknown`. v0.1 produces `declared` (trailers) and `unknown`.
+
+## License
+
+MIT — see [LICENSE](LICENSE). Contributions welcome under
+[CONTRIBUTING.md](CONTRIBUTING.md).

ai_profile_cli-0.3.0.dist-info/RECORD

@@ -0,0 +1,32 @@
+aiprofile/__init__.py,sha256=PQdSKLq8i3j8kBTe1VaLW1cp6EGcfWz_m24jFCZh9Qg,263
+aiprofile/__main__.py,sha256=vfaB5IsNzfve4aiagsrV2m0JgLsUPhWmoASdomBUJIg,92
+aiprofile/aggregate.py,sha256=3ELSLHGJ7zrtlhFa6IKjLZSvM9QJaSsf1AiGgKnl3LM,15276
+aiprofile/cli.py,sha256=cODSlPQPCulZIwFoFfrMgB7bU1TSJF5i8wI334QOILs,10820
+aiprofile/config.py,sha256=5L7WSVLn1HlNI0_hZycLod4skbYevJTqhLO9PwgmUoQ,8930
+aiprofile/errors.py,sha256=fvh6rvg4LQcvc1yCyl_OQeHIEezflJa4X52tDYZZqUI,905
+aiprofile/export.py,sha256=fJlz4kIfUJyqp6CjJy0qohfyI-QgudLKBr8OQnskiwE,9175
+aiprofile/gitio.py,sha256=ZWA0ee5TDnC0LtOm21Nrrc8WlEcTnTJnEZKTOUZyJqs,13743
+aiprofile/privacy.py,sha256=U1Q6SVEB6TexoNojy2785nOKnhd8EySi_qaifEEz5Lk,9662
+aiprofile/registry.py,sha256=Wz2HL32C9OtsGZFIqJR0ZJxrMxuuNQgSNdOrTQb019I,8126
+aiprofile/scanner.py,sha256=nQVSCrJs8ecLIvaei3wYBFL_oplAIPD7wnfO5NoyL7Y,7930
+aiprofile/viz.py,sha256=8_WPOZRZdAQ9R-6xmwCBvmSe-hwGQU1yBN0xpO--I9M,23033
+aiprofile/adapters/__init__.py,sha256=wi-dha9F06tN8T5VWTiLlLQHEHKBd3ZL3f1TRirFLI8,72
+aiprofile/adapters/trailers.py,sha256=md9FwhU8OmkyhSoYo9yoD4jKL8rOIS52dVQ-GCx85Yw,14856
+aiprofile/render/__init__.py,sha256=N-u5nMqIglDmNbfXluwpu0MrxInD7bN4k30ihNPgnZ8,85
+aiprofile/render/badge_svg.py,sha256=-xcmzlxIxBMHimnpIDOBk1jWtZI0KmwC-iwugf_kSaM,3945
+aiprofile/render/brand.py,sha256=3--vrXbvbjHbLuS3VAvRMQzzq6ykNay63FZpLlZ556Y,31936
+aiprofile/render/heatmap_svg.py,sha256=ox2kYhfEKwLeBOKWFmj92JBFIA1EXPgutadrrIbJ_tk,13908
+aiprofile/render/summary_svg.py,sha256=txXbwFtSB6QZQy8Jvg4pNUjfW8EQfaYuJ2x6-qF3n1A,48360
+aiprofile/render/themes.py,sha256=_gKtBEdoS5z-SMFD2TsHqysuFzboBaSJVjm58K9_r6U,2222
+aiprofile/schema/__init__.py,sha256=rS15vj43L5HhKcdxQCBWt5cGBs92vtmgpssOPwwePhE,644
+aiprofile/schema/event.py,sha256=KGM_vMFEStzdVE39Nyuy-sY513BGnevErnBE5J2b6cg,21026
+aiprofile/schema/vocab.py,sha256=c6juMN4x_AOjH0Kl6JVyDREdQQFcg4d-HDUd7EZCeQ8,6394
+aiprofile/storage/__init__.py,sha256=SVLUBpdIYNvyIE5f1HlvnYEFMOBuBuK_0UEntlrvCLM,72
+aiprofile/storage/db.py,sha256=JFujTDhW4Q430jcAp7CAp9tn_eLtdcwfnyqfhfds6fE,5421
+aiprofile/storage/migrations.py,sha256=TPgRIvbwPGZYrB_qhrNfDwHD4HVoec0IxHNU2zP5BQM,2501
+aiprofile/storage/store.py,sha256=sj4CP43BEZEbpvB56tYfhzNjnCOgQ3akmIyD3l7Jaz0,6445
+ai_profile_cli-0.3.0.dist-info/METADATA,sha256=ZYmlw4q4j2RBIzD6I41CooKAswQl72AFn4D_Q1yW-1w,9702
+ai_profile_cli-0.3.0.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+ai_profile_cli-0.3.0.dist-info/entry_points.txt,sha256=LhYqGd80ct4ObueO1tsAQbxhYZUO2z7ef4u_bcKFbFw,49
+ai_profile_cli-0.3.0.dist-info/licenses/LICENSE,sha256=HgNCKf1GuKd0i84QnjvMB44YC7BeJ25RMDniuamQxjc,1068
+ai_profile_cli-0.3.0.dist-info/RECORD,,

ai_profile_cli-0.3.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.31.0
+Root-Is-Purelib: true
+Tag: py3-none-any

ai_profile_cli-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+aiprofile = aiprofile.cli:main

ai_profile_cli-0.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Wenyu Chiou
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

aiprofile/__init__.py

@@ -0,0 +1,7 @@
+"""ai-profile: local-first, profile-level AI collaboration analytics for Git repositories."""
+
+__version__ = "0.3.0"
+
+#: ACE (AI Collaboration Event) schema version written into every event.
+#: Governed by docs/schema.md and ADR-012.
+ACE_SCHEMA_VERSION = "0.2.0"

aiprofile/__main__.py

@@ -0,0 +1,7 @@
+"""python -m aiprofile entry point."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

aiprofile/adapters/__init__.py

@@ -0,0 +1 @@
+"""Source adapters: provider-specific records → ParticipationSpec."""

aiprofile/adapters/trailers.py

@@ -0,0 +1,381 @@
+"""Git trailer adapter: trailer lines → ParticipationSpec (ADR-005).
+
+INTERFACE PINNED BY THE ORCHESTRATOR — work package B implements
+parse_commit_trailers without changing any signature or dataclass here.
+Normative behavior: ADR-005 (grouping rule + carved exceptions),
+schema.md sections 5 and 10, ADR-013 (registry matching).
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Sequence
+from dataclasses import dataclass
+
+from ..registry import match_coauthor, normalize_provider, resolve_tool
+from ..schema.event import ProvenanceSource
+from ..schema.vocab import ActorType, ContributionMode, EvidenceLevel, Role, SourceType
+
+#: Recognized AI-* trailer keys (case-insensitive; ADR-005).
+AI_TRAILER_KEYS = frozenset(
+    {"ai-provider", "ai-model", "ai-tool", "ai-role", "ai-mode", "ai-reviewed-by", "ai-schema"}
+)
+COAUTHOR_KEY = "co-authored-by"
+
+
+@dataclass(frozen=True)
+class ParticipationSpec:
+    """One AI actor presence (or human declaration) parsed from explicit
+    trailer evidence. The scanner turns specs into validated ACE events;
+    the adapter never invents data."""
+
+    actor_type: ActorType
+    provider: str | None
+    provider_raw: str | None
+    model: str | None       # lowercase(trim(model_raw)) — no registry (schema.md 10)
+    model_raw: str | None
+    tool: str | None
+    tool_raw: str | None
+    roles: tuple[Role, ...]
+    contribution_mode: ContributionMode | None
+    human_reviewed: bool | None
+    source: ProvenanceSource
+
+
+@dataclass(frozen=True)
+class ParseWarning:
+    """Diagnostics-hygiene-safe warning (architecture.md section 10): `code`
+    and `trailer_key` are always safe to print; `local_detail` may quote
+    trailer values and is shown only under --verbose."""
+
+    code: str          # unknown-role | malformed-mode | malformed-reviewed-by |
+                       # incomplete-group | contradictory-group
+    trailer_key: str
+    local_detail: str | None = None
+
+
+def parse_commit_trailers(
+    trailer_lines: Sequence[str],
+) -> tuple[list[ParticipationSpec], list[ParseWarning]]:
+    """Parse one commit's trailer block (ordered lines from
+    %(trailers:only,unfold)) into actor-presence specs.
+
+    Contract (implemented by work package B):
+    - Trailer lines split on the first ':'; keys matched case-insensitively;
+      non-trailer-shaped lines ignored.
+    - AI-* grouping: iterate AI-* trailers in order; a repeated key inside
+      the current group closes it and starts a new one (ADR-005).
+    - A group yields an AI spec when AI-Provider is present (registry
+      normalization; unrecognized → provider None + provider_raw kept) or
+      AI-Tool resolves via registry.resolve_tool (which supplies the
+      provider). Groups with neither are dropped: warning `incomplete-group`.
+    - `AI-Mode: Human-Only` in a group with NO AI-Provider/AI-Tool key →
+      one HUMAN spec (all identity fields None, evidence declared). With
+      any AI-Provider or AI-Tool key present (recognized by the registry
+      or not) → drop the whole group: warning `contradictory-group`.
+    - AI-Role: comma-separated tokens → Role vocabulary; unknown tokens
+      dropped with warning `unknown-role`; empty result = no roles.
+    - AI-Mode: vocabulary values matched case-insensitively with '-'/'_'
+      equivalence ("AI-Assisted" → ai_assisted); unparseable → None +
+      warning `malformed-mode`. Missing mode on an AI group → None (the
+      group itself declares AI; schema.md section 5).
+    - AI-Reviewed-By: "human" → True, "none" → False, else None + warning
+      `malformed-reviewed-by`.
+    - AI-Schema: informational only, never affects parsing.
+    - Co-authored-by: value shaped "Name <email>"; registry.match_coauthor
+      (exact email + optional name-prefix condition) → one AI spec with
+      source git_trailer_coauthor, model/model_raw None, provider_raw set
+      to the display name. Non-matching co-authors are ignored silently
+      (they are presumed human co-authors, not evidence of anything).
+    - Sources: git_trailer / git_trailer_coauthor, evidence declared,
+      source_reference = the matched trailer key (never a value).
+    - Never raises on message content; returns ([], []) for no evidence.
+    - Same provider+tool in several groups is fine — the scanner merges by
+      identity; the parser does not deduplicate.
+    """
+    specs: list[ParticipationSpec] = []
+    warnings: list[ParseWarning] = []
+
+    # `pending` holds, in message order, either an in-progress AI-* group
+    # or an already-resolved co-author ParticipationSpec. Co-author lines
+    # never depend on later lines so they are resolved immediately; AI-*
+    # groups are finalized only after the loop so a group left open at
+    # end-of-input is handled identically to one closed early by a repeated
+    # key (ADR-005). A group tracks VALUES and KEY PRESENCE separately
+    # (gate M-03): an empty-valued `AI-Provider:` contributes no value but
+    # its presence still matters to the Human-Only contradiction rule.
+    pending: list[_Group | ParticipationSpec] = []
+    current_group: _Group | None = None
+
+    for line in trailer_lines:
+        key, value = _split_trailer_line(line)
+        if key is None:
+            continue
+
+        if key == COAUTHOR_KEY:
+            if value:
+                coauthor_spec = _parse_coauthor(value)
+                if coauthor_spec is not None:
+                    pending.append(coauthor_spec)
+            continue
+
+        if key not in AI_TRAILER_KEYS:
+            # Non-AI, non-co-author trailers are ignored without affecting
+            # grouping.
+            continue
+
+        if current_group is None:
+            current_group = _Group()
+            pending.append(current_group)
+        elif value and key in current_group.values:
+            # Only a NON-EMPTY repeat closes the group (ADR-005): an
+            # empty-valued repeat contributes presence without splitting.
+            current_group = _Group()
+            pending.append(current_group)
+        current_group.present.add(key)
+        if value:
+            current_group.values[key] = value
+
+    for item in pending:
+        if isinstance(item, _Group):
+            spec, group_warnings = _finalize_group(item)
+            warnings.extend(group_warnings)
+            if spec is not None:
+                specs.append(spec)
+        else:
+            specs.append(item)
+
+    return specs, warnings
+
+
+class _Group:
+    """One AI-* trailer group: parsed non-empty values plus the set of
+    recognized keys that APPEARED (even with empty values — gate M-03)."""
+
+    __slots__ = ("values", "present")
+
+    def __init__(self) -> None:
+        self.values: dict[str, str] = {}
+        self.present: set[str] = set()
+
+
+def _split_trailer_line(line: str) -> tuple[str | None, str]:
+    """Split one already-unfolded trailer line on the first ':'. A line with
+    no ':' yields (None, "") so the caller ignores it; the key is lowercased
+    and both sides are stripped (docstring contract)."""
+    key_part, sep, value_part = line.partition(":")
+    if not sep:
+        return None, ""
+    return key_part.strip().lower(), value_part.strip()
+
+
+def _finalize_group(group: _Group) -> tuple[ParticipationSpec | None, list[ParseWarning]]:
+    """Turn one collected AI-* trailer group into a spec, or drop it with a
+    group-level warning (ADR-005 grouping rule + the two carved Human-Only
+    exceptions; schema.md section 5)."""
+    values = group.values
+    provider_raw_value = values.get("ai-provider")
+    tool_raw_value = values.get("ai-tool")
+    tool_resolved = resolve_tool(tool_raw_value) if tool_raw_value is not None else None
+    has_anchor = provider_raw_value is not None or tool_resolved is not None
+
+    mode_raw_value = values.get("ai-mode")
+    mode_candidate = _normalize_mode(mode_raw_value) if mode_raw_value is not None else None
+    is_human_only = mode_candidate is ContributionMode.HUMAN_ONLY
+
+    if is_human_only:
+        # Contradiction keys on KEY PRESENCE — even an empty-valued
+        # `AI-Provider:`/`AI-Tool:` line next to Human-Only is a
+        # contradictory declaration, never a clean human record
+        # (ADR-005; gate M-03).
+        if {"ai-provider", "ai-tool"} & group.present:
+            return None, [ParseWarning("contradictory-group", "ai-mode")]
+        return _build_human_spec(values)
+
+    if not has_anchor:
+        anchor_key = next(iter(values), None) or next(iter(sorted(group.present)))
+        return None, [ParseWarning("incomplete-group", anchor_key)]
+
+    return _build_ai_spec(values, provider_raw_value, tool_raw_value, tool_resolved)
+
+
+def _build_human_spec(group: dict[str, str]) -> tuple[ParticipationSpec, list[ParseWarning]]:
+    """AI-Mode: Human-Only with no AI provider/tool anchor → one HUMAN spec,
+    all six identity fields None (schema.md section 2)."""
+    warnings: list[ParseWarning] = []
+    roles, role_warnings = _parse_roles(group.get("ai-role"))
+    warnings.extend(role_warnings)
+    human_reviewed, reviewed_warning = _parse_reviewed_by(group.get("ai-reviewed-by"))
+    if reviewed_warning is not None:
+        warnings.append(reviewed_warning)
+
+    spec = ParticipationSpec(
+        actor_type=ActorType.HUMAN,
+        provider=None,
+        provider_raw=None,
+        model=None,
+        model_raw=None,
+        tool=None,
+        tool_raw=None,
+        roles=roles,
+        contribution_mode=ContributionMode.HUMAN_ONLY,
+        human_reviewed=human_reviewed,
+        source=ProvenanceSource(
+            source_type=SourceType.GIT_TRAILER,
+            evidence_level=EvidenceLevel.DECLARED,
+            source_reference="ai-mode",
+        ),
+    )
+    return spec, warnings
+
+
+def _build_ai_spec(
+    group: dict[str, str],
+    provider_raw_value: str | None,
+    tool_raw_value: str | None,
+    tool_resolved: tuple[str, str] | None,
+) -> tuple[ParticipationSpec, list[ParseWarning]]:
+    """A group anchored by AI-Provider and/or a resolvable AI-Tool → one AI
+    spec (schema.md section 10 normalization; explicit AI-Provider always
+    wins the provider fields over a tool's owning provider)."""
+    warnings: list[ParseWarning] = []
+
+    if provider_raw_value is not None:
+        provider = normalize_provider(provider_raw_value)
+        provider_raw = provider_raw_value
+    elif tool_resolved is not None:
+        provider = tool_resolved[1]
+        provider_raw = None
+    else:
+        provider = None
+        provider_raw = None
+
+    if tool_raw_value is not None:
+        tool = tool_resolved[0] if tool_resolved is not None else None
+        tool_raw = tool_raw_value
+    else:
+        tool = None
+        tool_raw = None
+
+    model_raw_value = group.get("ai-model")
+    if model_raw_value is not None:
+        model = model_raw_value.strip().lower()
+        model_raw = model_raw_value
+    else:
+        model = None
+        model_raw = None
+
+    roles, role_warnings = _parse_roles(group.get("ai-role"))
+    warnings.extend(role_warnings)
+
+    mode_raw_value = group.get("ai-mode")
+    mode: ContributionMode | None = None
+    if mode_raw_value is not None:
+        mode = _normalize_mode(mode_raw_value)
+        if mode is None:
+            warnings.append(ParseWarning("malformed-mode", "ai-mode", local_detail=mode_raw_value))
+
+    human_reviewed, reviewed_warning = _parse_reviewed_by(group.get("ai-reviewed-by"))
+    if reviewed_warning is not None:
+        warnings.append(reviewed_warning)
+
+    source_reference = "ai-provider" if "ai-provider" in group else "ai-tool"
+    spec = ParticipationSpec(
+        actor_type=ActorType.AI,
+        provider=provider,
+        provider_raw=provider_raw,
+        model=model,
+        model_raw=model_raw,
+        tool=tool,
+        tool_raw=tool_raw,
+        roles=roles,
+        contribution_mode=mode,
+        human_reviewed=human_reviewed,
+        source=ProvenanceSource(
+            source_type=SourceType.GIT_TRAILER,
+            evidence_level=EvidenceLevel.DECLARED,
+            source_reference=source_reference,
+        ),
+    )
+    return spec, warnings
+
+
+def _normalize_mode(raw: str) -> ContributionMode | None:
+    """Lowercase, '-'/' ' -> '_', then ContributionMode lookup; None when the
+    normalized token is not a recognized mode (docstring contract)."""
+    normalized = raw.strip().lower().replace("-", "_").replace(" ", "_")
+    try:
+        return ContributionMode(normalized)
+    except ValueError:
+        return None
+
+
+def _parse_roles(raw: str | None) -> tuple[tuple[Role, ...], list[ParseWarning]]:
+    """Comma-separated AI-Role tokens → Role vocabulary; unknown tokens are
+    dropped with an `unknown-role` warning; missing key or empty result is
+    `()` (docstring contract)."""
+    if raw is None:
+        return (), []
+    warnings: list[ParseWarning] = []
+    roles: list[Role] = []
+    for token in raw.split(","):
+        token = token.strip()
+        if not token:
+            continue
+        try:
+            role = Role(token.lower())
+        except ValueError:
+            warnings.append(ParseWarning("unknown-role", "ai-role", local_detail=token))
+            continue
+        roles.append(role)
+    return tuple(roles), warnings
+
+
+def _parse_reviewed_by(raw: str | None) -> tuple[bool | None, ParseWarning | None]:
+    """"human" -> True, "none" -> False, anything else -> None + a
+    `malformed-reviewed-by` warning; a missing key -> None with no warning
+    (docstring contract)."""
+    if raw is None:
+        return None, None
+    normalized = raw.strip().lower()
+    if normalized == "human":
+        return True, None
+    if normalized == "none":
+        return False, None
+    return None, ParseWarning("malformed-reviewed-by", "ai-reviewed-by", local_detail=raw)
+
+
+#: "Name <email>", tolerant of extra spaces around the name and brackets.
+_COAUTHOR_RE = re.compile(r"^\s*(?P<name>.*?)\s*<\s*(?P<email>[^<>\s]+)\s*>\s*$")
+
+
+def _parse_coauthor(value: str) -> ParticipationSpec | None:
+    """"Name <email>" -> AI spec via registry.match_coauthor; a malformed
+    shape (no "<email>") or no registry match is silently ignored
+    (docstring contract; ADR-013)."""
+    match = _COAUTHOR_RE.match(value)
+    if match is None:
+        return None
+    name = match.group("name").strip()
+    email = match.group("email").strip()
+    identity = match_coauthor(name, email)
+    if identity is None:
+        return None
+
+    return ParticipationSpec(
+        actor_type=ActorType.AI,
+        provider=identity.provider,
+        provider_raw=name,
+        model=None,
+        model_raw=None,
+        tool=identity.tool,
+        tool_raw=None,
+        roles=(),
+        contribution_mode=None,
+        human_reviewed=None,
+        source=ProvenanceSource(
+            source_type=SourceType.GIT_TRAILER_COAUTHOR,
+            evidence_level=EvidenceLevel.DECLARED,
+            source_reference=COAUTHOR_KEY,
+        ),
+    )