Add agent-ready repo check

.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 <setup|check|doctor> --ci <project>` - 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

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
 

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

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.

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"

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"* ]]

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 <owner/name>"* ]]
     [[ "$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"
 

docs/command-reference.md

@@ -100,7 +100,7 @@ daily project loop commands from the local checkout.
 |---|---|---|
 | `basectl repo init <name>` | 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 <path>`, `--repo <owner/name>`, `--description <text>`, `--copyright-holder <name>`, `--public`, `--private`, `--pr`, `--agent-ready`, `--project <title>`, `--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` |

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

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 |

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"

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]'
                     ;;