diff --git a/README.md b/README.md index 1db5cd8..71bdf10 100644 --- a/README.md +++ b/README.md @@ -2,13 +2,13 @@ A personal GitHub stars dashboard and repository discovery pipeline, built in phases: -| Phase | What | Status | -| ------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -| **P0** | Deterministic **exporter**: stars → canonical `stars.json` | ✅ complete | -| P1 | Static **dashboard** on GitHub Pages (client-side filter/sort/search) | ✅ complete | -| P2 | **Notifier**: YouTube / awesome-stars → one-shot Telegram delivery | release candidate (P2.5 closure); live run pending | -| P3 | **AI classification**: categories, tags, summaries, semantic search | P3.0–P3.4 implementation complete; P3.5 ADR complete; provenance-gate registration + live closeout pending before executor use | -| P4 | Reusable template / workflow (fork model, no key custody) | planned | +| Phase | What | Status | +| ------ | --------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | +| **P0** | Deterministic **exporter**: stars → canonical `stars.json` | ✅ complete | +| P1 | Static **dashboard** on GitHub Pages (client-side filter/sort/search) | ✅ complete | +| P2 | **Notifier**: YouTube / awesome-stars → one-shot Telegram delivery | release candidate (P2.5 closure); live run pending | +| P3 | **AI classification**: categories, tags, summaries, semantic search | P3.0–P3.4 implementation complete; P3.5 ADR complete; required checks configured, live closeout pending before executor use | +| P4 | Reusable template / workflow (fork model, no key custody) | planned | Contracts: **[`docs/P0-exporter-spec.md`](docs/P0-exporter-spec.md)** (exporter) · **[`docs/P1-dashboard-spec.md`](docs/P1-dashboard-spec.md)** (dashboard) · **[`docs/P2-notifier-spec.md`](docs/P2-notifier-spec.md)** (notifier) · **[`docs/P3-ai-spec.md`](docs/P3-ai-spec.md)** (optional AI enrichment). @@ -54,12 +54,20 @@ packages/schema @starred/schema canonical Zod model + JSON Sche packages/github-client @starred/github-client errors · retry coordinator · GraphQL probe/pagination/hydrate (bisection) · REST enumeration packages/exporter @starred/exporter config · enumerate (dual-path) · hydrate-merge · degraded gate · serialize · staged git publish · CLI packages/notifier @starred/notifier YouTube / awesome-stars source polling · durable state branch · pending queue · CLI -packages/ai-schema @starred/ai-schema strict optional-AI artifact, job, manifest, and candidate contracts -packages/classifier @starred/classifier deterministic candidate validation, artifact assembly, and agent diff gate -apps/dashboard @starred/dashboard Vite + React static site: trusted loading + schema validation (P1) +packages/ai-schema @starred/ai-schema strict optional-AI artifact/job/manifest/candidate contracts (+ crypto-free /contracts browser entrypoint) +packages/classifier @starred/classifier trusted planner, fingerprints, candidate reconciliation, artifact assembly, structural + provenance gates, operational state +apps/dashboard @starred/dashboard Vite + React static site: trusted canonical loading + optional fail-soft AI enrichment schemas/ generated JSON Schemas ``` +The optional P3 AI layer adds the workflows `ai-agent-pr.yml` (structural gate), +`ai-provenance.yml` (provenance gate), and `ai-state.yml` (trusted operational +state), plus the optional, fail-soft `ai-annotations.json` / `ai-annotations-meta.json` +artifacts the dashboard enriches from when present. The agent executor itself runs +**outside** this repo (no model call in CI); see +[`docs/P3-ai-spec.md`](docs/P3-ai-spec.md) and the +[`docs/P3.2-executor-runbook.md`](docs/P3.2-executor-runbook.md). + ## Running the notifier Configure watched channels in `config/notifier.yaml` (starting from diff --git a/docs/P3-ai-spec.md b/docs/P3-ai-spec.md index 4a1fd08..c7c205d 100644 --- a/docs/P3-ai-spec.md +++ b/docs/P3-ai-spec.md @@ -455,12 +455,12 @@ with no secret/backend and acceptable size + latency — see **Live closeout is operational and still PENDING.** There is no AI artifact on `main` yet, so no real executor run, provenance validation of a real artifact, AI -Pages deploy, or no-churn second run has occurred. Before enabling an executor, -add `verify-ai-provenance` to the `main` ruleset as a required check — it is -registered and tested but NOT yet required (only `verify-agent-artifacts` is). -Then: enable exactly one executor, produce one real artifact PR, confirm BOTH -required checks, merge via human review, confirm the Pages deploy and live AI -facets, and prove an unchanged second run produces no artifact PR or churn. +Pages deploy, or no-churn second run has occurred. `verify-ai-provenance` is now +required alongside `verify-agent-artifacts` and CI on `main`. Before enabling an +executor, confirm those protections remain active. Then: enable exactly one +executor, produce one real artifact PR, confirm all required checks, merge via +human review, confirm the Pages deploy and live AI facets, and prove an unchanged +second run produces no artifact PR or churn. `pnpm p3-gate` is the aggregate gate: typecheck, lint, format, the full test suite (AI schema drift, fingerprint/planner, injection fixtures, structural + provenance