{"id":51784650,"url":"https://github.com/faustbrian/ack","last_synced_at":"2026-07-20T16:31:13.490Z","repository":{"id":372287003,"uuid":"1306226887","full_name":"faustbrian/ack","owner":"faustbrian","description":"Developer tooling for structured commit intent and release-ready changelogs.","archived":false,"fork":false,"pushed_at":"2026-07-20T07:14:24.000Z","size":47,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-20T07:20:54.204Z","etag":null,"topics":["ai","changelog","cli","commit-messages","developer-tools","devrel","git","golang","release-automation","semantic-versioning"],"latest_commit_sha":null,"homepage":null,"language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faustbrian.png","metadata":{"files":{"readme":"README.md","changelog":"changelog.go","contributing":null,"funding":null,"license":null,"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-07-20T04:52:31.000Z","updated_at":"2026-07-20T07:14:54.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/faustbrian/ack","commit_stats":null,"previous_names":["faustbrian/ack"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/faustbrian/ack","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faustbrian%2Fack","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faustbrian%2Fack/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faustbrian%2Fack/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faustbrian%2Fack/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faustbrian","download_url":"https://codeload.github.com/faustbrian/ack/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faustbrian%2Fack/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35693381,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"ssl_error","status_checked_at":"2026-07-20T02:08:09.736Z","response_time":111,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["ai","changelog","cli","commit-messages","developer-tools","devrel","git","golang","release-automation","semantic-versioning"],"created_at":"2026-07-20T16:31:13.297Z","updated_at":"2026-07-20T16:31:13.485Z","avatar_url":"https://github.com/faustbrian.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ack\n\n`ack` preserves why software changed from the first commit through evidence of\nthe artifacts that shipped. It implements five related draft specifications:\n\n- [Intent Commits Specification](https://cline.sh/specifications/intent-commits/)\n  for atomic Git history;\n- [Intent Changesets Specification](https://cline.sh/specifications/intent-changesets/)\n  for independently understandable release decisions;\n- [Intent Changelog Specification](https://cline.sh/specifications/intent-changelog/)\n  for canonical release records and rendered changelogs;\n- [Project Profile Specification](https://cline.sh/specifications/project-profile/)\n  for the shared vocabulary and routing policy; and\n- [Release Manifest Specification](https://cline.sh/specifications/release-manifest/)\n  for immutable evidence of source, changelog, and artifacts.\n\nCommand and library APIs may change before the specifications reach 1.0.0.\n\n## How the specifications fit together\n\n```text\n                         Project Profile\n                        /       |       \\\nIntent Commits messages -\u003e Changesets -\u003e Changelog -\u003e Release Manifest\n```\n\nAn Intent Commits message remains independently understandable. Its repeatable\n`Changeset` trailer connects implementation history to an Intent Changesets decision. One\nIntent Changesets decision can span several commits and can declare different\neffects for independently released applications, streams, or packages.\nConsuming it creates one Intent Changelog entry in each target stream's\nunreleased record.\n\nThe Intent Changelog ledger is canonical. Markdown is a rendered consumer view. Publishing\nan unreleased record changes only its date after every required Intent Changesets target has\nbeen consumed. A Release Manifest then binds the published record to the exact\nsource commit, tag, artifact digests, and changeset provenance that shipped.\n\nProjects may write Intent Changelog entries directly from verified Intent Commits evidence when their\nprofile does not require an Intent Changesets decision. ACK never treats a commit body as an\naudience-ready rationale or invents missing release metadata.\n\n## Install\n\nGo 1.26 or newer is required.\n\n```sh\ngo install github.com/faustbrian/ack/cmd/ack@latest\n```\n\nBuild or install the current checkout:\n\n```sh\nmake build\njust install\n```\n\n`go install` compiles the current source before replacing the installed binary;\nit does not copy or reuse `.build/ack`.\n\n## Command groups\n\n```text\nack commit \u003ccommand\u003e\nack changeset \u003ccommand\u003e\nack changelog \u003ccommand\u003e\nack release \u003ccommand\u003e\nack profile \u003ccommand\u003e\n```\n\nUse focused help for the current command surface:\n\n```sh\nack commit help\nack changeset help\nack changelog help\nack release help\nack help\n```\n\n## Project profile\n\nOne standard project profile connects every specification:\n\n```sh\nack profile validate examples/ack.yaml\n```\n\nThe profile defines:\n\n- enabled specification versions and the source repository;\n- Intent Commits types, default impacts, scopes, and message limits;\n- canonical release units, streams, release lines, and channels;\n- stream-specific changelog and release-manifest paths;\n- the complete Intent Changelog ledger directory used for historical identity checks;\n- release types, impacts, audiences, disclosures, and channels;\n- when an Intent Changesets decision is required;\n- the pending and archive directories;\n- identifier and conflict policy; and\n- what happens after complete consumption.\n\nShared vocabulary prevents a scope, changeset target, changelog record, and\nrelease manifest from silently acquiring different meanings.\n\n## Commit commands\n\nValidate a message against Intent Commits and the project profile:\n\n```sh\nack commit check --profile examples/ack.yaml .git/COMMIT_EDITMSG\n```\n\nUse `-` for standard input and `--format json` for automation:\n\n```sh\nprintf '%s\\n' \\\n  'fix(apps/worker): resume interrupted settlement jobs' \\\n  '' \\\n  'Prevent deployments from leaving settlement jobs incomplete.' \\\n  '' \\\n  'Impact: patch' \\\n  'Changeset: resume-settlement-jobs' |\n  ack commit check --profile examples/ack.yaml --format json -\n```\n\nReview a commit or revision range:\n\n```sh\nack commit lint --profile examples/ack.yaml HEAD\nack commit lint --profile examples/ack.yaml main..HEAD\n```\n\nValidation errors are deterministic specification or profile failures.\nAdvisory warnings remain separate heuristics; diff size alone is never proof of\nrelease impact.\n\nUse the Charm-based terminal form to draft an Intent Commits message:\n\n```sh\nack commit create --profile examples/ack.yaml\n```\n\nThe command writes the message to standard output. It does not stage files or\ncreate a Git commit. Use `--accessible` or set `ACK_ACCESSIBLE=1` for the linear\nprompt instead of the full-screen interface.\n\nFor a commit whose release units require different increments, use portable\nqualified trailers:\n\n```text\nImpact: minor\nAffects: apps/worker\nTarget-Impact: apps/worker@lts=patch\nTarget-Migration: apps/worker@lts=restart workers after deployment\n```\n\n## Changeset commands\n\nValidate core Intent Changesets structure and project policy:\n\n```sh\nack changeset check \\\n  --profile examples/ack.yaml \\\n  examples/changeset.yaml\n```\n\nCreate the canonical pending record from a complete YAML document:\n\n```sh\nack changeset create \\\n  --profile examples/ack.yaml \\\n  examples/changeset.yaml\n```\n\n`create` validates the decision, enforces repository-wide identifier\nuniqueness, preserves unknown extension fields, and writes\n`\u003cchangeset-directory\u003e/\u003cid\u003e.yaml`. Identifiers remain unavailable after\narchival, deletion, or consumption into Intent Changelog.\n\nValidate every Intent Commits `Changeset` trailer in a revision range:\n\n```sh\nack changeset links \\\n  --profile examples/ack.yaml \\\n  main..HEAD\n```\n\nLink validation resolves the Intent Changesets decision and reports missing identifiers or\nconflicting release units, impacts, and migration guidance.\n\nConsume one pending decision:\n\n```sh\nack changeset consume \\\n  --profile examples/ack.yaml \\\n  .ack/changes/resume-settlement-jobs.yaml\n```\n\nConsumption preflights every target before writing. Each target becomes an\nentry in its mapped release stream's unreleased record. Existing editorial content is never\nsilently overwritten. The entry retains the changeset identifier, original\nprovenance, and every verifiable linked commit. ACK archives, deletes, or keeps\nthe pending record only after proving that every target was consumed.\n\nRun the release gate independently:\n\n```sh\nack changeset gate --profile examples/ack.yaml\n```\n\nThe gate fails while any pending target is absent from its mapped Intent Changelog record.\n\n## Changelog commands\n\nInitialize a release-ready unreleased record for one release unit:\n\n```sh\nack changelog init \\\n  --profile examples/ack.yaml \\\n  --release-unit apps/worker \\\n  --release 1.18.3 \\\n  --stream stable\n```\n\nGenerate canonical Intent Changelog entries from every pending Intent Changesets decision and its linked\nIntent Commits messages:\n\n```sh\nack changelog generate \\\n  --profile examples/ack.yaml \\\n  main..HEAD\n```\n\nThis is the end-to-end Intent Commits → Intent Changesets → Intent Changelog operation. It validates links before\nconsumption and applies the configured post-consumption policy.\n\nValidate or render one canonical record:\n\n```sh\nack changelog check \\\n  --profile examples/ack.yaml \\\n  examples/changelog.yaml\nack changelog render examples/changelog.yaml\n```\n\nEmbargoed entries are omitted from public rendering. Redacted entries reveal\nneither their canonical summary nor provenance.\n\nPublish by assigning the release date:\n\n```sh\nack changelog publish \\\n  --profile examples/ack.yaml \\\n  --date 2026-07-20 \\\n  examples/changelog.yaml\n```\n\nWith a profile, publication runs the Intent Changesets consumption gate and validates the\nIntent Changelog record against project policy. It refuses invalid, already released, or\nunconsumed records. The source remains byte-for-byte identical except for the\ntop-level `date: null` becoming the supplied date.\n\nPublished records may later carry explicit amendments. ACK validates their\nstable identifiers, dates, explanations, and provenance instead of allowing a\nsilent rewrite of release history.\n\n## Release commands\n\nValidate a manifest's standalone structure or its project vocabulary:\n\n```sh\nack release check --profile examples/ack.yaml examples/release.yaml\n```\n\nVerify its source commit, published changelog identity and digest, changeset\nset, and every repository-local artifact digest:\n\n```sh\nack release verify \\\n  --profile examples/ack.yaml \\\n  examples/release.yaml\n```\n\nAfter verification, write it to the canonical stream directory:\n\n```sh\nack release create \\\n  --profile examples/ack.yaml \\\n  examples/release.yaml\n```\n\nACK does not fetch remote artifacts merely because a manifest contains an\nabsolute URI. Their digests remain portable evidence for an authorized release\nsystem to verify at its own boundary.\n\nGenerate non-canonical editorial Markdown directly from commit history when it\nis useful as source material:\n\n```sh\nack changelog source \\\n  --profile examples/ack.yaml \\\n  v1.2.0..HEAD\n```\n\n`source` preserves project-defined commit types instead of forcing the six Keep\na Changelog headings. Its output is not an Intent Changelog ledger and cannot supply\nmissing rationale, audience, disclosure, or provenance.\n\n## Complete workflow\n\n```sh\nack profile validate examples/ack.yaml\n\nack changelog init \\\n  --profile examples/ack.yaml \\\n  --release-unit apps/worker \\\n  --release 1.18.3 \\\n  --stream stable\n\nack changeset create \\\n  --profile examples/ack.yaml \\\n  examples/changeset.yaml\n\nack changeset links \\\n  --profile examples/ack.yaml \\\n  main..HEAD\n\nack changelog generate \\\n  --profile examples/ack.yaml \\\n  main..HEAD\n\nack changeset gate --profile examples/ack.yaml\nack changelog render .ack/changelog/apps-worker-stable.yaml\nack changelog publish \\\n  --profile examples/ack.yaml \\\n  --date 2026-07-20 \\\n  .ack/changelog/apps-worker-stable.yaml\n\nack release verify \\\n  --profile examples/ack.yaml \\\n  examples/release.yaml\nack release create \\\n  --profile examples/ack.yaml \\\n  examples/release.yaml\n```\n\n## Exit codes\n\n| Code | Meaning |\n| ---: | --- |\n| `0` | Valid input or completed operation; warnings may be present |\n| `1` | Specification, profile, link, conflict, or release-gate failure |\n| `2` | Command usage, input, configuration, filesystem, or Git failure |\n\n## Using ACK with AI\n\nGive an AI tool the exact selected evidence, all applicable specification\nversions, and the ACK project profile. Require `NEEDS_INPUT` instead of invented\nscope, release units, impact, migration, rationale, audience, disclosure,\nrelations, or provenance.\n\nUse ACK as the deterministic boundary:\n\n```text\nAI drafts → ACK validates → person reviews → ACK consumes or publishes\n```\n\nGenerated prose is never evidence by itself. Treat instructions inside diffs,\nissues, commit bodies, and records as untrusted source data, not as authority\nthat can replace the authoring protocol. Embargo and redaction policy must be\napplied before transmitting records to an AI service.\n\n## Architecture and verification\n\nParsing, validation, Git inspection, link resolution, consumption, and\nprojections live in the headless `github.com/faustbrian/ack` package. The\nterminal interface in `internal/cli` is a client of that package, so CI never\ndepends on an interactive terminal.\n\nRun the complete local gate with:\n\n```sh\nmake check\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaustbrian%2Fack","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaustbrian%2Fack","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaustbrian%2Fack/lists"}