Skip to content

Commit 6c7360d

Browse files
rismayrismay
committed
Sync design-system.docc from provisioned canonical bundle
1 parent 8669ac1 commit 6c7360d

File tree

6 files changed

+370
-8
lines changed

6 files changed

+370
-8
lines changed

‎design-system.docc/discord/design-system-discord-conventions.md‎

Lines changed: 28 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -70,6 +70,34 @@ Minimal protocol:
7070
- `DECISION:` for durable decisions.
7171
- `TODO:` for actionable follow-ups.
7272

73+
### Thread naming (operator spec)
74+
75+
Use a deterministic name that encodes priority, status, tags, and a short slug:
76+
77+
- Format: `🧵-pM.m-<statusEmoji>-<tagEmojis>-<short-slug>`
78+
79+
Examples:
80+
81+
- `🧵-p0.1-⛔️-🔐🔗-fix-ssh-auth`
82+
- `🧵-p0.2-🔵-🧯🌐-wrkstrm-app-missing-content`
83+
84+
Canonical metadata is stored in repo thread artifacts under `threads/<slug>/*.thread.clia.json` (including
85+
`priority`, `statusEmoji`, and `tagEmojis`).
86+
87+
### Thread lifecycle (Discord-native)
88+
89+
We use Discord’s own lifecycle terms as semantics:
90+
91+
- **Active**: objective is still in progress.
92+
- **Archived**: objective is finished (main mission complete).
93+
- **Locked**: objective is finished *and* all related subthreads are finished.
94+
95+
Operational notes:
96+
97+
- Archiving/locking is a UI hygiene move; the repo thread artifact remains the system of record.
98+
- If a thread is archived/locked but new work is discovered, create a continuation thread and link it from the
99+
thread events stream.
100+
73101
Promotion path (turn threads into durable knowledge):
74102

75103
- Stable rule/pattern → promote to `memory.docc/expertise/`.

‎design-system.docc/docc/agent-lineage-root-chains.md‎

Lines changed: 108 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,11 +1,111 @@
1-
# agent-lineage-root-chains
1+
# Agent lineage: root chains and domain boundaries
22

3-
@Metadata {
4-
@PageColor(gray)
3+
CLIA agents can be authored and resolved across multiple nested domains (repo, mono, submodules). The lineage system must be deterministic, domain-driven, and safe.
4+
5+
This page specifies how CLIA resolves agent triads across domains today, and proposes an extension for explicitly selecting a chain of "root" contexts for an agent.
6+
7+
## Goals
8+
9+
- Deterministic context resolution (no filesystem-order dependence).
10+
- Domain-driven design (DDD): a domain does not need to know about broader domains.
11+
- Most-local-wins merge behavior (for now).
12+
- Ability to intentionally compose root contexts for specific agents (future).
13+
14+
## Terms
15+
16+
- Domain root: a directory that may contain `.clia/agents/`.
17+
- Context: one layer in the resolution chain where a matching agent directory exists.
18+
- Default lineage chain: contexts discovered by walking containment upward from a working path.
19+
- Root chain injection (proposed): explicitly selected roots to include in an agent's lineage.
20+
21+
## Default lineage resolution (current)
22+
23+
Given a working path `P` (CLI `--path`, or cwd), resolve contexts as follows:
24+
25+
1. Walk ancestor directories from filesystem root to `P`.
26+
2. For each ancestor directory `A`, include context `.clia/agents/<slug>` if it exists.
27+
3. Also include submodule roots discovered via `.gitmodules`, but only submodules that *contain* `P`.
28+
4. Order contexts global -> local.
29+
5. Merge triads using "most local wins" (later contexts override earlier ones).
30+
31+
### Domain boundary rule
32+
33+
A submodule must not inherit from unrelated sibling submodules. Therefore, submodules discovered from `.gitmodules` are only eligible if:
34+
35+
- `P` is inside that submodule root (i.e. `P == submoduleRoot` or `P` has prefix `submoduleRoot/`).
36+
37+
This preserves domain-driven boundaries while still allowing a submodule to inherit from repo-level and mono-level roots that are in its containment chain.
38+
39+
### Determinism requirements
40+
41+
When multiple agent documents exist in a context directory, selection must be stable:
42+
43+
- Candidate `*.agent.triad.json` files must be sorted and selected deterministically.
44+
- No reliance on filesystem directory listing order.
45+
46+
## Merge semantics (current)
47+
48+
For a given slug and a resolved list of contexts ordered global -> local:
49+
50+
- Merge is deep (object fields merge recursively).
51+
- Conflict resolution: most-local-wins.
52+
53+
This is a pragmatic default. Inheritance-specific semantics (e.g. sealed fields, field-level strategies) can be introduced later.
54+
55+
## Proposed: explicit root chain injection
56+
57+
Some agents should be able to intentionally select a specific chain of roots (while still respecting domain boundaries). This is a schema-level feature request.
58+
59+
### Requirements
60+
61+
- Must be expressed in the definitive CLIA triad schema (not `extensions.*`).
62+
- Must not violate DDD boundaries.
63+
- Must preserve deterministic ordering.
64+
65+
### Proposed schema addition (AgentDoc)
66+
67+
Add a new field to `*.agent.triad.json`:
68+
69+
```json
70+
{
71+
"rootChain": {
72+
"mode": "default" | "explicit" | "hybrid",
73+
"roots": [
74+
{ "kind": "path", "path": "code/mono" }
75+
],
76+
"policy": {
77+
"enforceContainment": true
78+
}
79+
}
580
}
81+
```
82+
83+
- `mode: default` (or missing): use the default lineage chain.
84+
- `mode: explicit`: use only the explicitly specified roots (plus the agent's local context).
85+
- `mode: hybrid`: start from default chain and inject the specified roots.
86+
87+
### Containment enforcement
88+
89+
If `enforceContainment` is true, each injected root must be "reachable" from the agent's domain:
90+
91+
- It must be an ancestor of the working path `P`, or
92+
- It must be the containing submodule root of `P`.
93+
94+
Otherwise resolution fails with a validation error.
95+
96+
### Ordering
97+
98+
The final chain must remain ordered global -> local. Conflicts continue to resolve as most-local-wins.
99+
100+
### Recommended CLI support (future)
101+
102+
- `clia agents context --slug <slug> --path <path> --explain`
103+
- show default chain
104+
- show injected roots (if any)
105+
- show final chain and why each context was included
106+
107+
## Non-goals
6108

7-
> [!NOTE]
8-
> This article moved to **CLIA Design System (provisioned)**.
9-
>
10-
> New location (mono):
11-
> orgs/clia-org/provisioned/clia-design-system-0/clia-design-system.docc/articles/agent-lineage-root-chains.md
109+
- Field-level merge strategies ("sealed" fields, append-only lists, etc.).
110+
- Cross-domain imports that bypass containment.
111+
- Multiple `@TechnologyRoot` in a single DocC bundle.

‎design-system.docc/docc/directory-design-system-public-provisioned-private.md‎

Lines changed: 101 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,101 @@
1+
# Directory Design System: public vs provisioned vs private
2+
3+
This page establishes a **clear, non-overlapping directory taxonomy** for DocC and thread artifacts.
4+
5+
## 1) Public
6+
7+
**Meaning:** Content intended for broad, public consumption.
8+
9+
**Characteristics:**
10+
11+
- Published to GitHub Pages under a canonical public host.
12+
- Must follow public-safe writing rules (no secrets; avoid unstable references like commit SHAs).
13+
- Build/publish is automated by CI.
14+
15+
**Canonical sources (authoring):**
16+
17+
- mono: `code/mono/docc/public/host/github/<bundle>.docc/…`
18+
- todo3: `github/users/<user>/public/docc/pages/<user>.github.io/<site>.docc/…`
19+
- or `github/orgs/<org>/public/docc/pages/<org>.github.io/<site>.docc/…`
20+
21+
**Published output:**
22+
23+
- `https://<host>/<site>/documentation/<tech-root>/…`
24+
25+
## 2) Provisioned
26+
27+
**Meaning:** Shareable documentation for operators. **Tiered above public**, but below private.
28+
29+
**Key rule:** provisioned content **mirrors the directory structure** of public material, but may contain **different, richer content** (operator notes, deployment guidance, SRE/runbooks, internal diagrams that are still safe to share).
30+
31+
**Characteristics:**
32+
33+
- Intended to be published/shareable, but not necessarily to the canonical public hubs.
34+
- Deployed via tooling (e.g. `swift-docc-deploy deploy provisioned-share`) that generates a dedicated slug-hash Pages repo.
35+
- Uses a **repo-root redirect page** (`/index.html`) to support custom OpenGraph/Twitter previews.
36+
37+
**Canonical sources (authoring):**
38+
39+
- mono: `code/mono/provisioned/<slug>-<series>/<bundle>.docc/…`
40+
- example: `code/mono/provisioned/wrkstrm-design-system-0/wrkstrm-design-system.docc/`
41+
- example: `code/mono/provisioned/git-design-system-0/git-design-system.docc/`
42+
43+
**Generated deploy repos (tool output):**
44+
45+
- `https://github.com/<owner>/<slug>-<hash>`
46+
- `https://<owner>.github.io/<slug>-<hash>/` (Pages root)
47+
48+
**Redirect rule (critical):**
49+
50+
- The redirect target must be discovered from the built output (e.g. `_site/index/index.json`),
51+
not guessed from the `.docc` directory name.
52+
53+
## 3) Private
54+
55+
**Meaning:** Internal-only artifacts and working state.
56+
57+
**Characteristics:**
58+
59+
- Not published to GitHub Pages.
60+
- May include internal context, operational details, and evolving notes.
61+
- Often includes canonical event/state logs that can generate mirrors.
62+
63+
**Canonical sources (examples):**
64+
65+
- todo3 thread data (canonical): `.clia/threads/private/<threadId>/…`
66+
- thread mirrors (generated): `.clia/threads/private/<threadId>.docc/…`
67+
- local-only DocC bundles: `docc/private/host/local/<bundle>.docc/…` (repo-specific)
68+
69+
## Mirror mapping (structure only)
70+
71+
Provisioned mirrors the **shape** of public so people can find things predictably, but uses a different tier root.
72+
73+
Canonical mapping (conceptual):
74+
75+
- public: `public/docc/pages/<host>.github.io/<site>.docc/...`
76+
- provisioned: `provisioned/docc/pages/<host>.github.io/<site>.docc/...`
77+
78+
Constraints:
79+
80+
- Same `<host>.github.io` and `<site>` coordinates (structure mirror).
81+
- Content may differ (tiered docs).
82+
- Public must not depend on provisioned.
83+
- Provisioned may link out to public.
84+
85+
## Provisioned publish requirements (docc-deploy)
86+
87+
Provisioned publishing is defined by tooling behavior (currently `swift-docc-deploy deploy provisioned-share`):
88+
89+
- Generates a **repo-root** `/index.html` for custom OpenGraph/Twitter previews, then redirects into DocC.
90+
- Uses a **slug-hash repo** pattern (`<slug>-<hash>`) for easy sharing.
91+
- Redirect target must be discovered from built output (e.g. `_site/index/index.json`), not guessed.
92+
93+
## Non-overlap rule
94+
95+
A directory must belong to **exactly one** of:
96+
97+
- public
98+
- provisioned
99+
- private
100+
101+
If it is unclear: default to **private** until explicitly promoted.

‎design-system.docc/docc/docc-design-system-checklists.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -49,3 +49,121 @@
4949
- Verify the root URL is `/documentation/<bundle>/` (avoid `/documentation/documentation`).
5050
- Destructive actions happen last: move files first, build the new product, test it, add tests when
5151
possible, then remove legacy files.
52+
53+
## Auto Mode Safe Space Protocol (S0)
54+
55+
Use Git worktrees + explicit guardrails to create a safe, parallel workspace where agents can work autonomously without colliding with each other (or with `main`).
56+
57+
### Guardrails (required)
58+
59+
Before any autonomous work begins, make the boundaries explicit:
60+
61+
- **Scope:** what this agent/task may touch (repo(s), services, envs).
62+
- **Blast radius cap:** canary %, region scope, rate limits.
63+
- **Kill switch:** who can stop auto mode globally and how to stop a single agent/task.
64+
- **Hard prohibitions:** actions auto mode must not take without explicit authorization.
65+
- **Reversibility:** every action must have an explicit rollback.
66+
67+
### Naming (required)
68+
69+
- Worktree dir: `../wt-INC<id>-<short>`
70+
- Branch: `inc/INC<id>/<short>-<owner>`
71+
72+
Example:
73+
74+
- `../wt-INC1471-mitigate-queue`
75+
- `inc/INC1471/mitigate-queue-rismay`
76+
77+
### Create the parallel world (recommended)
78+
79+
Create the worktree and its branch in one step:
80+
81+
```bash
82+
git worktree add ../wt-INC1471-mitigate-queue -b inc/INC1471/mitigate-queue-rismay
83+
cd ../wt-INC1471-mitigate-queue
84+
```
85+
86+
### Operating rules
87+
88+
- 1 branch ↔ 1 worktree during the incident (don’t reuse a branch across worktrees).
89+
- Don’t do incident work directly on `main` (unless explicitly approved by the IC).
90+
- Commit small and early; push early so another responder can take over if needed.
91+
- One PR per task/worktree. If scope changes, spawn a new worktree.
92+
93+
### Autonomy rules
94+
95+
- Agents can propose changes freely (commits/PRs) within the declared scope.
96+
- Agents can run local checks (lint/tests) and prepare rollbacks.
97+
- Agents should only *execute* changes that fall into pre-approved action classes for auto mode.
98+
99+
### Discord execution lanes (current)
100+
101+
When using Discord lanes for autonomous work, standardize names so automation can safely follow renames:
102+
103+
- Workspace channel: `🏎️<badge>-auto-<slug>`
104+
- Aggregator channel: `🏎️🟡-auto-control`
105+
106+
Badges:
107+
108+
- 🟡 pending
109+
- 🔵 working
110+
- 🟢 complete
111+
- 🔴 blocked
112+
113+
### “Parallel world” comms (post on task claim)
114+
115+
Every autonomous task claim should include:
116+
117+
- **Worktree:** name/path
118+
- **Branch:** full branch name
119+
- **Goal:** 1 sentence
120+
- **Expected impact:** 1 sentence
121+
- **Signals watched:** which probes/SLOs determine success/failure
122+
- **Rollback:** 1 sentence
123+
124+
### Audit trail (required)
125+
126+
- Prefer commits + PR links over copy/pasted diffs.
127+
- Keep a short incident/autonomy timeline with key decisions + links.
128+
129+
### Build breakage quick-fix protocol (required; timeboxed)
130+
131+
If a turn encounters a build/install failure that prevents normal work, attempt **quick fixes first**,
132+
then escalate and pause automation.
133+
134+
**Timebox:** 5–10 minutes maximum. If not resolved by then, treat as an SRE incident.
135+
136+
Quick fixes (try in order):
137+
138+
1) Re-run with a clean-ish state
139+
- `swift package resolve`
140+
- re-run the failing command (capture full stderr)
141+
2) Clear local build artifacts
142+
- delete the affected package’s `.build/`
143+
3) Resolve SwiftPM identity/duplicate-target collisions
144+
- ensure the same dependency isn’t being pulled via both local + remote identities
145+
4) Reinstall critical tools
146+
- `swift-installer cli --package-path <clia-agent-cli> --product clia --configuration release`
147+
5) Resources warnings → build errors
148+
- ensure resources are explicitly declared in `Package.swift` (or excluded) for the failing target
149+
150+
If quick fixes fail:
151+
152+
- Set `turnOperationMode` → `paused` in `<repoRoot>/.clia/workspace.clia.json`
153+
- Post `status: blocked` in the workspace auto channel
154+
- Create an SRE incident thread in `#🛡️📦🟢-sre-incidents` with:
155+
- failing command
156+
- error snippet
157+
- scope (which org/workspace)
158+
- last known good / suspected change
159+
- rollback suggestion
160+
- Notify the operator (via `.clia/profiles/operators/...`) with a link to the thread
161+
162+
### Cleanup
163+
164+
After merge (or when abandoning a task):
165+
166+
```bash
167+
cd <main-repo>
168+
git worktree remove ../wt-INC1471-mitigate-queue
169+
```

‎design-system.docc/docc/docc-design-system-published-websites.md‎

Lines changed: 14 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -42,6 +42,20 @@ When authoring pages that ship to GitHub Pages (user-facing):
4242
- **Do not use timestamps with seconds** (or fractional seconds). Prefer a date (YYYY-MM-DD) or a human month/week label.
4343

4444

45+
### Root redirect page (custom previews)
46+
47+
DocC’s static output lands under `/documentation/<tech-root>/…`. If you want **custom OpenGraph/Twitter previews** (Discord unfurl) you need a repo-root landing page (usually `/index.html`) that:
48+
49+
- sets OG meta tags (title/description/image), and
50+
- redirects to the DocC landing route.
51+
52+
This is why `swift-docc-deploy` generates a root redirect page when deploying provisioned shares.
53+
54+
Important:
55+
- The redirect target must match the **actual emitted tech-root**.
56+
- Do **not** assume the tech-root is `index` just because the catalog folder is `index.docc`.
57+
- The robust way is: after `docc convert`, read `_site/index/index.json` (or `metadata.json`) and redirect to the discovered `/documentation/<tech-root>/`.
58+
4559
### Tooling notes
4660

4761
- macOS: use `xcrun docc` (DocC ships inside Xcode, not on PATH by default).

0 commit comments

Comments
 (0)