{"id":51316198,"url":"https://github.com/hop-top/spec-12fc","last_synced_at":"2026-07-01T07:31:17.550Z","repository":{"id":362238935,"uuid":"1258013617","full_name":"hop-top/spec-12fc","owner":"hop-top","description":"Build agent-first command line tools — the 12-Factor AI-CLI specification and conformance Action.","archived":false,"fork":false,"pushed_at":"2026-06-03T08:49:01.000Z","size":83,"stargazers_count":0,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-06-03T09:25:35.914Z","etag":null,"topics":["12-factor","agent","agentic","ai","ai-agents","cli","conformance","github-action","llm","spec"],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hop-top.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-06-03T07:48:44.000Z","updated_at":"2026-06-03T08:49:06.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/hop-top/spec-12fc","commit_stats":null,"previous_names":["hop-top/spec-12fc"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/hop-top/spec-12fc","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fspec-12fc","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fspec-12fc/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fspec-12fc/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fspec-12fc/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hop-top","download_url":"https://codeload.github.com/hop-top/spec-12fc/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hop-top%2Fspec-12fc/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34997946,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-01T02:00:05.325Z","response_time":130,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["12-factor","agent","agentic","ai","ai-agents","cli","conformance","github-action","llm","spec"],"created_at":"2026-07-01T07:31:16.635Z","updated_at":"2026-07-01T07:31:17.536Z","avatar_url":"https://github.com/hop-top.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 12-Factor CLI Conformance\n\nA GitHub Action that verifies a CLI conforms to the [12-Factor AI-CLI specification](specs/v0.1/spec.md), generates a structured JSON report, a shields.io endpoint-badge JSON, and (optionally) SARIF results that annotate the PR diff via GitHub code-scanning.\n\n```yaml\n- uses: hop-top/spec-12fc@v1\n```\n\n## What it does\n\n- Runs the `kit conformance` gate tree (`verify-no-leak`, `verify-stories`, optional `grade`) against your CLI source.\n- Aggregates leaf results into a single `12fc-report.json` with stable schema.\n- Builds a per-factor matrix (`12fc-matrix.json`) covering all 12 factors of the spec.\n- Generates `.12fc.json` — the shields.io endpoint-badge payload — so a single badge in your README always reflects the latest verdict.\n- Emits SARIF and uploads to GitHub code-scanning so individual findings render inline on the PR diff.\n- Posts a sticky PR comment with the verdict, leaf-level breakdown, and the first 20 findings.\n- Optionally commits the updated badge JSON back to your default branch on `push` events.\n\n## Outputs\n\n| File | Purpose |\n|------|---------|\n| `12fc-report.json` | Full aggregated report (schema `12fc/v1`) |\n| `12fc-matrix.json` | Per-factor pass/fail matrix |\n| `.12fc.json` | shields.io endpoint-badge payload |\n| `12fc.sarif` | SARIF v2.1.0 results for code-scanning |\n\n## Exit codes\n\nInherited from `kit conformance`:\n\n| Code | Meaning |\n|------|---------|\n| 0 | clean |\n| 2 | leak detected |\n| 3 | usage error |\n| 4 | I/O error (retryable) |\n| 5 | config error |\n\nThe Action fails the job when the aggregate exit code is in `fail-on` (default `2,3,5` — code 4 is excluded so flaky networks don't red-light the build).\n\n## Inputs\n\nSee [`action.yml`](action.yml). Defaults are tuned for the common case (PR gate with a sticky comment, no badge commit). For a push-only badge regeneration workflow, set `pr-comment: false` and `commit-badge: true`.\n\n## Badge\n\nAfter the Action runs at least once on your default branch with `commit-badge: true`, add this to your README:\n\n```markdown\n![12fc](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/\u003cowner\u003e/\u003crepo\u003e/main/.12fc.json)\n```\n\nThe badge colour is verdict-driven: green (pass), red (fail), grey (ungradable / not yet run).\n\n## Example workflow\n\nSee [`specs/v0.1/examples/workflow.yml`](specs/v0.1/examples/workflow.yml).\n\n## How factors map to leaves\n\n| Factor | Leaf | Notes |\n|--------|------|-------|\n| F1 Capability Introspection | `verify-stories` | story-doc presence + shape |\n| F2 Intent Clarity | `verify-stories` | grammar / noun-verb check |\n| F3 Structured I/O | `grade` | requires service tier |\n| F4 Corrective Error Model | `grade` | typed error contract |\n| F5 Explicit Contracts | `grade` | side-effect annotations |\n| F6 Previewability | `grade` | dry-run discipline |\n| F7 Idempotency | `grade` | declarative-verb check |\n| F8 State Transparency | `grade` | `status` subcommand probe |\n| F9 Contextual Guidance | `verify-stories` | examples + next-steps |\n| F10 Delegation Safety | `verify-no-leak` | scenario isolation |\n| F11 Exit Code Semantics | `grade` | exit-code taxonomy probe |\n| F12 Evolution Guarantees | `verify-stories` | schema version present |\n\nFactors without an active leaf fall back to `skip` in the matrix (grey).\n\n## The spec\n\nThe full specification lives in [`specs/v0.1/spec.md`](specs/v0.1/spec.md). This Action is the executable counterpart: every `MUST` in the spec maps to a check the gate enforces.\n\n## Contributing\n\nLocal checks mirror CI:\n\n```bash\nmake hooks     # one-time: enable .githooks/pre-push (runs make ci on every push)\nmake ci        # lint + tests\nmake check-tools\n```\n\nRequires `python3` and `markdownlint-cli2` (`npm i -g markdownlint-cli2`).\n\n## License\n\nCC-BY-4.0 for the spec text; MIT for examples and this Action's code.\nSee [`LICENSE`](LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhop-top%2Fspec-12fc","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhop-top%2Fspec-12fc","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhop-top%2Fspec-12fc/lists"}