Repository navigation
docs: add curated AI context and maintenance guidance - #82
codeforester wants to merge 1 commit into
Conversation
| 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 claim: no automated job exists.
"This pack is picked up automatically by workspace export jobs" is not backed by anything in the org. Checked base, base-workspace, base-demo, and this repo: the only mechanism that reads .ai-context/ is the manually-invoked basectl export-context CLI (base/cli/bash/commands/basectl/subcommands/export_context.sh). There's no scheduled workflow, cron, or CI job anywhere that scans .ai-context across projects — base's downstream-version-bumps.yml is an unrelated version-bump bot and doesn't apply here either.
A reader (human or AI agent) who trusts this line will assume the pack is kept fresh by some background process and never notice when it drifts from code, since nothing actually runs automatically.
| `scripts/verify-vendor`. Consumer packaging and artifact validation are owned by | ||
| this repository. Do not edit vendor files to fix application behavior. | ||
|
|
||
| Sources: [application](../lib/beacon.sh), [launcher](../bin/beacon), |
There was a problem hiding this comment.
Sources footer omits the doc that actually backs the trust-boundary claims above it.
Lines 12-15 make security-relevant claims (destination-reservation via exclusive mkdir, symlink/special-file rejection, "not a concurrent-filesystem sandbox"), but the Sources list only cites docs/lifecycle-and-automation.md and docs/framework-updates.md — neither covers this. The actual canonical doc is docs/bundle-format-and-trust-boundary.md, which isn't linked here at all.
Per INDEX.md's own rule ("canonical repository sources linked from each page take precedence when exact implementation or policy details matter"), a reader trying to verify the trust-boundary claim follows these links and finds nothing addressing it.
| 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.
New maintenance rule has no CI enforcement, and the one check it names can't catch drift.
Nothing in .github/workflows/*.yml or tests/validate.sh checks that .ai-context/ stays in sync with code, and git diff --check (cited here as part of "validate changes") only catches whitespace/conflict-marker errors — it can't detect a renamed command or a dead relative link inside the pack.
A future PR that changes bin/beacon's command surface or lib/beacon.sh's policy without touching .ai-context/ merges clean with zero signal. This repeats, unchanged, the explicit non-gate the Jun-2026 design spec (base/docs/superpowers/specs/2026-06-10-ai-context-pack-design.md) scoped out 4+ months ago ("starts as a human/agent workflow rule, not a hard CI gate").
| run `basectl setup base-bash-libs-demo` before testing; direct validation must | ||
| use the prepared interpreter or set `SPDX_VALIDATOR_PYTHON` accordingly. | ||
|
|
||
| Use an issue and a dedicated canonical worktree. This repository keeps its |
There was a problem hiding this comment.
Invents the term "canonical worktree" — not this repo's actual terminology.
CONTRIBUTING.md:20 and AGENTS.md both say "dedicated Git worktree" (one per PR, removed after merge) — there's no single "canonical" worktree concept here. An agent reading only this curated page could infer there's one authoritative worktree to reuse, rather than creating a fresh one per PR as the real workflow (CONTRIBUTING.md step 4/9) requires.
Suggestion: Use an issue and a dedicated Git worktree.
| workflow. Only a merged PR becomes Done. Framework upgrades and releases follow | ||
| their own pin, evidence, compatibility, and required-check contracts. | ||
|
|
||
| Sources: [contribution guide](../CONTRIBUTING.md), [agent guidance](../AGENTS.md), |
There was a problem hiding this comment.
Sources footer omits the doc that backs the preceding sentence.
Line 24 ("Framework upgrades and releases follow their own pin, evidence, compatibility, and required-check contracts") directly summarizes docs/framework-updates.md ("Framework compatibility and pin updates"), but that doc isn't among the four Sources listed (CONTRIBUTING, AGENTS, validate.sh, ci-required-checks.md). Someone needing the actual pin-update procedure follows the listed sources and finds none of them describe it.
| @@ -0,0 +1,11 @@ | |||
| # base-bash-libs-demo AI context index | |||
There was a problem hiding this comment.
Reuse: hand-copied pack structure, already inconsistent across sibling repos, no shared generator.
This 5-file shape (INDEX/ARCHITECTURE/PROJECT/WORKFLOWS/README) is nearly identical to base-bash-libs/.ai-context, but base/.ai-context uses 8 files (adds COMMANDS, DECISIONS, STATUS) and base-demo/.ai-context uses 3 differently-named files; base-cli/base-cli-demo have none at all. With no shared template/generator deriving this from base_manifest.yaml or canonical docs, each repo in this bus-factor-1 org hand-authors and hand-maintains overlapping prose that drifts independently — the one shared piece of tooling (basectl export-context) only concatenates whatever Markdown a human already wrote, it doesn't generate or validate it.
| 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.
Duplicates CONTRIBUTING.md's new maintenance-policy wording, introduced in this same PR.
This ("for typo-only or internal changes with no contract impact, record no context impact in the PR") and CONTRIBUTING.md:80-81 ("Typo-only and internal changes without behavioral or architectural impact usually need no context update") state the same exception in different words in two files added by the same commit. A future tightening of this exception risks being applied to only one copy, leaving them silently contradictory.
| run `basectl setup base-bash-libs-demo` before testing; direct validation must | ||
| use the prepared interpreter or set `SPDX_VALIDATOR_PYTHON` accordingly. | ||
|
|
||
| Use an issue and a dedicated canonical worktree. This repository keeps its |
There was a problem hiding this comment.
Simplification: restates the Project-status workflow rule that CONTRIBUTING.md and AGENTS.md already own verbatim.
"This repository keeps its Project item In Progress while a PR is open; it does not use In Review... Only a merged PR becomes Done" duplicates CONTRIBUTING.md:28-32 and AGENTS.md's workflow section. CONTRIBUTING.md:30 already flags this as a deliberate, revisitable choice — if it's ever revisited, the change now needs to land in three places instead of two, and this page is the one most likely to be missed.
| to `verify`. Do not silently delete an existing bundle to make collection pass. | ||
| Use [the tutorial](../docs/five-minute-tutorial.md) for expected output. | ||
|
|
||
| Development validation is `./tests/validate.sh`. The artifact checks require the |
There was a problem hiding this comment.
Simplification: restates CONTRIBUTING.md's SPDX-validator setup paragraph almost verbatim.
CONTRIBUTING.md:57-60 already documents "run setup before testing... or set SPDX_VALIDATOR_PYTHON"; these lines repeat it with slightly different phrasing. A future change to the SPDX setup flow (new env var, new setup command) can update one copy and miss the other — a second duplication pair in this same file, distinct from the Project-status one above.
| through a small application whose commands, input schema, redaction policy, and | ||
| messages remain application-owned. | ||
|
|
||
| Beacon uses a committed, verified framework bundle under `vendor/base-bash-libs`. |
There was a problem hiding this comment.
Simplification: duplicates vendor-pin/runtime-requirement content already in README.md and docs/why-base-bash-libs.md / docs/should-i-use-base-bash-libs.md.
"does not require Base, Docker, cloud credentials, or network access... framework pin... reproducible consumer baseline" restates facts the top-level README.md and the two linked docs already state. A future change to the vendor/pin story (e.g. a new runtime requirement) now needs to stay consistent across three or four places instead of two.
Summary
base-bash-libs-demo is discovered as a Base-managed project but cannot be exported without
.ai-context/. Add five curated Markdown pages covering Beacon consumer behavior, pinned vendoring, runtime workflow, and artifact validation, with a deliberate INDEX order and links to canonical sources. Contribution guidance defines when the pack must be updated.Issue
Fixes #81
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/validate.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.Notes
No release version or CHANGELOG update: this is repository orientation, 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.