docs: Guildhall design (guilds, skills, standards) + Ravenline mock org#5
Merged
Conversation
…dards Design doc for the practice layer: the conceptual model and vocabulary relating Skill-Exchange-style skills, crafts (skill bundles a muster calls for), gildi/guilds (the practice hub with people, process, and measurement faces), Soundcheck-style standards with trials, and visir procedure guides — plus how they connect to the shipped Cycle and Saga kinds. Layered per the brainstorm: an abstract, portable model first, then the Backstage mapping (typed Group for gildi, vocabularies for skills and crafts, Git-backed YAML standards via Tech-Insights-first, annotation- referenced visir docs, muster calls deferred to the Phase 4 store). No new custom kinds. A kennings display layer maps the canonical technical terms to per-instance lexicons (norse or plain), which also keeps parent-facing Ting surfaces on Tone-Guide-safe plain language. Grounded in fresh research on Spotify's premium Soundcheck and Skill Exchange plugins (exact upstream vocabulary captured in the doc). Vocabulary lands now — mechanics are Phase 6 (scorecards, profiles) and Phase 4 (calls) work. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…owship, visir grades Review feedback from Cervator untangled a conflation in the first draft: the gildi was carrying both the medieval fellowship role (guilds gather around crafts) and the cross-cutting-concern role (Safety applies to many things). This revision splits them. Aspect becomes the first-class cross-cutting concern in the full AOP sense and now holds the standards. Gildi becomes purely the fellowship (craft- or aspect-aligned), which is exactly why it maps to a typed Group. Skills become explicitly unowned shared vocabulary — crafts and aspects reference them, and pointing is not owning. The three-faces framing becomes the anatomy-of-a-practice constellation. Visir gains two grades per Cervator's steer: teaching visar are static material in /docs (TechDocs), while operational visar are parameterized templates in /runbooks rendered by a dedicated runbooks plugin (placeholders for environment details filled via URL parameters — a pre-existing plugin concept that slots in here). Thattr joins the kennings table as the norse skin for aspect. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…rms now open items Mobile-review feedback pass. Reflowed the whole doc to soft wrap (one line per paragraph) so display tools control word wrap instead of the ~100-column hard breaks fighting narrow screens. Thattr is rejected as the aspect kenning skin — it sound-collides with a rude Danish word. The norse skin for aspect is now an explicit open question with live candidates (thradr, hattr, sidr, grein), and a lexicon-review discipline note records the false-friend check as standing practice. The visir grade term split (Fraedi-as-lore vs plain docs vs adjectives only) also moves to open questions rather than being settled prematurely. Also fixed the stale two-sides/third-side counting in section 1 (the constellation has four pieces since the aspect rework) and clarified that operational visar differ from teaching visar by capability (placeholder insertion for copy-paste-accurate commands), not genre. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…inks, practice home repo Harvested from drafting the day-job presentation intro, which surfaced the first concrete answer to "what does a gildi actually do, and where does it work." New worked example: the paved-road loop. A gildi works out of a practice home repo holding the standard (trials in tiers), the paved road (reusable techniques such as CI pipeline template steps adopted with a one-line include), and the remediation visar every trial links to. Enrolling a Component, following a failing trial's remediation visir, and having the next pipeline run's facts flip the trial green closes the loop with no manual chasing — when the requirement, the tooling, and the measurement share one steward, the cheapest way to comply is the paved road. The community translation (Logistics gildi pre-stocking the first-aid-kit checklist) is included to keep the model dual-domain. Model additions that fell out: aspects ship both the bar and the paved road to clear it, trials declare remediation-visir refs (a failing check is always one click from the fix), and the aspect mapping row gains the practice-home-repo convention. Also swapped one lingering "load-bearing" phrasing per Cervator's wording feedback. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
…example A whole mock software org (Ravenline, a small parcel-logistics SaaS) paired with the practice-layer design doc as its running example — demo data now, fixtures for future practice-layer features later. The catalog half ingests with ZERO new code, demonstrating the design's no-new-custom-kinds claim: an org tree with two gildi-typed Groups (one aspect-aligned, one craft-aligned), six users, a software graph with aspect-enrollment and visir annotations, a release Cycle, a drive Cycle (the Soundcheck-Campaign analog), and a Saga narrated by a user. The non-catalog half freezes the design section-5 file shapes as plain YAML/markdown deliberately not ingested: skill/craft/aspect vocabularies, two standards (security measuring Components in three tiers, release-readiness measuring Cycles — the season-readiness twin), the security practice home repo with its paved-road pipeline template, and teaching vs operational (parameterized) visar showing the /docs-vs-/runbooks convention. The demo data tells the design's paved-road story: tracking-api at silver, carrier-gateway stuck at bronze with the dependency-scanning trial failing and a remediation doc whose entire instruction is the one-line template include. smoke-catalog now also asserts the Ravenline entities ingest at runtime (gildi Group typed, release Cycle with partOf/dependsOn relations, Saga owned by its skald and touching its Cycle) — 17 checks, all passing. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Run ID: 📒 Files selected for processing (1)
📝 WalkthroughSummary by CodeRabbit
WalkthroughAdds the Ravenline mock organization catalog seed, Guildhall practice-layer design and fixtures, operational documentation, reusable pipeline and runbook examples, and expanded catalog smoke validation. ChangesRavenline practice layer
Estimated code review effort: 3 (Moderate) | ~25 minutes Sequence Diagram(s)sequenceDiagram
participant AppConfig
participant Catalog
participant RavenlineFiles
participant SmokeCatalog
AppConfig->>Catalog: register Ravenline catalog locations
Catalog->>RavenlineFiles: ingest org.yaml, software.yaml, cycles.yaml
RavenlineFiles-->>Catalog: expose Ravenline entities and relationships
SmokeCatalog->>Catalog: poll and validate Ravenline entities
Catalog-->>SmokeCatalog: return entity kinds, types, and relations
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 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 `@docs/plans/2026-07-10-guilds-skills-standards-design.md`:
- Around line 118-119: Update the Vísir referrer list in the surrounding design
document to include Components and practice homes, matching the
component/aspect-scoped references allowed elsewhere and used by Ravenline
fixtures. Keep the existing referrer entries and scope unchanged while ensuring
future plugins recognize these valid annotations.
In `@examples/mock-org/repos/security-practice/docs/dependency-scanning.md`:
- Around line 13-15: Align remediation references with their trial scopes: in
examples/mock-org/repos/security-practice/docs/dependency-scanning.md lines
13-15, limit the guide to dependency-scanning remediation or add procedures for
vulnerability aging, security-contact declaration, and threat-model freshness;
in examples/mock-org/repos/security-practice/standard.yaml lines 24-37, replace
unrelated remediation paths with guides that directly resolve each silver and
gold trial.
In
`@examples/mock-org/repos/security-practice/runbooks/rotate-leaked-credential.md`:
- Around line 13-15: Update both fenced shell blocks in the credential rotation
runbook to declare the bash or sh language after the opening fence, including
the blocks containing the bao and kubectl commands, while leaving their command
contents unchanged.
- Around line 10-15: Update the credential replacement instructions to pass the
new secret through stdin rather than exposing it as a command-line argument,
following the read/printf and value=- pattern from the review. Add an
appropriate language identifier to the fenced shell command block so
markdownlint accepts it.
In `@examples/mock-org/repos/tracking-api/runbooks/queue-backlog.md`:
- Around line 11-13: Update the fenced shell command blocks in the queue-backlog
runbook to declare the bash language, including the blocks containing the
kubectl logs and scale commands, so each fence has a bash identifier.
In `@scripts/smoke-catalog.sh`:
- Around line 63-76: Bound the polling loop around the six byname lookups with
an overall deadline so the smoke test exits promptly when entities never appear
or the catalog is unavailable. Track elapsed time or an absolute deadline across
iterations, check it before each iteration, and preserve the existing success
condition and failure behavior once the deadline is reached.
🪄 Autofix (Beta)
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: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 7d85b575-d728-479d-815d-798c3e4db484
📒 Files selected for processing (19)
app-config.yamldocs/plans/2026-07-10-guilds-skills-standards-design.mdexamples/mock-org/README.mdexamples/mock-org/cycles.yamlexamples/mock-org/org.yamlexamples/mock-org/practice-layer/aspects.yamlexamples/mock-org/practice-layer/crafts.yamlexamples/mock-org/practice-layer/skills.yamlexamples/mock-org/practice-layer/standards/release-readiness.yamlexamples/mock-org/repos/handbook/docs/release-captain-guide.mdexamples/mock-org/repos/security-practice/docs/dependency-scanning.mdexamples/mock-org/repos/security-practice/pipeline-templates/dependency-scan.ymlexamples/mock-org/repos/security-practice/runbooks/rotate-leaked-credential.mdexamples/mock-org/repos/security-practice/standard.yamlexamples/mock-org/repos/tracking-api/docs/oncall-primer.mdexamples/mock-org/repos/tracking-api/runbooks/queue-backlog.mdexamples/mock-org/sagas/tracking-2026-2.mdexamples/mock-org/software.yamlscripts/smoke-catalog.sh
There was a problem hiding this comment.
Pull request overview
Adds a new “practice layer” conceptual design (guilds/gildi, skills, crafts, aspects, standards/trials, vísir) and a comprehensive “Ravenline” mock org dataset to demonstrate that the model can be represented using built-in Backstage kinds plus the existing Cycle/Saga custom kinds, with smoke-catalog extended to assert runtime ingestion.
Changes:
- Introduces a practice-layer design doc defining vocabulary and mapping to Backstage mechanics.
- Adds
examples/mock-org/Ravenline catalog entities plus non-ingested practice-layer fixtures (skills/crafts/aspects/standards, runbooks/docs, practice-home repo shapes). - Updates
app-config.yamlto ingest Ravenline catalog files and extendsscripts/smoke-catalog.shto validate Ravenline entities/relations.
Reviewed changes
Copilot reviewed 19 out of 19 changed files in this pull request and generated 7 comments.
Show a summary per file
| File | Description |
|---|---|
| scripts/smoke-catalog.sh | Extends smoke checks to include Ravenline entities/relations. |
| examples/mock-org/software.yaml | Ravenline software graph (Domain/System/Components/Resource) with practice annotations. |
| examples/mock-org/sagas/tracking-2026-2.md | Ravenline Saga narrative markdown body. |
| examples/mock-org/repos/tracking-api/runbooks/queue-backlog.md | Example parameterized operational vísir/runbook. |
| examples/mock-org/repos/tracking-api/docs/oncall-primer.md | Example static teaching vísir/doc. |
| examples/mock-org/repos/security-practice/standard.yaml | Example tiered security standard with trials/remediations. |
| examples/mock-org/repos/security-practice/runbooks/rotate-leaked-credential.md | Example parameterized remediation runbook. |
| examples/mock-org/repos/security-practice/pipeline-templates/dependency-scan.yml | Example paved-road pipeline template stub. |
| examples/mock-org/repos/security-practice/docs/dependency-scanning.md | Teaching doc for satisfying the dependency-scanning trial. |
| examples/mock-org/repos/handbook/docs/release-captain-guide.md | Teaching doc referenced by a craft (release-captain). |
| examples/mock-org/README.md | Explains Ravenline dataset scope and ingest-vs-waits table. |
| examples/mock-org/practice-layer/standards/release-readiness.yaml | Example Cycle-measuring standard fixture (not ingested). |
| examples/mock-org/practice-layer/skills.yaml | Skill vocabulary + mock user profile selections fixture (not ingested). |
| examples/mock-org/practice-layer/crafts.yaml | Craft vocabulary fixture referencing skills and teaching docs (not ingested). |
| examples/mock-org/practice-layer/aspects.yaml | Aspect vocabulary fixture referencing standards/practice home (not ingested). |
| examples/mock-org/org.yaml | Ravenline org tree, gildi Groups, and Users. |
| examples/mock-org/cycles.yaml | Ravenline Cycle/Saga entities and relations. |
| docs/plans/2026-07-10-guilds-skills-standards-design.md | New practice-layer design doc (vocabulary + mapping). |
| app-config.yaml | Adds Ravenline catalog locations (org/software/cycles) for ingestion. |
Comments suppressed due to low confidence (1)
scripts/smoke-catalog.sh:120
- The catalog error filter still only matches
mtl|cycle|saga. Now that the smoke includes Ravenline entities, errors that mention onlyravenline/tracking/gildicould be missed, reducing the usefulness of the diagnostic output on failure.
# Surface any catalog processing errors for the seed.
echo "--- catalog errors mentioning mtl/cycle/saga (if any) ---"
grep -iE "error|InputError|Unable to read" "$LOG" 2>/dev/null | grep -iE "mtl|cycle|saga" | tail -20 || true
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The system gets its proper name: the Guildhall (norse kenning skin Gildaskali, the historic guild-hall). "Practice layer" was the working name and kept reading as a verb — practicing — which is one ambiguity too many for a terminology design. The doc title, the kennings table (new guildhall row), the mock-org README, and the examples/mock-org vocabulary directory (practice-layer/ → guildhall/) all follow. Review fixes (CodeRabbit + Copilot, round 1): - Design doc section 5: teaching-visir referrer list now includes Components and practice homes, matching the Ravenline fixtures. - Per-trial remediation alignment: new security-contact.md and threat-modeling.md docs in the practice home; standard.yaml points each silver/gold trial at its own fix (the 30-day-vulns trial keeps dependency-scanning.md, which documents that clock). - rotate-leaked-credential runbook: the replacement secret now goes in via stdin (read -rs + value=-) instead of the command line — the security practice's own runbook should not leak into shell history. - bash language identifiers on all runbook fences (markdownlint MD040). - Copilot path findings: guildhall/*.yaml fixture paths are now file-relative (the ./repos/... refs did not resolve from inside the vocabulary tree), each file stating the convention. - smoke-catalog: wall-clock deadline bounds the poll loop worst case (six lookups x 5s curl timeout x 120 iterations was unbounded in practice), and the failure-diagnostic error grep now also matches the Ravenline seed terms. - Umbrella-design reference in the doc header spells the real realm path and notes it lives in the yggdrasil workspace, not this repo. Validated: make smoke-catalog 17/17 PASS, full ws test gate green. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
agent-refr
changed the title
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
examples/mock-org/org.yaml (1)
33-45: 🗄️ Data Integrity & Integration | 🟠 Major | ⚡ Quick winUse the canonical steward annotation namespace.
Line [42] uses
siconsaga.org/stewards, but the design contract indocs/plans/2026-07-10-guilds-skills-standards-design.mdLine [114] specifiessiliconsaga.org/*. Future plugins following the documented namespace will ignore this steward annotation.Proposed fix
- siconsaga.org/stewards: 'aspect:security' + siliconsaga.org/stewards: 'aspect:security'🤖 Prompt for 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. In `@examples/mock-org/org.yaml` around lines 33 - 45, Update the stewards annotation key in the security-gildi Group to use the canonical siliconsaga.org/stewards namespace, matching the documented siliconsaga.org/* contract while preserving its existing annotation value.
🤖 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 `@examples/mock-org/repos/security-practice/docs/security-contact.md`:
- Line 13: Update the documentation near the trial status guidance to remove the
claim that the trial flips green on the next catalog refresh. Describe that
behavior as planned or not yet implemented, while preserving the existing
instructions about identifying and contacting the owning security team.
In
`@examples/mock-org/repos/security-practice/runbooks/rotate-leaked-credential.md`:
- Around line 14-16: Validate NEW_CREDENTIAL after the read and before the bao
kv put command, rejecting empty values and prompting for a non-empty replacement
instead of storing a blank credential. Keep the existing unset NEW_CREDENTIAL
cleanup behavior for both accepted and rejected input.
- Around line 11-16: Update the runbook command rendering to validate service,
secret_path, cluster, and namespace against strict allowlists and shell-escape
each value before interpolation into bao or kubectl commands. Apply the same
protection to the restart command, while preserving the existing command
behavior for valid parameters.
---
Outside diff comments:
In `@examples/mock-org/org.yaml`:
- Around line 33-45: Update the stewards annotation key in the security-gildi
Group to use the canonical siliconsaga.org/stewards namespace, matching the
documented siliconsaga.org/* contract while preserving its existing annotation
value.
🪄 Autofix (Beta)
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: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: 01508ddb-352f-4f8a-9daf-a84e78e31e71
📒 Files selected for processing (15)
app-config.yamldocs/plans/2026-07-10-guilds-skills-standards-design.mdexamples/mock-org/README.mdexamples/mock-org/guildhall/aspects.yamlexamples/mock-org/guildhall/crafts.yamlexamples/mock-org/guildhall/skills.yamlexamples/mock-org/guildhall/standards/release-readiness.yamlexamples/mock-org/org.yamlexamples/mock-org/repos/handbook/docs/release-captain-guide.mdexamples/mock-org/repos/security-practice/docs/security-contact.mdexamples/mock-org/repos/security-practice/docs/threat-modeling.mdexamples/mock-org/repos/security-practice/runbooks/rotate-leaked-credential.mdexamples/mock-org/repos/security-practice/standard.yamlexamples/mock-org/repos/tracking-api/runbooks/queue-backlog.mdscripts/smoke-catalog.sh
ADR 0009 distills the durable decisions of this arc into the MADR set: the Guildhall name (practice-layer rejected for its verb reading), the craft-vs-aspect split, aspects holding standards and shipping the paved road, the no-new-kinds mapping, and the kennings display layer. The design doc stays the deep treatment — the ADR is the compact record. Review round 2 fixes (CodeRabbit): - security-contact.md no longer claims trials evaluate today — the flip-green behavior is described as shipping with the future scorecard plugin, consistent with the mock-org README's honesty line. - rotate-leaked-credential.md guards against storing a blank credential (read -rs accepts an empty line) and its header now states the render-time requirement the injection finding surfaced. - That requirement is promoted to the design doc's section 8 runbooks open question as a hard constraint: URL-sourced placeholder values must be allowlist-validated and shell-escaped before interpolation, so a crafted link can never turn a copied command into an injection. - Declined the outside-diff "siconsaga.org/stewards typo" finding: verified via git grep that both the working tree and the pushed commit read siliconsaga.org/stewards — the claim does not match the code. Also folds in a kennings note from review discussion: corporate lexicons can slot in house terms like Center of Excellence for gildi where the org already speaks them. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 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
`@examples/mock-org/repos/security-practice/runbooks/rotate-leaked-credential.md`:
- Around line 19-20: Update the credential storage step in the runbook so a
failed `bao kv put` command immediately aborts execution before `unset
NEW_CREDENTIAL` and the restart step. Preserve the existing successful storage
flow and ensure the command failure status is propagated.
- Line 17: Update the credential input command in the runbook to read the value
verbatim by enabling raw mode and disabling IFS trimming. Preserve silent input
and ensure leading/trailing whitespace and backslashes remain unchanged.
🪄 Autofix (Beta)
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: Organization UI
Review profile: ASSERTIVE
Plan: Pro
Run ID: b1377494-cb75-4b89-bc7e-f5ce9567eb80
📒 Files selected for processing (5)
docs/adrs/0009-guildhall-practice-model.mddocs/adrs/README.mddocs/plans/2026-07-10-guilds-skills-standards-design.mdexamples/mock-org/repos/security-practice/docs/security-contact.mdexamples/mock-org/repos/security-practice/runbooks/rotate-leaked-credential.md
…rt on failed store CR #5 review round 3 (CodeRabbit, both valid): IFS= read -r -s reads the replacement credential verbatim (plain read -rs still lets IFS trim leading/trailing whitespace), and a failed bao kv put now aborts the runbook before the unset and restart steps — the dangerous state is precisely "old credential revoked, no replacement stored," so falling through to the rollout restart would be the worst move. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Cervator
approved these changes
Jul 13, 2026
This was referenced Jul 14, 2026
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
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.
Summary
docs/plans/2026-07-10-guilds-skills-standards-design.md): terminology and conceptual model relating Skill-Exchange-style skills, crafts (demand-side skill bundles), gildi (fellowship Groups), aspects (cross-cutting concerns holding standards), Soundcheck-style standards with trials, and visir procedure guides — plus how they connect to the shippedCycle/Sagakinds. Grounded in fresh research on Spotify's premium Soundcheck and Skill Exchange plugins (their exact vocabulary is captured in §2).examples/mock-org/): the design's running example. The catalog half (org tree, two gildi-typed Groups — one aspect-aligned, one craft-aligned — software graph with enrollment/visir annotations, release + drive Cycles, a Saga) ingests with zero new code, demonstrating the design's no-new-custom-kinds claim. The non-catalog half freezes the §5 file shapes (skill/craft/aspect vocabularies, two tiered standards, parameterized runbooks vs static docs) as fixtures for the future Phase 6 plugins. Trial evaluation is NOT implemented — bronze/silver mentions in entity descriptions are demo narrative, as the seed README states.Test plan
ws test leidangr(fullmake cigate): config-check + lint + tsc + envelope suite + app/backend units — all green.make smoke-catalog: headless backend boot, real ingestion — 17/17 checks pass (MTL + Ravenline, kinds and relations).examples/mock-org/README.mdfor the demo story and the ingests-vs-waits table.Related