diff --git a/.ai-context/COMMANDS.md b/.ai-context/COMMANDS.md index e5eb13eb..4c1dc4aa 100644 --- a/.ai-context/COMMANDS.md +++ b/.ai-context/COMMANDS.md @@ -62,8 +62,9 @@ options. repositories to the configured workspace root; use `--path .` for the current checkout. Plain `repo init` writes local baseline files without committing or pushing them; `repo init --agent-ready` also seeds `AGENTS.md` and `skills.md`; - `repo init --pr` commits baseline changes on a branch, pushes to `origin`, and - opens a PR. + `repo check --agent-ready` verifies that baseline-integrated agent guidance + contract; `repo init --pr` commits baseline changes on a branch, pushes to + `origin`, and opens a PR. - `basectl --ci ` - run Base setup/check/doctor with CI-safe defaults. It does not run project tests or create CI runners/VMs. `setup --ci --format json` uses `output` for the compact final status and diff --git a/CHANGELOG.md b/CHANGELOG.md index b30331ec..8d5ba935 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -32,6 +32,8 @@ and Base versions are tracked in the repo-root `VERSION` file. CI behavior. - Added `basectl repo init --agent-ready` to seed `AGENTS.md` and `skills.md` alongside the standard repo baseline. +- Added `basectl repo check --agent-ready` to verify the agent-ready repo + guidance contract without changing default baseline checks. ### Changed diff --git a/README.md b/README.md index 3e1b62b9..47ad2443 100644 --- a/README.md +++ b/README.md @@ -686,11 +686,13 @@ basectl repo init example --repo basefoundry/example --agent-ready basectl repo agent-guidance ~/work/example --repo-name example basectl repo agent-guidance ~/work/example --repo-name example --pr --dry-run basectl repo check ~/work/example --agent-guidance +basectl repo check ~/work/example --agent-ready ``` Use `repo init --agent-ready` for new baselines that should include agent guidance from the first pull request. Use `repo agent-guidance` to add or repair -that optional layer in an existing repository. +that optional layer in an existing repository. Use `repo check --agent-ready` +when a repo should satisfy the baseline-integrated agent readiness contract. Use `--pr` on `repo agent-guidance` or `repo installer-template` when the generated helper files should go through review first. The target must be a diff --git a/cli/bash/commands/basectl/README.md b/cli/bash/commands/basectl/README.md index 1a6ef0e5..304119d7 100644 --- a/cli/bash/commands/basectl/README.md +++ b/cli/bash/commands/basectl/README.md @@ -142,10 +142,11 @@ such command directories exist. Optional utility CLIs such as `caff` and preserves missing item field values where possible. Already-standard Projects are left intact. `basectl repo agent-guidance [path]` seeds optional repo-local agent guidance - files for existing repos, and `basectl repo check [path] --agent-guidance` - verifies that optional layer for repos that opt in. Use `--pr` when generated - guidance should land through a draft pull request instead of direct file - generation. + files for existing repos, `basectl repo check [path] --agent-guidance` + verifies that optional layer for repos that opt in, and + `basectl repo check [path] --agent-ready` verifies the baseline-integrated + agent readiness contract. Use `--pr` when generated guidance should land + through a draft pull request instead of direct file generation. `basectl repo installer-template [path]` prints or writes the maintained project installer starter script. Use `--pr` with a path to open the generated installer template as a draft pull request. diff --git a/cli/bash/commands/basectl/subcommands/repo.sh b/cli/bash/commands/basectl/subcommands/repo.sh index 6e90cfcd..1f5301e2 100644 --- a/cli/bash/commands/basectl/subcommands/repo.sh +++ b/cli/bash/commands/basectl/subcommands/repo.sh @@ -138,6 +138,7 @@ Usage: Options: --agent-guidance Include optional agent guidance files in repo check. + --agent-ready Include the agent-ready repo guidance contract in repo check. -v Enable DEBUG logging for this subcommand. -h, --help Show this help text. @@ -1931,6 +1932,40 @@ base_repo_check_agent_guidance() { return 0 } +base_repo_check_agent_ready() { + local command=() + local missing_files=() + local path="$1" + local rel + local repo_name + local required_count="${#BASE_REPO_AGENT_GUIDANCE_FILES[@]}" + + for rel in "${BASE_REPO_AGENT_GUIDANCE_FILES[@]}"; do + if [[ ! -f "$path/$rel" ]]; then + missing_files+=("$rel") + fi + done + + if ((${#missing_files[@]})); then + printf "Agent readiness: %d of %d files missing.\n" \ + "${#missing_files[@]}" \ + "$required_count" + for rel in "${missing_files[@]}"; do + printf " Missing: %s\n" "$rel" + done + repo_name="$(basename -- "$path")" + command=(basectl repo init "$repo_name" --path "$path" --agent-ready) + printf "Run '" + base_repo_pretty_command "${command[@]}" + printf "' to create the missing files.\n" + printf "Existing files are left unchanged.\n" + return 1 + fi + + printf "Agent readiness: all %d files present.\n" "$required_count" + return 0 +} + base_repo_init() { local agent_default_branch="main" local agent_ready=0 @@ -2428,6 +2463,7 @@ base_repo_clone() { base_repo_check() { local agent_guidance=0 + local agent_ready=0 local path="" local status=0 @@ -2441,6 +2477,10 @@ base_repo_check() { agent_guidance=1 shift ;; + --agent-ready) + agent_ready=1 + shift + ;; -v) set_log_level DEBUG export LOG_DEBUG=1 @@ -2464,7 +2504,9 @@ base_repo_check() { [[ -n "$path" ]] || path="." path="$(base_repo_target_path "$path")" base_repo_check_baseline "$path" || status=1 - if ((agent_guidance)); then + if ((agent_ready)); then + base_repo_check_agent_ready "$path" || status=1 + elif ((agent_guidance)); then base_repo_check_agent_guidance "$path" || status=1 fi return "$status" diff --git a/cli/bash/commands/basectl/tests/completions.bats b/cli/bash/commands/basectl/tests/completions.bats index 6f0eccbe..2acc5142 100644 --- a/cli/bash/commands/basectl/tests/completions.bats +++ b/cli/bash/commands/basectl/tests/completions.bats @@ -298,7 +298,7 @@ EOF [[ "$output" == *"repo_commands=init clone check configure agent-guidance installer-template"* ]] [[ "$output" == *"repo_init_options=--path --repo --pr --agent-ready --description --copyright-holder --private --public --no-configure --no-protect-default-branch --project --project-owner --project-schema --initiative-option --copy-project-fields-from --no-project --dry-run"* ]] [[ "$output" == *"repo_clone_options=--owner --path --dry-run"* ]] - [[ "$output" == *"repo_check_options=--agent-guidance"* ]] + [[ "$output" == *"repo_check_options=--agent-guidance --agent-ready"* ]] [[ "$output" == *"repo_configure_options=--repo --no-protect-default-branch --project --project-owner --project-schema --initiative-option --copy-project-fields-from --replace-project --no-project --dry-run"* ]] [[ "$output" == *"repo_agent_guidance_options=--repo --repo-name --default-branch --validation-command --pr --dry-run"* ]] [[ "$output" == *"repo_installer_template_options=--print --stdout --repo --pr --dry-run"* ]] diff --git a/cli/bash/commands/basectl/tests/repo.bats b/cli/bash/commands/basectl/tests/repo.bats index c82328f2..291b61dc 100644 --- a/cli/bash/commands/basectl/tests/repo.bats +++ b/cli/bash/commands/basectl/tests/repo.bats @@ -404,6 +404,7 @@ EOF [[ "$output" == *"Usage:"* ]] [[ "$output" == *"basectl repo check [path] [options]"* ]] [[ "$output" == *"--agent-guidance"* ]] + [[ "$output" == *"--agent-ready"* ]] [[ "$output" != *"--repo "* ]] [[ "$output" != *"--pr"* ]] } @@ -1375,6 +1376,36 @@ EOF [[ "$output" == *"Agent guidance: all 3 files present."* ]] } +@test "basectl repo check --agent-ready reports missing agent-ready files" { + local repo_dir="$TEST_TMPDIR/base-demo" + + run_basectl repo init base-demo --path "$repo_dir" --no-configure + [ "$status" -eq 0 ] + + run_basectl repo check "$repo_dir" --agent-ready + + [ "$status" -eq 1 ] + [[ "$output" == *"Repository baseline: all 12 required files present."* ]] + [[ "$output" == *"Agent readiness: 2 of 3 files missing."* ]] + [[ "$output" == *"Missing: AGENTS.md"* ]] + [[ "$output" == *"Missing: skills.md"* ]] + [[ "$output" == *"Run 'basectl repo init base-demo --path $repo_dir --agent-ready' to create the missing files."* ]] + [[ "$output" == *"Existing files are left unchanged."* ]] +} + +@test "basectl repo check --agent-ready passes after agent-ready init" { + local repo_dir="$TEST_TMPDIR/base-demo" + + run_basectl repo init base-demo --path "$repo_dir" --agent-ready --no-configure + [ "$status" -eq 0 ] + + run_basectl repo check "$repo_dir" --agent-ready + + [ "$status" -eq 0 ] + [[ "$output" == *"Repository baseline: all 12 required files present."* ]] + [[ "$output" == *"Agent readiness: all 3 files present."* ]] +} + @test "basectl repo configure dry-run prints GitHub settings and labels" { local repo_dir="$TEST_TMPDIR/repo" diff --git a/docs/command-reference.md b/docs/command-reference.md index 8815909c..6f3d440a 100644 --- a/docs/command-reference.md +++ b/docs/command-reference.md @@ -100,7 +100,7 @@ daily project loop commands from the local checkout. |---|---|---| | `basectl repo init ` | Create a Base-managed repository baseline, including `.github/base-project.yml`, and optionally create/configure the GitHub repo. Use `--path .` for the current checkout; plain init does not commit or push local files, while `--pr` commits baseline changes on a branch, pushes it to `origin`, and opens a PR. Use `--agent-ready` to seed `AGENTS.md` and `skills.md` with the baseline. | `--path `, `--repo `, `--description `, `--copyright-holder `, `--public`, `--private`, `--pr`, `--agent-ready`, `--project `, `--project-owner <login>`, `--project-schema <schema>`, `--copy-project-fields-from <title>`, `--initiative-option <name>`, `--no-configure`, `--no-project`, `--no-protect-default-branch`, `--dry-run` | | `basectl repo clone <name-or-owner/name>` | Clone one GitHub repository into the configured Base workspace, treating matching existing checkouts as already satisfied. | `--owner <owner>`, `--path <path>`, `--dry-run` | -| `basectl repo check [path]` | Verify the local repository baseline. | `--agent-guidance` | +| `basectl repo check [path]` | Verify the local repository baseline. | `--agent-guidance`, `--agent-ready` | | `basectl repo configure [path]` | Apply Base-managed GitHub repository settings, labels, branch protection, and repo Project metadata. Reads `.github/base-project.yml` to seed options and fill missing issue defaults when present. | `--repo <owner/name>`, `--project <title>`, `--project-owner <login>`, `--project-schema <schema>`, `--copy-project-fields-from <title>`, `--initiative-option <name>`, `--replace-project`, `--no-project`, `--no-protect-default-branch`, `--dry-run` | | `basectl repo agent-guidance [path]` | Seed optional repo-local agent guidance files, optionally through a draft PR. | `--repo <owner/name>`, `--repo-name <name>`, `--default-branch <name>`, `--validation-command <cmd>`, `--pr`, `--dry-run` | | `basectl repo installer-template [path]` | Write the maintained project installer starter script to a path, defaulting to `./install.sh`, optionally through a draft PR. | `--print`, `--repo <owner/name>`, `--pr`, `--dry-run` | diff --git a/docs/repo-baseline.md b/docs/repo-baseline.md index 1b3cbcd7..f544246b 100644 --- a/docs/repo-baseline.md +++ b/docs/repo-baseline.md @@ -87,6 +87,7 @@ Check the local baseline: ```bash basectl repo check ~/work/base-demo +basectl repo check ~/work/base-demo --agent-ready ``` Seed optional repo-local agent guidance: @@ -286,8 +287,14 @@ has opted into this layer: ```bash basectl repo check ~/work/base-demo --agent-guidance +basectl repo check ~/work/base-demo --agent-ready ``` +Use `--agent-guidance` when checking only the standalone optional guidance +layer. Use `--agent-ready` when checking the same file contract through the +`repo init --agent-ready` repair path; missing files are reported with a +no-overwrite `repo init ... --agent-ready` fix command. + ## Git Workflow The generated `CONTRIBUTING.md` and pull request template seed a portable diff --git a/docs/technical-overview.md b/docs/technical-overview.md index 1cf6656d..62500194 100644 --- a/docs/technical-overview.md +++ b/docs/technical-overview.md @@ -196,7 +196,7 @@ and their own build systems. See [Setup Hooks Boundary](setup-hooks.md). | Command | What it does | |---|---| | `basectl repo init <name> [--repo owner/name]` | Create a Base-managed repo baseline; use `--agent-ready` to include `AGENTS.md` and `skills.md`, `--path .` for the current checkout, and `--pr` when baseline changes should be pushed through a PR | -| `basectl repo check [path]` | Validate repo baseline | +| `basectl repo check [path]` | Validate repo baseline; use `--agent-ready` for the baseline-integrated agent guidance contract | | `basectl repo configure [path]` | Repair / standardize repo settings | | `basectl repo agent-guidance [path]` | Seed AI guidance for a repo | | `basectl release check\|plan\|notes\|publish` | Release readiness + guarded publishing | diff --git a/lib/shell/completions/basectl_completion.sh b/lib/shell/completions/basectl_completion.sh index 0a015b9d..e7d687d3 100644 --- a/lib/shell/completions/basectl_completion.sh +++ b/lib/shell/completions/basectl_completion.sh @@ -244,7 +244,7 @@ _base_basectl_completion() { _base_basectl_completion_compgen "--owner --path --dry-run -v -h --help" "$cur" ;; check) - _base_basectl_completion_compgen "--agent-guidance -v -h --help" "$cur" + _base_basectl_completion_compgen "--agent-guidance --agent-ready -v -h --help" "$cur" ;; configure) _base_basectl_completion_compgen "--repo --no-protect-default-branch --project --project-owner --project-schema --initiative-option --copy-project-fields-from --replace-project --no-project --dry-run -v -h --help" "$cur" diff --git a/lib/shell/completions/basectl_completion.zsh b/lib/shell/completions/basectl_completion.zsh index f3b4c323..9a3c2d71 100644 --- a/lib/shell/completions/basectl_completion.zsh +++ b/lib/shell/completions/basectl_completion.zsh @@ -351,6 +351,7 @@ _base_basectl_completion() { _arguments '1:repo command:(init clone check configure agent-guidance installer-template)' \ '2:path:_files' \ '--agent-guidance[Include optional agent guidance files]' \ + '--agent-ready[Include the agent-ready repo guidance contract]' \ '-v[Enable DEBUG logging]' \ '(-h --help)'{-h,--help}'[Show help text]' ;;