Repository navigation
docs: add AI context and stabilize timeout regression - #582
codeforester wants to merge 2 commits into
Conversation
codeforester
changed the title
| the exporter does not inline their targets. Keep core explanations self-contained. | ||
| Use real regular files, not symlinks. Store generated bundles outside the project | ||
| and keep generation timestamps out of source pages so unchanged exports remain | ||
| byte-identical. This pack is picked up automatically by workspace export jobs. |
There was a problem hiding this comment.
Unsupported/false claim: "This pack is picked up automatically by workspace export jobs." I grepped the entire base ecosystem (base, base-cli, base-demo, base-bash-libs, base-cli-demo, base-bash-libs-demo, base-platform-tools, basefoundry-dot-github) for any CI workflow, cron, or batch job that runs basectl export-context automatically, and found none — it's a manual, single-project, on-demand command (no --all/batch mode exists in cli/python/base_export_context/engine.py). base's own .ai-context/README.md makes no such automatic-pickup claim. A contributor reading this line could reasonably skip manually running export-context after editing the pack, believing some job keeps it in sync — nothing does, so the pack can silently go stale with no detection.
| Start AI-assisted orientation with [.ai-context/INDEX.md](.ai-context/INDEX.md). | ||
| Maintain these curated summaries alongside meaningful changes to product scope, | ||
| architecture, commands, or contributor workflows. Canonical docs and code remain | ||
| the source of truth; update the pack when they disagree. State context impact in |
There was a problem hiding this comment.
Toothless instruction: "State context impact in the PR, including a reason when no update is needed" reads as a sibling to the existing required Demo/Docs/API/CI Impact sections, but isn't backed by the same machinery. base_manifest.yaml's github.pr.required_sections maps docs/**→Docs Impact, lib/bash/**→API Impact, .github/**→CI Impact, and label security→Security Notes — there is no rule for .ai-context/**, and .github/pull_request_template.md has no "Context Impact" heading at all. A contributor following this instruction has no designated place to put the statement and nothing enforces or even prompts for it, unlike every other impact section CONTRIBUTING.md/AGENTS.md reference. Concrete failure: a contributor omits the statement entirely (or writes it somewhere ad hoc) while believing it's equally enforced — nothing surfaces the omission.
| runtime evidence or an authoritative release/status registry. Start with | ||
| [INDEX.md](INDEX.md). | ||
|
|
||
| Keep purpose, architecture, commands, and workflows aligned with code and |
There was a problem hiding this comment.
Copy-paste residue referencing a nonexistent category: "Keep purpose, architecture, commands, and workflows aligned with code and canonical documentation" lists "commands" as one of four things to keep aligned, and CONTRIBUTING.md:128 (added in the same PR) repeats "architecture, commands, or contributor workflows." But this pack's own INDEX.md only enumerates PROJECT (purpose) / ARCHITECTURE / WORKFLOWS / README (maintenance) — there is no COMMANDS.md page here, unlike base's own .ai-context pack (which this was clearly modeled on and which does have a COMMANDS.md for its command surface). A maintainer told to "keep commands aligned" has no artifact to update, making the instruction ambiguous/unfulfillable as written.
| the PR, including a reason when no update is needed. Typo-only and internal changes | ||
| without behavioral or architectural impact usually need no context update. | ||
|
|
||
| Validate changes with `basectl export-context --list-files` and |
There was a problem hiding this comment.
No mechanical enforcement (altitude): this instructs contributors to manually run basectl export-context --list-files/--print and git diff --check "from the checkout", but nothing in CI actually runs them. tests/validate.sh (the repo's CI entrypoint) never references .ai-context or export-context, and its required_files existence-check array does not list any of the 5 new .ai-context/*.md files either — so the pack can be deleted, left stale, or develop broken relative links and CI stays green forever. This is the same honor-system-only gap the related base project's 2026-10-18 docs-drift audit flagged (proposing a PR Impact-block + docs-impact CI lane, not yet implemented) — this PR adds more manual-only documentation-sync surface rather than wiring one of its own already-documented commands (e.g. basectl export-context --list-files, which fails non-zero on missing/broken/symlinked files) into tests/validate.sh.
| Use it where Bash is an intentional runtime constraint and shared application | ||
| infrastructure is useful. It does not require the Base workspace runtime and | ||
| does not own an application's domain policy. Homebrew installation, vendored | ||
| release bundles, source checkouts, and submodules are supported consumption paths. |
There was a problem hiding this comment.
Inaccurate conflation of consumption paths: "Homebrew installation, vendored release bundles, source checkouts, and submodules are supported consumption paths" merges two distinct, separately-documented things into a nonexistent hybrid category. README.md's real categories are Homebrew / Source Checkout (git checkout, tarball extract, or copied tree) / Vendored or Submodule Layout (placement pattern, covers both vendored copies and git submodules) — plus an independently-documented standalone release-archive download path (README.md:294, "Pinned checkout, archive, Homebrew, vendored, and standalone consumption..."). "Vendored release bundles" names neither the real "vendored" placement pattern nor the real "release archive" download path accurately, and omits the standalone archive-download path entirely. A reader could wrongly conclude there's no independent "download the verified tarball" consumption path, or misunderstand what "vendoring" means in this repo (placement, not bundling a release archive).
| Run the offline workflow regression tests with | ||
| `python3 tests/project-intake-test.py`; they also run in `./tests/validate.sh`. | ||
|
|
||
| ## AI Context Maintenance |
There was a problem hiding this comment.
Same-PR duplication: this new "AI Context Maintenance" section restates .ai-context/README.md's own maintenance text, added in the same PR — both state update-on-meaningful-change, the typo-only exemption, "state impact in PR," canonical-docs-win, no-secrets, and the basectl export-context validation commands. Two new copies of one policy are created together in this diff; CONTRIBUTING.md should link to .ai-context/README.md rather than restate its substance, or a future policy tightening (e.g. a new no-secrets exception) only gets applied to one copy and the two silently drift from each other starting from this PR's own merge.
| canonical documentation. Update the affected pages in the same meaningful PR; | ||
| for typo-only or internal changes with no contract impact, record no context | ||
| impact in the PR. Resolve disagreements by correcting this pack from its sources. | ||
| Do not copy credentials, local databases, private machine paths, personal records, |
There was a problem hiding this comment.
Cross-repo duplication, different wording: this Safety text ("Do not copy credentials, local databases, private machine paths, personal records, or transient logs") restates base's own .ai-context/README.md Safety section ("Do not put secrets, API keys, tokens, private local paths, private customer details, or personal notes") — same policy, independently hand-authored in different words in a second repo. basefoundry-dot-github has no shared .ai-context template (only LICENSE/README/profile), so this is a second hand-copied instance rather than a single source of truth. A future policy tightening (e.g. "no screenshots" or a new excluded-data category) must be hand-propagated to every repo's copy and will silently drift, exactly as the two independently-worded lists already have.
| compatibility. Use supported Bash and the documented development dependencies; | ||
| run timeout/process tests with non-terminal stdin. | ||
|
|
||
| Tracked work starts from an issue and a dedicated canonical worktree. Move its |
There was a problem hiding this comment.
Restates rather than links: "Tracked work starts from an issue and a dedicated canonical worktree. Move its Project item to In Progress before implementation and In Review when the PR opens... Ordinary PRs do not change VERSION. Releases must enter through scripts/release..." restates substance already fully stated in AGENTS.md's "Release Work" section and CONTRIBUTING.md's Project/worktree/good-first-issue workflow steps, rather than only linking to them (the "Sources" line at the bottom already cites both). A future change to the release guard or the Project-status workflow now needs updates in three places (AGENTS.md, CONTRIBUTING.md, and this file) to stay consistent, and a maintainer updating only the canonical doc could leave this summary stale without any signal.
| Sourcing stdlib is passive. Standalone consumers initialize through `base_init`; | ||
| `bin/base-bash` preloads stdlib, initializes once, sources the application, and | ||
| calls its `main`. Package-relative imports use `base_std_import` or the launcher's | ||
| import helper. Public functions use `base_<module>_...`; framework-owned state |
There was a problem hiding this comment.
Minor inaccuracy in a blanket naming-convention claim: "Public functions use base_<module>_..." is not 100% true — lib/bash/std/lib_std.sh exports base_init and base_require_version as public entry points, neither of which follows the module-prefixed base_std_... pattern. Spot-checking the other modules (arg/str/list/file/git/gh/cli/app/process), std is the only one with exceptions. Low severity since these are well-known top-level bootstrap functions documented elsewhere (README.md), but the blanket claim as written is technically inaccurate and could mislead someone writing new public API against this doc's stated convention.
Summary
base-bash-libs is discovered as a Base-managed project but cannot be exported without
.ai-context/. Add five curated Markdown pages covering Bash library modules, initialization/namespace contracts, standalone consumption, and validation/release boundaries, with a deliberate INDEX order and links to canonical sources. Contribution guidance defines when the pack must be updated.Issue
Fixes #581
Validation
basectl export-context --list-files, Markdown, and Zip exports passed from this issue worktree.git diff --cached --checkbefore commit andgit diff --checkpassed.bash tests/docs-contract.sh: passed.bash tests/community-contract.sh: passed.Docs Impact
Adds
.ai-context/README.md,INDEX.md,PROJECT.md,ARCHITECTURE.md, andWORKFLOWS.md; adds maintenance guidance inCONTRIBUTING.md. The pack supplies offline orientation while canonical documentation/code remain authoritative. It does not claim that source links are inlined by the exporter.Demo Impact
None. Existing examples and Beacon runtime behavior are unchanged.
API Impact
None. No public functions, manifest API entries, or runtime contracts change.
CI Impact
None. Existing workflows are unchanged. Local validation is documentation-focused; hosted checks provide the configured repository gates.
Security Notes
No runtime, dependency, privilege, or trust changes. The pack contains source summaries, not credentials or local runtime data.
Notes
No release version or CHANGELOG update: this adds repository orientation and repairs a test race, with no runtime behavior change. The optional Base scaffold enhancement is tracked separately in basefoundry/base#2627 and is not required to use this pack. After merge and checkout update, existing workspace export/sync jobs discover the directory automatically. This PR does not publish exports or change cloud synchronization.
CI regression repair
The macOS timeout-clock test incorrectly assumed that the child command writes its counter before an immediately failing clock stops the process group. Count external clock executions instead, excluding the capability probe, so the assertion directly verifies that infrastructure failures are not retried. The fixture uses Bash builtins with its restricted PATH. Production timeout and retry behavior is unchanged.
The four focused timeout/supervision tests passed, and the corrected no-retry regression passed ten consecutive runs. The full local
./tests/validate.shpassed: 712 BATS tests, 26 Project-intake tests, and all option, property, artifact, benchmark, integration, concurrency, quality, CI-policy, compatibility, release-invariant, and example checks. Both hosted Ubuntu 24.04 and macOS 15 validation jobs passed, including independent SPDX artifact verification and supported/unsupported Bash smoke tests. All hosted checks completed successfully on commit 82f12f0. This test-only correction has no public API or context-content impact.