Skip to content

docs(p3): align AI status and closeout guidance #12

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
F-e-u-e-r merged 2 commits into from
Jun 22, 2026
+24 −16
Merged

docs(p3): align AI status and closeout guidance #12

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4cd5868
docs(readme): document P3 AI architecture
Jun 22, 2026
8671a01
docs(p3): record required gate configuration
Jun 22, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 18 additions & 10 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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).

Expand Down Expand Up @@ -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
Expand Down
12 changes: 6 additions & 6 deletions docs/P3-ai-spec.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading