fix(handoff): close what stops a Hub agent working without the LearnStack tree - #4
Merged
Conversation
…tack tree Preparation for handing this repository to its own agents. Findings come from an autonomy audit; each was re-verified against the working tree here before being touched. **Three runtime defects an agent hits on day one.** - Both places that tell you how to start the API give a project path that does not exist. It is `src/Core/LearnStack.Hub.Api`, not `src/LearnStack.Hub.Api`, so `dotnet run` fails immediately. - The API cannot reach its database when started the documented way. The host never loads `.env`, so the connection string falls back to defaults. Both run blocks now export it the way `scripts/seed.sh` already does. - `.env.example` and `infra/compose/dev.yml` provision `HUB_POSTGRES_DB`; `HubFoundationRegistration` read `POSTGRES_DB_HUB`. It worked only because both sides defaulted to the same literal — the first time someone changed the database name, compose and the app would have disagreed silently. **Skills sent the agent to a checkout it is not supposed to need.** Eleven references across nine skills pointed at `../LearnStack/docs/...` or `../LearnStack/backend/src/...` for reading authority or source. Reading LearnStack does not require a clone — it requires a URL, which is the rule this repository already states for Markdown links. All are now absolute GitHub URLs. `../LearnStack` survives only where it is genuinely a shell path: `make dev`, the compose stack, the Keycloak realm files. The sharpest case was `wire-cross-cutting-foundation`, whose Step 1 still said "reproduce `../LearnStack/backend/src/LearnStack.SharedKernel/` folder-for-folder". That kernel shipped with P02c-1 and is on `main`; the skill is now about understanding what is there, which is what the owed SharedKernel reconciliation actually needs. **Skills taught rules the corpus has retired.** `add-integration-event` carried the "four HTTPS endpoints, a fifth needs an ADR" framing in four places and `standards-check` had it as a checklist box — ADR-0034 replaced the count with two invariants precisely because protecting it caused TLS private keys to be tunnelled through the entitlement payload. Two skills also described the link audit backwards, telling the agent to check that sibling-relative links "resolve locally" when CI now **fails** on them. **The freeze was unreachable from the entry point.** `start-task` Step 2 checked packet fit against the roadmap but never mentioned that P02c-2 and everything after it is frozen — so an agent asked to build the internal API would have been green-lit into it. Step 2 now checks the freeze first and stops. **`meta` claimed work it does not do.** Its only step is the Markdown link audit; the job name and CONTRIBUTING both advertised format verification, which runs in `backend`. Also: `HubBoundaryTests`' summary described a corpus drift the restructure already closed — Architecture 24 now spells the test `Hub_NeverStores_TenantData` and lists seven, so the KNOWN CORPUS DRIFT block is deleted rather than updated. `openapi-diff` moves off `if: false`, which actionlint rejects, to an unset repository variable. And the two skills the remaining packets need but nobody has written — `add-recurring-job` and `add-contract-test` — are registered in the deferred table instead of being discovered missing. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Reviewer's GuideAligns Hub repo docs, skills and runtime behaviour so agents can work without a sibling LearnStack checkout, fixes three runtime defects around Hub API startup and Postgres config, and clarifies contract/freeze rules and meta CI behaviour. Flow diagram for updated Hub API startup and Postgres configurationflowchart TD
A[Developer runs Hub API locally] --> B[Export .env in repo root using set -a; . ./.env; set +a]
B --> C[Set POSTGRES_HOST=localhost]
C --> D[Run dotnet project src/Core/LearnStack.Hub.Api]
D --> E[HubFoundationRegistration.ResolveConnectionString]
E --> F[Read POSTGRES_HOST, POSTGRES_PORT, HUB_POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD]
F --> G[Build Postgres connection string and connect]
Flow diagram for start-task Step 2 freeze and packet-fit logicflowchart TD
A[Agent runs start-task Step 2] --> B[Check CLAUDE.md state and roadmap freeze]
B --> C{Packet is P02c-2 or later?}
C -- Yes --> D[Say task is frozen and stop]
C -- No --> E[Confirm task belongs to current packet]
E --> F{Belongs to a later packet?}
F -- Yes --> G[Say so and stop; do not pull future work forward]
F -- No --> H[If LearnStack-side changes needed, flag cross-repo coordinated packet and follow two-PR protocol]
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (5)
🚧 Files skipped from review as they are similar to previous changes (1)
📝 WalkthroughWalkthroughThe changes align Hub guidance with canonical LearnStack references, update contract and task rules, correct local API and database setup instructions, enable variable-controlled OpenAPI diff checks, and update architecture, entitlement, and roadmap documentation. ChangesHub guidance and workflow alignment
Estimated code review effort: 2 (Simple) | ~15 minutes Possibly related PRs
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
There was a problem hiding this comment.
Hey - I've left some high level feedback:
- The absolute GitHub URLs for LearnStack docs and source are repeated across multiple skills and tests; consider centralizing the base URL (e.g., in a shared constant or a short "LearnStack links" section) to reduce the risk of future drift if the repo or branch structure changes.
- The
.envexport sequence for running the Hub API is now described in bothREADME.mdandlocal-dev-setup/SKILL.md; factoring this into a single canonical snippet or script (and referencing it from both places) would help avoid the two instructions diverging over time.
Prompt for AI Agents
Please address the comments from this code review:
## Overall Comments
- The absolute GitHub URLs for LearnStack docs and source are repeated across multiple skills and tests; consider centralizing the base URL (e.g., in a shared constant or a short "LearnStack links" section) to reduce the risk of future drift if the repo or branch structure changes.
- The `.env` export sequence for running the Hub API is now described in both `README.md` and `local-dev-setup/SKILL.md`; factoring this into a single canonical snippet or script (and referencing it from both places) would help avoid the two instructions diverging over time.Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 5
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.claude/skills/commit-and-pr/SKILL.md:
- Line 66: Update the cross-repo coordination guidance in the commit-and-PR
instructions to state the required sequence explicitly: merge the LearnStack ADR
PR first, open the Hub code PR, open the LearnStack code PR referencing the Hub
commit hash, then merge both code PRs together. Preserve the restriction
requiring explicit user permission before pushing to or merging in LearnStack.
In @.claude/skills/start-task/SKILL.md:
- Around line 46-55: Update the freeze-check instruction in Step 2 to explicitly
say “At the start of Step 2” instead of “Before anything else,” preserving the
required ordered document reading from Step 1 before evaluating the task’s
packet or freeze status.
In `@CONTRIBUTING.md`:
- Around line 11-12: Keep the meta status-check context consistent between
.github/workflows/ci.yml and the CONTRIBUTING.md entry: either update the
required-check configuration and documentation to use the emitted “meta
(markdown link audit)” name, or rename the workflow job to meta. Apply the same
choice everywhere so the required check matches the workflow output.
In `@README.md`:
- Line 68: Update the documented Hub API commands in README.md at line 68 and
infra/compose/README.md at line 27 to invoke the repository-required
~/.dotnet/dotnet executable instead of plain dotnet, preserving the existing
project arguments.
- Around line 64-67: Update the README API startup instructions around the
backend setup to select the .NET 10 SDK before running either API command. Add
the user-local .NET directory to PATH or invoke the dotnet executable through
~/.dotnet/dotnet, while preserving the existing environment-loading and
backend-directory steps.
🪄 Autofix
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 8542f7ab-f01c-4163-ae40-fd72d9a69a46
📒 Files selected for processing (19)
.claude/skills/README.md.claude/skills/add-feature-key/SKILL.md.claude/skills/add-integration-event/SKILL.md.claude/skills/code-review/SKILL.md.claude/skills/commit-and-pr/SKILL.md.claude/skills/implement-task/SKILL.md.claude/skills/local-dev-setup/SKILL.md.claude/skills/standards-check/SKILL.md.claude/skills/start-task/SKILL.md.claude/skills/update-glossary/SKILL.md.claude/skills/wire-cross-cutting-foundation/SKILL.md.claude/skills/write-adr/SKILL.md.github/workflows/ci.ymlCONTRIBUTING.mdREADME.mdbackend/src/Core/LearnStack.Hub.Infrastructure/Composition/HubFoundationRegistration.csbackend/tests/LearnStack.Hub.Tests.Architecture/HubBoundaryTests.csbackend/tests/LearnStack.Hub.Tests.Architecture/RepositoryLayoutTests.csinfra/compose/README.md
The autonomy audit that scoped the handoff PR flagged three items as
out-of-scope for it. They are corpus defects, not handoff gaps, so they
land here rather than in a follow-up nobody owns.
1. `caps.value` is a string on the wire. The worked example in
entitlement-projection.md carried `"value": 365` as a JSON number,
which `entitlement-v1.schema.json` rejects — the envelope declares
`"value": { "type": ["string", "null"] }` with
`additionalProperties: false`, and `ComplianceCapDto.Value` is
`string?`, so the serialiser cannot emit a number anyway. The
document's own contract test would have failed on its own example.
Corrected to `"365"` and stated as a rule, because the next numeric
cap will reach for the same shape.
2. The dependency map was missing `p4 → p5` and `p4 → p6`. Both P02c-5
and P02c-6 ship "Operator portal screens" sections that build on the
portal shell and its Operators/Audit modules; the prose said so, the
graph did not. A reader planning parallel work off the diagram would
have scheduled them concurrently.
3. P02c-4 was labelled "touches no LearnStack code" in two places while
its own Deliverables require editing
`../LearnStack/infra/keycloak/realms/learnstack-hub.json` — the
operator roles and the MFA-required browser flow — and describe it as
a coordinated cross-repo change. The file cannot be duplicated into
this repository because LearnStack's compose imports both realms at
first boot. P02c-4 now carries a row in "Hub waits on LearnStack" and
is counted with the coordinated packets, leaving P02c-2 as the only
fully Hub-local packet remaining.
The third is the failure mode this whole review keeps finding: a fact
was corrected where the work was being done and left stale in the index
that summarises it. A packet declared LearnStack-free is a packet whose
cross-repo edit nobody schedules.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…ation and .NET SDK usage
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Preparation for handing this repository to its own agents. An autonomy audit
asked one question — can a competent Hub agent work here without opening or
editing the LearnStack repository? — and this closes what it found. Every
finding was re-verified against the working tree before anything was touched.
Documentation and comments, plus one behavioural line (an env-var key).
Three runtime defects, day one
dotnet run --project src/LearnStack.Hub.Apisrc/Core/LearnStack.Hub.Api. Fails immediately, in both places that document it.envscripts/seed.shalready doesHUB_POSTGRES_DBvsPOSTGRES_DB_HUB.env.exampleanddev.ymlprovision one key,HubFoundationRegistrationread the other. It worked only because both defaulted tolearnstack_hub— the first rename would have desynced compose from the app silentlySkills sent the agent to a checkout it should not need
Eleven references across nine skills pointed at
../LearnStack/docs/...or../LearnStack/backend/src/...to read authority or source. ReadingLearnStack needs a URL, not a clone — which is the rule this repo already
states for Markdown links. All are absolute GitHub URLs now.
../LearnStacksurvives only where it is genuinely a shell path:
make dev, the composestack, the Keycloak realm files.
The sharpest case was
wire-cross-cutting-foundation, whose Step 1 still read:That kernel shipped with P02c-1 and is on
main. The skill is now aboutunderstanding what is there — which is what the owed SharedKernel
reconciliation actually needs.
Skills taught retired rules
add-integration-eventcarried "four HTTPS endpoints, a fifth needs anADR" in four places;
standards-checkhad it as a checklist box.ADR-0034
replaced the count with two invariants because protecting it caused TLS
private keys to be tunnelled through the entitlement payload.
sibling-relative links "resolve locally" when CI now fails on them.
The freeze was unreachable from the entry point
start-taskStep 2 checked packet fit against the roadmap and never mentionedthat P02c-2 and everything after it is frozen. An agent asked to "implement the
internal API" would have been green-lit straight into frozen work. Step 2 now
checks the freeze first and stops.
Smaller
metaadvertised format verification in its job name and in CONTRIBUTING; itsonly step is the link audit. Format verification runs in
backend.HubBoundaryTests' summary carried a KNOWN CORPUS DRIFT block for a drift therestructure closed — Architecture 24 now spells it
Hub_NeverStores_TenantDataand lists seven tests. Deleted rather than updated.
openapi-diffmoves offif: false, whichactionlintrejects(
[if-cond] constant expression), to an unset repository variable.add-recurring-jobandadd-contract-test— needed by P02c-5 / hub-billing andP02c-2, written by nobody — are registered in the deferred table rather than
discovered missing later.
Verification
actionlintclean. Every relative Markdown link in the changed files resolves.The C# edits are one env-var key plus comments; CI builds and runs the
Testcontainers suite.
Not in scope
The audit also flagged items that are LearnStack's to fix or that depend on
decisions not yet made — the entitlement
compliance.caps.valuetype divergence,the P02c-4 cross-repo realm edit, and the dependency-map edges into P02c-5/6.
Those are content decisions, not handoff blockers, and belong in their own PR.
🤖 Generated with Claude Code
Summary by Sourcery
Align Hub repository with autonomous usage by a Hub agent without requiring a local LearnStack checkout, and fix configuration and documentation mismatches found during that audit.
New Features:
Bug Fixes:
Enhancements:
Build:
CI:
Deployment:
Documentation:
Tests:
Chores:
Summary by CodeRabbit
Documentation
CI & Quality
Bug Fixes