business-context-os

LLM wiki kit

First committed by walm00

Published in walm00/business-context-os. Publisher page

22 GitHub starsUpdated 2026-05-15

What it is

CLEAR Context OS is the maintenance layer your second brain never had: ownership boundaries enforced mechanically, staleness surfaced on a schedule, drift propagated across linked docs, a dispatcher that learns from your clicks. One source of truth per topic. Searchable. Task-aware.

— the description by walm00

AutoGineer overview, from the brain’s own files

CLEAR Context OS is a framework designed to solve the problem of silent context degradation in AI agents. By implementing a structured methodology called CLEAR (Contextual Ownership, Linking, Elimination, Alignment, Refinement), it provides a maintenance layer that manages knowledge through automated scheduling, ownership enforcement, and drift detection. It organizes information into specific zones—such as canonical data, wiki-based derivatives, and verbatim evidence—ensuring that agents always operate on the most accurate, source-of-truth-ranked information. The system includes a dispatcher for scheduled maintenance, a local dashboard for monitoring, and integration with Claude Code to facilitate onboarding and task-aware context retrieval.

How it works

Memory model: LLM wiki

AutoGineer overview, from the brain’s own files

The system organizes information into a folder hierarchy where the path itself acts as a trust signal for the LLM. It uses a dispatcher to run scheduled maintenance jobs that check for staleness, propagate updates across linked documents, and audit content health. New information is ingested through a routing process that places content into specific zones: canonical data for facts, wiki pages for operational knowledge, and collections for legal evidence. The system learns from user interactions to suggest fixes and uses frontmatter metadata to allow agents to filter and retrieve information efficiently without full-text scanning.

Folders
Folder	Role	Files
.claude	agent-config	193
.github	agent-config	6
docs	docs	68

The agent reads

docs/_bcos-framework/guides/folder-conventions.md evidence: CLAUDE.md
docs/_inbox/ evidence: README.md

The agent writes

docs/_inbox/ evidence: CLAUDE.md

Requirements

Works with: Claude Code, OpenCode

Set it up

This brain runs code automatically: 5 hooks (claude-code), 1 script. Review .claude/settings.json, install.sh before opening the folder in Claude Code. No step below turns a hook on for you.
- .claude/settings.json: bash "$CLAUDE_PROJECT_DIR/.claude/hooks/auto_save_session.sh"
- .claude/settings.json: bash "$CLAUDE_PROJECT_DIR/.claude/hooks/precompact_save.sh"
- .claude/settings.json: "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_frontmatter_check.py"
- .claude/settings.json: "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_frontmatter_check.py"
- .claude/settings.json: "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_commit_context_check.py"
- install.sh: sh install.sh

Clone the repository at the commit AutoGineer scanned:

git clone https://github.com/walm00/business-context-os.git && cd business-context-os && git checkout 463568372f31f24fa6c01121c38f989845ca7c84

Claude Code reads CLAUDE.md from this folder automatically.
cd business-context-os && claude
AutoGineer scanned these files at commit 4635683.
First committed by walm00. Published in walm00/business-context-os. Licence: MIT License.

Usage

AutoGineer overview, from the brain’s own files

Automating the maintenance of project documentation and SOPs.
Providing AI agents with a reliable, freshness-aware knowledge base.
Managing ownership boundaries across large, multi-topic documentation sets.
Syncing and auditing context across linked documents to prevent drift.
Generating daily digests of system health and pending maintenance tasks.

“Install BCOS from https://github.com/walm00/business-context-os and walk me through onboarding.”: Claude clones the repository, sets up the environment, and guides the user through an interactive onboarding process to configure the context architecture.
“/context bundle market-report:write”: The agent retrieves a curated, freshness-aware package of context specifically relevant to writing a market report.
“Run the audit twice a week.”: The dispatcher updates the maintenance schedule to perform an audit of the knowledge base on a bi-weekly cadence.
“/wiki run https://stripe.com/docs/api”: The system fetches the URL, summarizes the content, and creates a cited wiki entry within the knowledge base.

Documentation by walm00

<h1 align="center">CLEAR Context OS</h1> Knowledge that maintains itself — so your AI doesn't act on what was true last month. <a href="#install">Install</a>  ·  <a href="#what-it-does">What it does</a>  ·  <a href="#the-wiki-zone">Wiki zone</a>  ·  <a href="#what-ships">What ships</a>  ·  <a href="docs/_bcos-framework/guides/getting-started.md">Getting Started</a> <img src="https://img.shields.io/badge/claude_code-ready-blueviolet" alt="Claude Code"> <img src="https://img.shields.io/badge/methodology-CLEAR-green" alt="CLEAR Methodology"> <img src="https://img.shields.io/badge/install-one_command-success" alt="One-command install"> <img src="https://img.shields.io/badge/skills-17-blue" alt="17 skills"> <img src="https://img.shields.io/badge/maintenance_jobs-12-orange" alt="12 maintenance jobs"> <img src="https://img.shields.io/badge/license-MIT-lightgrey" alt="MIT">

Your AI had perfect context — two weeks ago. Then your strategy shifted, three meetings redefined priorities, and the docs you wrote on Monday are wrong by Friday. CLEAR Context OS is the maintenance layer your second brain never had: ownership boundaries enforced mechanically, staleness surfaced on a schedule, drift propagated across linked docs, a dispatcher that learns from your clicks. One source of truth per topic. Searchable. Task-aware. Never silently stale.

Install

Easiest — let Claude do it. Open Claude Code in any directory and paste:

"Install BCOS from https://github.com/walm00/business-context-os and walk me through onboarding."

Claude clones the repo, picks the right install path for your platform (Windows/macOS/Linux), runs setup, and steps straight into onboarding. No prereq checks to debug — if something's missing, Claude resolves it interactively.

Or manually, two commands:

curl -fsSL https://raw.githubusercontent.com/walm00/business-context-os/main/install.sh -o /tmp/bcos-install.sh
bash /tmp/bcos-install.sh

(Requires bash, curl, and tar on PATH — fine on macOS/Linux and on Windows under WSL or Git Bash. Two steps instead of a single bash <(curl …) pipe so Claude Code's permission gate auto-approves both commands — you don't need to drop out to a terminal.)

Drop anything you already have — SOPs, brand docs, meeting notes, exports — into docs/_inbox/ (skip if you're starting fresh). Then open Claude Code in that repo and say:

"Launch BCOS onboarding."

That's the only prompt you need. Onboarding inspects your inbox, scans the rest of the repo, asks one Q&A round, and proposes the architecture for review. Works the same whether the repo is fresh or already full of context.

From zero to running

  INSTALL  →  DISCOVER  →  ALIGN  →  SCHEDULE  →  RUNNING

#	Step	What happens
1	Install	One bash line drops the framework into any repo
2	Discover	Claude scans your repo + any MCP you've connected (Drive, Notion, Slack, Gmail, your CRM — whatever's wired in) for existing context, plus anything you've dropped into `docs/_inbox/`
3	Align	One Q&A round — project type, key sources, ownership boundaries. Architecture drafted for your review
4	Schedule	Pick maintenance cadence in plain English: "audit twice a week", "dispatcher at 08:30", "deep daydream off"
5	Running	Daily digest. Local dashboard. `/context bundle <task>` ready. Context compounds from here — the system maintains itself.

Simple, guided, automatic. Claude walks you through each step — you review, you decide. Nothing deleted along the way — originals preserved or archived, never silently overwritten.

What it does

Stops context rot in three ways:

	What it does
Organize	Every doc declares what it owns. CLEAR boundaries prevent the same fact living in 5 places.
Maintain	Scheduled jobs check freshness, surface stale docs, propagate updates across linked content.
Use	`/context search` and `/context bundle <task>` give Claude curated, freshness-aware, source-of-truth-ranked context for the job at hand.

The folder tells the LLM what to trust. Claude reads the path before the content: docs/*.md = canonical, _planned/ = not yet real, _archive/ = history, _inbox/ = unprocessed, _collections/ = verbatim evidence, _wiki/ = explanatory. The hierarchy is the trust signal — fewer tokens spent re-deciding, no chance of treating an archived draft as today's truth.

docs/
├── *.md                  ← canonical data points (one source of truth per topic)
├── document-index.md     ← auto-generated TOC
├── current-state.md      ← what's true right now + what changed recently
├── table-of-context.md   ← high-level cluster map for orientation
├── _inbox/               ← drop zone — Claude triages on demand
├── _planned/             ← polished ideas, not yet real
├── _archive/             ← superseded — kept, not deleted
├── _collections/         ← verbatim evidence (invoices, contracts, transcripts)
│   └── <type>/_manifest.md   (each collection has a manifest)
├── _wiki/                ← derivative knowledge (how-tos, source summaries)
│   ├── pages/            ← user-authored explainers
│   ├── source-summary/   ← external captures with citation banners
│   ├── raw/              ← original artifacts (PDFs, HTML)
│   └── queue.md          ← URLs awaiting fetch
└── _bcos-framework/      ← framework docs — never user content
    ├── architecture/     ← 12 zone + system architecture docs
    ├── methodology/      ← 5 CLEAR + ownership + standards docs
    ├── patterns/         ← 8 project-type starting templates
    └── templates/        ← 15 frontmatter / schema / starter files

The wiki zone

Inspired by Karpathy's LLM Wiki approach — give the LLM a wiki of your knowledge, the way you'd brief a smart new hire.

Save anything to the wiki, from anywhere:

/wiki run https://stripe.com/docs/api          ← fetch a URL, summarize, cite
/wiki create from /Users/me/Downloads/spec.pdf ← extract a PDF, link to the binary
/wiki promote docs/_inbox/meeting-notes.md     ← turn an inbox capture into a wiki page

The wiki holds how-tos, runbooks, glossaries, source summaries, post-mortems, decision logs — derivative knowledge that explains and supports your canonical data points. Every page cites what it builds on. Stale pages surface automatically when their sources advance.

Wiki content is searchable alongside the rest of your context:

/context search "stripe billing"       ← cross-zone search, ranked by source-of-truth
/context bundle market-report:write    ← curated bundle for a specific task

The dashboard

A local cockpit at http://127.0.0.1:8091 that shows your system at a glance — no third-party services, no telemetry, no logins.

Image: BCOS dashboard cockpit — knowledge system status, things waiting on you, maintenance routine

python .claude/scripts/bcos-dashboard/run.py

Surface	What you see
Cockpit	One-line status (healthy / N waiting / heads-up). Per-job dot strip for every maintenance job (core BCOS + wiki zone).
Update	"Run full sync" button → `update.py` + CLAUDE.md drift review + auto-commit + push, with a live log drawer.
Schedules (`/settings/schedules`)	Per-job preset buttons (`daily`, `mon_wed_fri`, `weekly_mon`, `off`) + the global auto-commit toggle + auto-fix whitelist. Saves directly to `schedule-config.json`.
Run history (`/settings/runs`)	Last 20 dispatcher runs with filter chips (job / verdict / trigger).
File health (`/settings/files`)	Frontmatter / cross-reference / staleness findings with one-click fixes.

The dashboard is read-mostly: data flows from the dispatcher's diary, the schedule config, and the canonical context index. Writes (mark-done, schedule preset, auto-commit toggle, file fix) go through dedicated POST endpoints.

Requirements

Claude Code (desktop app, CLI, or web)
Python 3.8+ on PATH
bash (default macOS bash 3.2 is fine)

Updating

python .claude/scripts/update.py

Refreshes framework files only — skills, hooks, scripts, templates. Your docs/ and .private/ are never touched.

Maintenance

One scheduled task per repo. The dispatcher reads schedule-config.json, runs the jobs due today, writes one consolidated digest at docs/_inbox/daily-digest.md, and surfaces findings as one-click cards in the dashboard.

Image: BCOS maintenance schedule dispatcher — daily, weekly, monthly jobs flowing into the daily digest and dashboard cards

You can tune any of it in plain English:

"Run the audit twice a week." · "Move dispatcher to 08:30." · "Turn off deep daydream."

The system learns from your clicks. After three consistent uses of the same fix, the dashboard pre-selects it as a "✨ suggested" action — you accept or reject. Reversals trigger an automatic safety brake.

CLEAR — the methodology

Five principles, one rule each:

C — Contextual Ownership · one document owns each topic. No duplicates.
L — Linking · reference sources; don't copy them.
E — Elimination · consolidate; don't keep two versions.
A — Alignment · context that doesn't support decisions doesn't belong.
R — Refinement · structured maintenance, not ad-hoc fixes.

The whole framework is the mechanical implementation of these five rules.

What ships

Everything below installs as one repo drop-in. No third-party services, no logins, no telemetry — all state lives in your .claude/ and docs/ folders.

Layer	Count	Examples
Skills (chat-invokable via slash command)	17	`clear-planner` · `bcos-wiki` · `context-routing` · `context-audit` · `context-ingest` · `daydream` · `learning` · `schedule-tune` · `lessons-consolidate` · `ecosystem-manager`
Sub-agents (delegated bounded tasks)	3	`wiki-fetch` · `explore` · plus one optional
Scripts (mechanical Python)	46	`lifecycle_sweep` · `run_wiki_` (5) · `cmd_wiki_` (7) · `auto_fix_audit` · `bcos_inventory` · `digest_sidecar` · `record_resolution`
Hooks (auto-validation on edit)	4	post-edit frontmatter check · post-commit context check · pre-compact save · auto-save session
Maintenance jobs (scheduled, one dispatcher)	12	`index-health` · `audit-inbox` · `daydream-lessons` · `daydream-deep` · `architecture-review` · `auto-fix-audit` · `lifecycle-sweep` · `wiki-stale-propagation` · `wiki-source-refresh` · `wiki-graveyard` · `wiki-coverage-audit` · `wiki-canonical-drift`
Auto-fix IDs (silent dispatcher fixes)	12	`missing-last-updated` · `eof-newline` · `frontmatter-field-order` · `wiki-mark-queue-ingested` · `wiki-archive-expired-post-mortem`
Architecture docs	12	`wiki-zone.md` · `lifecycle-routing.md` · `typed-events.md` · `context-zones.md` · `content-routing.md` · `wiki-headless-scripts.md`
Methodology docs	5	CLEAR principles · context architecture · decision framework · document standards · ownership specification
Project patterns (starting templates by project type)	8	client-project · gtm · marketing · operational · product-development · product-service · internal-tool-app · internal-tool-automation
Templates (frontmatter, schema, starters)	15	data-point · cluster · current-state · table-of-context · wiki-schema · wiki-config · session-diary-starter

Every script and skill is documented at the source. Every job has a reference doc under .claude/skills/schedule-dispatcher/references/job-*.md. Every typed-event finding maps to a renderer in the dashboard cockpit. Adding a new check means dropping a cmd_*.py or run_*.py, registering it in one map, and the dashboard picks it up.

Contributing

Contributions welcome — open an issue or submit a PR targeting the dev branch. CI runs frontmatter, reference, and ecosystem-integration checks on every PR.

The fastest contribution path is lessons learned. As you use the system it captures insights; if you find one universal, contribute it back.

Origin

Built by Guntis Coders after two years of operating context systems in production. The CLEAR methodology emerged from a practical problem: AI context degrades silently, and no amount of one-time documentation prevents it. The solution required a system — ownership boundaries, automated maintenance, self-learning, and structured reflection.

Background: What is the Table of Contexts and why does it matter.

License

MIT

docs/_bcos-framework/methodology/document-standards.md

Document Standards

The minimum quality bar for every document in your context architecture.

What Counts as a "Document"

CLEAR Context OS manages any document that represents organizational knowledge. Not just brand or strategy -- anything your team needs to stay aligned on.

Document Types

Type	What It Is	Examples
context	Business knowledge with clear ownership	Company identity, value proposition, investor narrative, competitive positioning, team structure, market context
process	How something is done (SOPs, workflows)	Employee onboarding, sales handoff, content approval, board reporting, vendor evaluation, release process
policy	Rules and decisions that govern behavior	Data handling, pricing rules, expense approval, hiring criteria, brand usage, IP protection
reference	Lookup information that rarely changes	Glossary, tool inventory, vendor contacts, org chart, key metrics definitions, tech stack
playbook	Decision guides for recurring situations	Crisis comms, fundraising, product launch, competitive response, market entry, M&A integration
wiki	Explanatory or source-summary page in `docs/_wiki/`	How-to pages, glossaries, decision logs, post-mortems, source summaries

All types follow the same metadata standard and quality bar. The ownership specification (DOMAIN, EXCLUSIVELY_OWNS, etc.) applies to all of them -- a process document needs clear boundaries just as much as a brand guide does.

type: wiki documents are governed by the wiki-zone extension, not the normal flat active-doc model. Use docs/_bcos-framework/architecture/wiki-zone.md and docs/_wiki/.schema.yml for page-type-specific rules.

Metadata Standard (YAML Frontmatter)

Every managed document MUST have a YAML frontmatter header. This is the machine-readable metadata that enables auditing, tracking, and discovery.

Required Fields

---
name: "Document Name"
type: context                   # context | process | policy | reference | playbook | wiki
cluster: "Parent Cluster"       # Which cluster this belongs to
version: "1.0.0"               # Semantic versioning: major.minor.patch
status: active                  # draft | active | under-review | archived
created: "2026-04-05"          # ISO date, set once, NEVER change
last-updated: "2026-04-05"     # ISO date, MUST update on every change
---

Optional Fields

---
# ... required fields above ...
tags: [brand, messaging, external]    # Expected for search and filtering; warning-only if absent
review-cycle: monthly                  # weekly | monthly | quarterly | annual | trigger-based
last-reviewed: "2026-05-05"           # Last validation check, even when content did not change
next-review: "2026-05-05"             # When the next review is due
depends-on: [brand-identity]          # Documents this one requires as input
consumed-by: [messaging-framework]    # Documents that use this one as input
source: "https://..."                 # Original source if migrated from elsewhere
confidentiality: internal             # public | internal | confidential | restricted
lifecycle:                             # Exit-trigger declaration; consumed by lifecycle-sweep job
  archive_when: "proposal-sent"        # See "Lifecycle Triggers" section below
stale-claims:                          # Per-section staleness flags; consumed by bundle resolver
  - section: "Cost taxonomy"
    last-confirmed: "2025-10-15"
    see-evidence: docs/_collections/reports/audit-2025-02-to-2026-04/theo_financial_report.meta.md
    note: "October 2025 baseline; Q1-Q2 2026 actuals captured in audit run, not yet folded back."
---

Field Definitions

Field	Required	Description
`name`	Yes	Human-readable document name
`type`	Yes	Document classification (see types above)
`cluster`	Yes	Parent cluster for grouping
`version`	Yes	Semantic version. Bump on every change (see versioning rules)
`status`	Yes	Lifecycle state (see status definitions below)
`created`	Yes	Date document was first created. Set once, never change.
`last-updated`	Yes	Date content was last changed. MUST update on every edit.
`tags`	No	Free-form labels for discovery and filtering. Expected on managed docs and wiki pages; missing tags are warning-only during adoption.
`review-cycle`	No	How often this should be reviewed
`last-reviewed`	No	Last date the doc was checked and confirmed. This is not the same as `last-updated`; review can happen without content changes. Expected when `review-cycle` exists.
`next-review`	No	Specific date for next scheduled review
`depends-on`	No	Upstream documents (maps to BUILDS_ON in ownership spec)
`consumed-by`	No	Downstream documents (maps to PROVIDES in ownership spec)
`source`	No	Where the original content came from
`confidentiality`	No	Access level classification
`lifecycle`	No	Nested object declaring an exit trigger — when/where this doc should move out of the active zone. Consumed by the `lifecycle-sweep` job (see "Lifecycle Triggers" section below).
`stale-claims`	No	List of structured per-section staleness flags. Each entry names a section of this doc whose values are known-stale, points at fresher evidence, and notes what to reconcile. Consumed by the bundle resolver (surfaces in envelope) and by retrieval-time freshness checks. See "Stale Claims" section below.

Wiki-zone pages add fields such as page-type, domain, exclusively-owns, builds-on, references, last-reviewed, and source-summary provenance fields. Source summaries also keep last-fetched; that records source refresh, while last-reviewed records validation of the authored summary. The authoritative list lives in docs/_wiki/.schema.yml; the framework fallback template is docs/_bcos-framework/templates/_wiki.schema.yml.tmpl.

Lifecycle Triggers

The lifecycle field declares when and where a document should leave the active zone — its exit contract. It is consumed by the lifecycle-sweep job (see docs/_bcos-framework/architecture/lifecycle-routing.md), which classifies each active doc by composing the declared trigger with body-signal markers and reality cross-checks before routing to _archive/, _wiki/, _collections/, or folding into a sibling doc.

The field is optional. Documents without it are evaluated by routing-rule pattern match alone (see lifecycle-routing.yml). Adding a lifecycle declaration upgrades a doc from "guessed" to "self-describing".

Trigger types

Each is independently optional. Compose freely.

Trigger	Type	Semantics
`archive_when`	string (named marker)	Body marker name. Sweep matches against the marker table below. When matched + reality check passes, route to `_archive/<bucket>/`.
`fold_into`	path (relative to repo root)	Sibling doc that should absorb this doc's content. Sweep folds source into target, archives source. Trigger fires when target exists AND source has non-trivial content + age.
`expires_after`	duration (`Nd`, `Nw`, `Nm`)	Date-based fallback. When `last-updated + duration < today`, doc is candidate for routing. Pairs with another trigger to specify destination; alone, defaults to `_archive/abandoned/`.
`route_to_wiki_after_days`	int	After N days, sweep treats this as a wiki-promotion candidate (calls `/wiki promote`). Used for research dumps that should become referenceable explainers.
`route_to_collection`	string (collection type)	Doc represents evidence (a transcript, signed contract, export). After body-marker confirms or `expires_after` fires, route to `_collections/<type>/` with manifest row.

Body-marker table

Trigger names map to body markers the sweep scans for. Markers must appear at the start of a line (case-sensitive) and are followed by a colon + value:

`archive_when` value	Body marker pattern	Example match
`proposal-sent` / `outbound-sent`	`^SENT:`	`SENT: 2026-04-12 to [e-mail address on the upstream page](https://github.com/walm00/business-context-os/blob/463568372f31f24fa6c01121c38f989845ca7c84/docs/_bcos-framework/methodology/document-standards.md)`
`decision-made`	`^DECISION:` or `^RESOLVED:`	`DECISION: pivot to enterprise tier`
`outcome-known`	`^OUTCOME:`	`OUTCOME: closed-won, $40K ARR`
`published`	`^PUBLISHED:`	`PUBLISHED: 2026-04-15 https://blog.example.com/post`
`abandoned`	`^ABANDONED:`	`ABANDONED: stakeholder pivoted, not pursuing`

Custom marker names are allowed; sweep treats unknown values as a synonym for "match any of the standard markers AND require reality cross-check".

Reality cross-check

For each declared trigger, the sweep also verifies the world matches the body's claim. Examples:

archive_when: proposal-sent — if body has SENT:, sweep confirms by checking git log for a sibling "as-sent" version (or a referenced URL).
fold_into: docs/operations/sops/onboarding.md — sweep confirms the target file exists AND that the target either references this doc's date OR contains content overlap above a threshold.
route_to_wiki_after_days: 60 — sweep confirms an external URL exists in the body (otherwise it's not source-summary material).

If the trigger fires but reality contradicts (body says SENT: but no sibling exists), the finding is lifecycle-route-ambiguous — needs user decision, not auto-route.

Five worked examples

Example 1 — outbound proposal that gets sent or abandoned:

---
name: "Acme Enterprise Proposal v3"
type: process
cluster: outbound
version: "1.0.0"
status: active
created: "2026-05-01"
last-updated: "2026-05-01"
lifecycle:
  archive_when: "proposal-sent"   # body adds SENT: when actually sent
  expires_after: 60d              # if no SENT: in 60d → _archive/abandoned/
---

Example 2 — meeting notes that fold into an SOP:

---
name: "Onboarding Process Tweaks — 2026-04-12 sync"
type: reference
cluster: operations
version: "1.0.0"
status: active
created: "2026-04-12"
last-updated: "2026-04-12"
lifecycle:
  fold_into: "docs/operations/sops/employee-onboarding.md"
  expires_after: 14d              # fold within 2 weeks or auto-archive raw
---

Example 3 — research dump that should become a wiki explainer:

---
name: "Competitor X Pricing Teardown"
type: reference
cluster: market-intelligence
version: "1.0.0"
status: active
created: "2026-04-08"
last-updated: "2026-04-08"
source: "https://competitor-x.com/pricing"
lifecycle:
  route_to_wiki_after_days: 30    # after 30d, promote into _wiki/source-summary/
---

Example 4 — point-in-time analysis with a decision in it:

---
name: "Q1 2026 Pipeline Analysis"
type: reference
cluster: revenue
version: "1.0.0"
status: active
created: "2026-04-01"
last-updated: "2026-04-01"
lifecycle:
  archive_when: "decision-made"   # body adds DECISION: when conclusion reached
  expires_after: 90d              # auto-archive after a quarter
---

Example 5 — call transcript that's evidence:

---
name: "Customer Discovery Call — Mid-Market Buyer (Acme)"
type: reference
cluster: market-intelligence
version: "1.0.0"
status: active
created: "2026-04-10"
last-updated: "2026-04-10"
lifecycle:
  route_to_collection: "call-transcripts"   # → _collections/call-transcripts/ with manifest row
  archive_when: "outcome-known"               # body adds OUTCOME: when call's signal is captured elsewhere
---

What lifecycle is NOT

Not a workflow tracker. It declares an exit trigger, not the doc's current operational state. Use status for state.
Not required. A doc without lifecycle is still valid; the sweep falls back to routing-rule pattern match.
Not the only signal. The sweep composes lifecycle + body-markers + reality cross-check + routing-rule pattern match. A trigger fires only when at least two of these agree (configurable confidence tier in lifecycle-routing.yml).

Stale Claims

The stale-claims: field declares per-section staleness — finer-grained than last-updated, which is doc-wide. A canonical doc can be structurally fresh (last-updated: 2026-05-01) yet still contain numbers from six months ago. The resolver has no way to know unless the author says so.

The field is optional. Prose freshness flags remain valid; stale-claims: upgrades them to a structured form the bundle resolver can read.

Shape

A list of entries; each entry is an object:

Field	Required	Description
`section`	Yes	Human-readable name (or section heading) inside this doc whose claims are known stale. Free text.
`last-confirmed`	Yes	ISO date the values in that section were last verified.
`see-evidence`	No	Repo-relative path to a fresher source (typically a `_collections/` sidecar or manifest). Must resolve.
`note`	No	Short prose describing what is stale and how it diverges.

How the framework uses it

Bundle resolver (context_bundle.py): surfaces stale-claims-by-doc as a separate top-level envelope block. Existing by-zone / by-family are untouched — consumers opt in.
Frontmatter validation: rejects entries missing section or last-confirmed; warns when see-evidence does not resolve.
Wake-up generator / audit: may count stale-claims: entries per doc and surface in .wake-up-context.md.

Worked examples

Example 1 — single stale section pointing at a derived-report sidecar:

---
name: "Cost Structure"
type: data-point
cluster: financial
version: "2.1.0"
status: active
created: "2025-10-15"
last-updated: "2026-05-01"
stale-claims:
  - section: "Cost taxonomy and normalized burn"
    last-confirmed: "2025-10-15"
    see-evidence: docs/_collections/reports/audit-2025-02-to-2026-04/theo_financial_report.meta.md
    note: "October 2025 baseline; Q1-Q2 2026 actuals captured in audit run, not yet folded back."
---

Example 2 — multiple stale sections in the same doc:

stale-claims:
  - section: "Cost taxonomy"
    last-confirmed: "2025-10-15"
    see-evidence: docs/_collections/reports/audit-2025-02-to-2026-04/theo_financial_report.meta.md
  - section: "Monthly burn — €16k claim at line 53"
    last-confirmed: "2025-10-15"
    see-evidence: docs/_collections/reports/audit-2025-02-to-2026-04/theo_financial_report.meta.md
    note: "Actual investor-view monthly average is ~€40k; gap is too large to be one-off-only."

Example 3 — no fresh evidence yet, just a flag:

stale-claims:
  - section: "Pricing tiers"
    last-confirmed: "2025-09-01"
    note: "2026 pricing review pending; numbers below are last year's."

What stale-claims is NOT

Not a workflow tracker. Use status: under-review for review state. stale-claims flags known divergence with a pointer to fresher truth (or a note that fresher truth does not yet exist).
Not an automatic-rewrite trigger. The framework does not auto-replace stale sections; the author owns the migration. The resolver merely surfaces the flag.
Not a substitute for last-updated. Doc-level freshness still matters; stale-claims is the finer-grained complement when only some of the doc is stale.

Mechanical Index Facets

The canonical context index derives fields from the path so authors do not duplicate them in frontmatter:

Derived field	Meaning
`zone`	Active, wiki, collection-manifest, inbox, planned, archive, framework, generated, or custom opt-out
`bucket`	Lifecycle bucket used by Atlas/Galaxy: `active`, `_inbox`, `_planned`, `_archive`, `_bcos-framework`, `_collections`
`folder`	Parent path of the file
`path-tags`	Folder components used as searchable facets
`trust-level`	Derived trust class such as high, high-derived, future, historical, low, system, or evidence

These fields are emitted by .claude/scripts/context_index.py into .claude/quality/context-index.json and rendered into docs/document-index.md. Do not hand-maintain them in YAML.

Mandatory Refinement Step

Every time you update a document, you MUST:

Update last-updated to today's date
Bump the version number (at least patch: x.x.+1)
Never touch created -- it's immutable history

Status Definitions

Status	Meaning	When to Use
`draft`	In progress, not yet reliable	New documents being written, content being refined
`active`	Current, accurate, trustworthy	The default state for maintained docs. This IS reality today.
`under-review`	Flagged for accuracy check	When a trigger event occurs or staleness detected
`archived`	No longer current but preserved	Superseded docs. Never delete -- archive instead.

Document Locations (The Folder Structure)

The folder a document lives in tells Claude what it IS before the file is even opened. This is the primary signal — more reliable than metadata fields because it's visible in every glob, grep, and file listing.

docs/
├── *.md                    # ACTIVE CONTEXT — current reality, act on it
├── _inbox/                 # RAW MATERIAL — meeting notes, brain dumps, unprocessed
├── _planned/               # POLISHED IDEAS — documented but not yet real, may never be
├── _archive/               # SUPERSEDED — was real once, kept for reference
├── _collections/           # MANAGED MATERIALS — binary/local assets with manifests
├── _wiki/                  # EXPLANATORY LAYER — wiki pages, source summaries, raw captures
├── table-of-context.md     # Synthesis layer (stable, monthly)
├── current-state.md        # Operations layer (fluid, weekly)
└── document-index.md       # Auto-generated inventory

Folder	What lives here	Quality bar	Claude should...
`docs/*.md`	Active context — current business reality	Full CLEAR compliance	Trust and act on this content
`docs/_inbox/`	Raw dumps — meeting notes, transcripts, pasted content	None (no frontmatter required)	Process via `context-ingest`, not reference directly
`docs/_planned/`	Polished ideas — defined concepts that may or may not happen	Frontmatter recommended, linking optional	Read but NOT treat as current reality
`docs/_archive/`	Superseded docs — no longer current	As-was when archived	Reference for history only, not as current truth
`docs/_collections/`	Managed binary/material collections	Manifest-driven, collection-specific	Treat manifests as authoritative, not binary filenames alone
`docs/_wiki/pages/`	Wiki explainers	Wiki frontmatter schema + ownership fields	Use as high-trust explanatory context built on data points
`docs/_wiki/source-summary/`	Source summaries	Wiki source-summary schema	Use as high-trust summaries of captured sources
`docs/_wiki/raw/`, `queue.md`, `index.md`, `log.md`	Source captures and mechanical artifacts	Managed by `bcos-wiki`	Do not edit as canonical business truth

Why folders instead of a status field? When Claude searches for "pricing" and finds docs/_planned/enterprise-pricing.md, the path itself signals "this is an idea, not reality" — before the file is even opened. A status field buried in YAML frontmatter is easy to miss after the content is already in context.

Moving documents between folders:

_inbox/ → docs/ — raw material refined into active context (via context-ingest)
_inbox/ → _planned/ — raw idea polished into a documented concept
_planned/ → docs/ — idea becomes reality (build full relationships and ownership spec)
docs/ → _archive/ — superseded by newer version or no longer relevant
_inbox/ → _wiki/pages/ — raw material promoted into an explanatory wiki page via /wiki promote
URL/local source → _wiki/source-summary/ plus _wiki/raw/ — source captured and summarized via /wiki create or /wiki run

Wiki-zone exception to flat active docs: normal active data points stay flat under docs/*.md, but docs/_wiki/ intentionally uses semantic subfolders. docs/_wiki/pages/ and docs/_wiki/source-summary/ are governed by docs/_bcos-framework/architecture/wiki-zone.md; docs/_wiki/source-summary/ is the authorized exception to the flat active-doc folder rule.

Minimum Quality Bar

Every document must meet these checks to be considered healthy. This is what context-audit and doc-lint verify.

Level 1: Exists and Is Findable

[ ] Has YAML frontmatter with all required fields
[ ] Lives in the correct cluster directory
[ ] Is listed in the Document Index (if one exists)
[ ] Filename matches content (kebab-case, descriptive)

Level 2: Has Clear Ownership

[ ] Has an Ownership Specification section with DOMAIN and EXCLUSIVELY_OWNS at minimum
[ ] DOMAIN is a clear, one-sentence scope statement
[ ] EXCLUSIVELY_OWNS lists at least 3 specific items

Level 3: Is Bounded

[ ] STRICTLY_AVOIDS lists what belongs elsewhere (with cross-references)
[ ] No content duplicated from another document
[ ] Cross-references use linking, not copying

Level 4: Is Current

[ ] last-updated is recent relative to review cycle
[ ] status accurately reflects the document's state
[ ] Content matches current business reality
[ ] No stale references to things that have changed

Level 5: Is Connected

[ ] BUILDS_ON / REFERENCES / PROVIDES relationships are documented
[ ] depends-on and consumed-by in frontmatter match ownership spec
[ ] Cross-references to other documents resolve (no broken links)

Minimum to be "active": Levels 1-3 must pass. Levels 4-5 are the ongoing maintenance standard.

Documents in docs/_planned/ should have frontmatter but get relaxed rules: staleness threshold is 180 days (vs 90 for active), incomplete cross-references are informational (not errors), and linking is optional until promoted to active.

Documents in docs/_inbox/ don't need to meet any quality bar. They're raw material waiting to be processed by context-ingest. No frontmatter required.

Documents in docs/_wiki/pages/ and docs/_wiki/source-summary/ must satisfy wiki-zone schema rules instead of the standard active-doc template. They still need clear ownership, bounded relationships, and current metadata, but their source-of-authority relationship is expressed with builds-on: and source provenance rather than by duplicating canonical data-point content.

The Golden Rule: Consolidate, Don't Carelessly Delete

When auditing or refining, the goal is clean, authoritative documents -- not cluttered ones.

If you find...	Do this
Duplicated content	Identify the owning document. Merge the best version there. Remove the duplicate from the other document and replace with a cross-reference.
Outdated information	Update it. If the old version matters for history, note the change in a brief changelog at the bottom -- but don't leave stale content inline. Keep active docs clean.
Wrong information	Fix it. Set `status: under-review` if you're unsure of the correct version. Escalate to the owner.
Irrelevant content	Move it to the document that OWNS that topic. If no owner exists, create one or remove it.
Contradictory content	Figure out which version is correct. Consolidate into the owning document. Remove the contradiction from the other.

The principle: Place content where it belongs, then clean up. Don't leave duplicates "just in case." Don't clutter active documents with archived sections and old versions. Git history exists for a reason.

What "don't carelessly delete" means: Before removing a paragraph, make sure the information lives somewhere authoritative. Merge first, then remove the duplicate. The goal is one clean source of truth, not two messy ones.

Changelog (optional, lightweight): If a document needs change history, add a brief section at the bottom:

## Changelog

- **1.2.0** (2026-04-05) - Consolidated audience segments from old marketing deck
- **1.1.0** (2026-03-15) - Added secondary audience definition
- **1.0.0** (2026-02-01) - Initial version

Keep it short. Three to five recent entries. Not a full git log.

Ownership Disputes

When two people or documents claim the same content:

Check the specs. Read both EXCLUSIVELY_OWNS sections. Usually the answer is already there — one document owns the concept, the other should reference it.
If genuinely ambiguous: the architecture owner (whoever maintains the Document Index) decides. Their decision is documented by updating both ownership specs.
If no architecture owner exists: the person who created the data point first is the default owner. The other party splits out their distinct angle into a separate data point with clear boundaries.

The goal is not to prevent disagreement — it's to resolve it in the ownership spec so the same question never comes up twice.

Ownership Specification Format

The ownership spec is the heart of every document. It prevents overlap and drift.

Required for all document types (context, process, policy, reference, playbook):

## Ownership Specification

**DOMAIN:** [One sentence: what this document covers]

**EXCLUSIVELY_OWNS:**
- [Item 1: something ONLY this document contains]
- [Item 2]
- [Item 3]

**STRICTLY_AVOIDS:**
- [Item that belongs to another document] (see: [other-document])
- [Item that belongs elsewhere] (see: [which-document])

Recommended (add when relationships emerge):

**BUILDS_ON:**
- [upstream-document]: [what it provides to this document]

**REFERENCES:**
- [related-document]: [what this document looks up but doesn't modify]

**PROVIDES:**
- [what this document outputs] -> [downstream-document]

Ownership Spec for Process Documents

Process documents (SOPs, workflows) use the same format but with process-specific content:

## Ownership Specification

**DOMAIN:** The content approval workflow from draft submission through final publication.

**EXCLUSIVELY_OWNS:**
- Step-by-step approval process
- Role responsibilities at each step
- Escalation paths and timelines
- Approval criteria and quality gates
- Template links for each stage

**STRICTLY_AVOIDS:**
- Content creation guidelines (see: content-standards)
- Brand voice rules (see: brand-voice)
- Publishing tool documentation (see: tool-reference)
- Legal review requirements (see: legal-compliance-policy)

What Gets Audited

When context-audit runs, it checks every managed document against this standard:

Metadata Checks

All required frontmatter fields present and non-empty
status is a valid value
type is a valid value
version follows semantic versioning format
created is present and immutable (never changed after creation)
last-updated is recent relative to review cycle

Ownership Checks

DOMAIN exists and is a clear statement
EXCLUSIVELY_OWNS has at least 3 items
STRICTLY_AVOIDS exists and references other documents
No two documents have overlapping EXCLUSIVELY_OWNS items

Content Checks

No duplicated content between documents (same paragraph in two places)
Cross-references use (see: document-name) format, not copy-paste
Archived documents have status: archived, not just abandoned

Relationship Checks

All documents referenced in BUILDS_ON / REFERENCES / PROVIDES exist
depends-on and consumed-by frontmatter matches ownership spec
No circular dependencies
No orphan documents (not referenced by anything and not a top-level entry point)

Versioning Rules

Use semantic versioning for documents:

Change Type	Version Bump	Example
Typo fix, formatting	Patch (x.x.1)	1.0.0 -> 1.0.1
New content added, section expanded	Minor (x.1.0)	1.0.1 -> 1.1.0
Major restructure, ownership boundary change	Major (2.0.0)	1.1.0 -> 2.0.0

Every edit = update last-updated + bump version. No exceptions.

Never touch created. It's the document's birth certificate.

Quick Reference

Creating a new document:

Copy the appropriate template from docs/templates/
Fill in all required frontmatter fields (created = today)
Write DOMAIN and EXCLUSIVELY_OWNS at minimum
Add STRICTLY_AVOIDS to prevent future overlap
Set status: draft until content is complete
Change to status: active when ready for use
If it's a polished idea/plan that may not happen yet — put it in docs/_planned/ instead of root docs/

Updating an existing document:

Make your changes
Update last-updated to today
Bump version (at least patch: x.x.+1)
Check that your changes don't violate EXCLUSIVELY_OWNS boundaries
Never touch created

Reviewing an existing document:

Check last-updated -- how old is it?
Read the content -- still accurate?
Check cross-references -- still resolve?
Check EXCLUSIVELY_OWNS -- still correct boundaries?
If you made changes: update last-updated + bump version
If nothing changed: no metadata update needed

278 files · 9 not served here

Advantages

Prevents context rot by surfacing stale information on a configurable schedule. evidence: README.md
Enforces ownership boundaries to ensure one source of truth per topic. evidence: README.md
Reduces token usage by providing a structured index that avoids redundant scanning. evidence: CLAUDE.md
Enables task-aware context retrieval through curated bundles. evidence: README.md

Limitations

Requires adherence to a specific folder structure and frontmatter schema to function correctly. evidence: README.md
Maintenance jobs and dispatcher functionality rely on Python and bash being available on the host system. evidence: README.md

Security

Risk level: Medium risk

This brain runs

Agent instructions that run or fetch something (170)

.claude/agents/wiki-fetch/AGENT.md: A 100k-token URL fetched into the main thread by `/wiki run` saturates the context window before a single page lands.
.claude/agents/wiki-fetch/AGENT.md: | Calling skill | Subcommand | Trigger | |---|---|---| | `bcos-wiki` | `run` Pass 1 | Each URL in the queue → one `wiki-fetch` invocation | | `bcos-wiki` | `refresh` full-tier | Source-summary past `stale_threshold_days` and HEAD signals changed | | `bcos-wiki` | `promote` (Path B) | S …[+132 chars] · uses the network
.claude/agents/wiki-fetch/AGENT.md: The cumulative budget guard ([`_wiki_budget.decide_dispatch_strategy`](../../scripts/_wiki_budget.py)) decides whether N sub-agents run in parallel or serial — `parallel` when projected cumulative tokens stay ≤ 80% of the main context limit;
.claude/agents/wiki-fetch/AGENT.md: queue an explicit retry tag for next run | | `error.kind: fetch-error` | 4xx/5xx from upstream | Surface to user;
.claude/agents/wiki-fetch/AGENT.md: `python .claude/scripts/test_wiki_fetch.py` — asserts this AGENT.md declares the documented input kinds and output fields, that the 4000-token cap is stated, that calling-skill docs reference both `wiki-fetch` and the Task tool, and that the result-schema validator + cumulative budget g …[+47 chars]
.claude/skills/bcos-wiki/SKILL.md: **`/wiki`** with subcommands: `init`, `init --defaults`, `run`, `queue`, `promote`, `create`, `review`, `archive`, `refresh`, `lint`, `remove`, `schema`, `search`
.claude/skills/bcos-wiki/SKILL.md: "Run the wiki refresh"
.claude/skills/bcos-wiki/SKILL.md: | | `run [<url>]` | implemented | P3 | Path A: batch (no arg) processes all `## Pending` queue items;
.claude/skills/bcos-wiki/SKILL.md: single (with URL) auto-queues + ingests | | `queue <url> [tags]` | implemented | P3 | Append URL to `## Pending` of `queue.md` without fetching | | `ingest` | shared protocol | P3 | Internal — called by `run`/`promote`/`create`;
.claude/skills/bcos-wiki/SKILL.md: optionally re-pull `builds-on` data points to verify | | `archive <slug>` | implemented | P3 | Soft-delete to `_wiki/.archive/` with dangling-reference scan | | `refresh <slug>` | implemented | P3 | Path A: re-fetch a `source-summary` page (refresh-must-rediscover applies, D-05 two-tie …[+470 chars]
.claude/skills/bcos-wiki/SKILL.md: `run` → `run.md`
.claude/skills/bcos-wiki/SKILL.md: Run `/wiki init` first."* and exit.
.claude/skills/bcos-wiki/SKILL.md: | Choice | Behavior | |---|---| | Init with defaults + proceed | Run `.claude/scripts/cmd_wiki_init.py` (or equivalent `ensure_wiki_zone.py` call).
.claude/skills/bcos-wiki/SKILL.md: Then resume the original subcommand (`create from`, `promote`, `run`, etc.) as if the Guard had passed.
.claude/skills/bcos-wiki/SKILL.md: | | Full interview + proceed | Read `init.md` and run the 6-question interactive scaffold.
.claude/skills/bcos-wiki/SKILL.md: The dispatched subcommand files (`create.md`, `promote.md`, `run.md`, `refresh.md`, `lint.md`, `archive.md`, `review.md`, `remove.md`, `schema.md`, `search.md`, `bundle.md`, `queue.md`) all reference *"the `.config.yml` Guard defined in `SKILL.md`"* — they inherit this AskUserQuestion p …[+46 chars]
.claude/skills/bcos-wiki/SKILL.md: The human reviews diffs and runs `git commit` / `git push` when ready. · uses the network
.claude/skills/bcos-wiki/SKILL.md: This applies to `run`, `refresh`, and `create` (when source content is large).
.claude/skills/bcos-wiki/SKILL.md: Users who want a binary in collections-as-evidence must run `/collections add` explicitly.
.claude/skills/bcos-wiki/SKILL.md: ├── run.md ← /wiki run [<url>]
.claude/skills/bcos-wiki/SKILL.md: ├── ingest.md ← shared ingest pipeline (called by run/promote/create/refresh)
.claude/skills/clear-planner/SKILL.md: Step 2: Run Discovery
.claude/skills/clear-planner/SKILL.md: { "step": 2, "name": "Run Discovery", "status": "in_progress" }
.claude/skills/clear-planner/SKILL.md: **Run all three discovery scripts:**
.claude/skills/clear-planner/SKILL.md: bash .claude/agents/agent-discovery/find_agents.sh
.claude/skills/clear-planner/SKILL.md: bash .claude/skills/skill-discovery/find_skills.sh
.claude/skills/clear-planner/SKILL.md: python .claude/scripts/find_lessons.py --tags "#{scenarioType}"
.claude/skills/clear-planner/SKILL.md: Run discovery scripts (Step 2 results)
.claude/skills/clear-planner/SKILL.md: | | ------------------- | ------------------------------------ | --------------------------------------------------------- | ------------------- | | Integration Audit | Detect stale references in ecosystem | `python .claude/scripts/analyze_integration.py --staged` + AI review | **YES …[+455 chars]
.claude/skills/clear-planner/SKILL.md: | Scenario | Key Requirement | | ----------------- | ------------------------------------------------------------------ | | **AGENTING** | Check for ecosystem overlaps + run integration audit before commit | | **DOCUMENTAT …[+76 chars]
.claude/skills/context-audit/SKILL.md: Run all five audit categories against the scoped files.
.claude/skills/context-audit/SKILL.md: python .claude/scripts/build_document_index.py
.claude/skills/context-ingest/SKILL.md: | Input shape | Dispatch to | Why | |-------------|-------------|-----| | HTTP/HTTPS URL (article, GitHub, YouTube) | `/wiki run <url>` (the `bcos-wiki` skill, Path A) | Wiki owns external-source ingest, banner citations, schema validation, refresh tier | | Path inside `docs/_inbox/` a …[+508 chars]
.claude/skills/context-ingest/SKILL.md: If the input is mixed (e.g. Slack export *and* a URL), do mine first, then handle the URL via `/wiki run` separately, then return to ingest for whatever's left.
.claude/skills/context-ingest/SKILL.md: Run `python .claude/scripts/build_document_index.py` after material changes
.claude/skills/context-ingest/SKILL.md: **→ Rebuild Document Index** — Always: `python .claude/scripts/build_document_index.py`
.claude/skills/context-ingest/SKILL.md: **→ context-audit** — If a new data point was created: "Want me to run a quick CLEAR audit on the new doc?"
.claude/skills/context-mine/SKILL.md: Recommend: "Run context-ingest to classify and route these items"
.claude/skills/context-onboarding/SKILL.md: | What you see | What you do | |---|---| | User shares a URL, pitch deck, or describes their business | Gather from those sources, ask 2-3 follow-ups if needed | | Repo already has docs/, README, markdown files with business content | Scan the repo, map what exists | | User drops files …[+394 chars] · uses the network
.claude/skills/context-onboarding/SKILL.md: Before anything else, run **once** per onboarding session to make sure the BCOS-managed instructions are present in `CLAUDE.md`.
.claude/skills/context-onboarding/SKILL.md: This catches the `git clone`-without-`install.sh` case: if `CLAUDE.md` exists but lacks the `` / `` markers, the framework section is missing or unstructured. · uses the network
.claude/skills/context-onboarding/SKILL.md: If `.claude/bcos-claude-reference.md` doesn't exist yet (fresh clone), point `--source` at the upstream template available in this repo's tree (the same file install.sh would have copied).
.claude/skills/context-onboarding/SKILL.md: **First-run routing principle:** onboarding is allowed to identify all BCOS zones, but it should only create active data points after the user approves the architecture.
.claude/skills/context-onboarding/SKILL.md: | Material | First-run handling | |---|---| | Canonical facts, current decisions, project/task/business reality | Draft active data points in `docs/*.md` | | Raw notes, unsorted snippets, uncertain material | Keep in `docs/_inbox/` until triaged | | Future ideas, plans, or maybes | Par …[+578 chars]
.claude/skills/context-onboarding/SKILL.md: Options: **Activate** (set all to active, run index + wake-up) / **Adjust** (tell me what to fix)
.claude/skills/context-onboarding/SKILL.md: Run `python .claude/scripts/build_document_index.py` to generate the Document Index with DOMAIN one-liners
.claude/skills/context-onboarding/SKILL.md: Run `python .claude/scripts/generate_wakeup_context.py` to generate the Wake-Up Context for instant session orientation
.claude/skills/context-onboarding/SKILL.md: The checklist ships with install at `docs/.onboarding-checklist.md`.
.claude/skills/context-onboarding/SKILL.md: Ensure the `.claude/hook_state/` directory exists (it usually does from install.sh — check and create if missing).
.claude/skills/context-onboarding/SKILL.md: the dispatcher will create it on first run.
.claude/skills/context-onboarding/SKILL.md: **Run the catalog drift guard:**
.claude/skills/context-onboarding/SKILL.md: python .claude/scripts/validate_permissions_catalog.py
.claude/skills/context-onboarding/SKILL.md: python .claude/scripts/update.py
.claude/skills/context-onboarding/SKILL.md: Re-run the validator to confirm clean.
.claude/skills/context-onboarding/SKILL.md: If the answer is "Yes, multi-repo" (or the user confirms after explanation), run:
.claude/skills/context-onboarding/SKILL.md: python .claude/scripts/install_global_permissions.py
.claude/skills/context-onboarding/SKILL.md: Question: "When should the morning dispatcher run?"
.claude/skills/context-onboarding/SKILL.md: Run the schedule-dispatcher skill to execute today's scheduled CLEAR maintenance. It will:
.claude/skills/context-onboarding/SKILL.md: 3. Execute each job in sequence, appending one diary entry per job
.claude/skills/context-onboarding/SKILL.md: The portfolio aggregator picks it up on the next dispatcher run.
.claude/skills/context-onboarding/SKILL.md: The dispatcher will run in the wrong directory and writes meant for this repo's `docs/_inbox/` will be blocked.
.claude/skills/context-onboarding/SKILL.md: If "Recreate", call `mcp__scheduled-tasks__delete_event` (or the equivalent delete tool) on the bad task, then re-run Step 6d.
.claude/skills/context-onboarding/SKILL.md: That's intentional — fresh setups should over-monitor for the first 1-2 weeks until the auto-tuner suggests reductions after green-run streaks.
.claude/skills/context-onboarding/SKILL.md: Let the user invoke the first run on their terms.
.claude/skills/context-onboarding/SKILL.md: A fresh install has nothing to migrate and should never see the word.
.claude/skills/core-discipline/SKILL.md: **Significant change** (restructure a cluster, create new skills) → use clear-planner, run the full workflow
.claude/skills/core-discipline/SKILL.md: | Task Type | Action | | ------------------------- | ---------------------- | | Questions, commands | Respond directly | | Single-file fixes | Just do it | | Small changes (1-3 files) | Think briefly, execute |
.claude/skills/core-discipline/SKILL.md: A scheduled dispatcher run finishes clean green with zero findings (one-line summary keeps the dashboard "Ready" status meaningful)
.claude/skills/core-discipline/SKILL.md: **Special case — wrapping scripts with built-in prompts** (like `update.py`'s `[y/N]` prompt): invoke the script with `--dry-run` first, parse the output, surface the summary via `AskUserQuestion`, then re-invoke with `--yes` based on the user's choice.
.claude/skills/daydream/SKILL.md: If the file doesn't exist, this is the first run — use 2 weeks ago as the baseline.
.claude/skills/daydream/SKILL.md: # Read last run timestamp (or default to 2 weeks ago)
.claude/skills/daydream/SKILL.md: cat .claude/quality/last-daydream.txt 2>/dev/null || echo "no previous run"
.claude/skills/daydream/SKILL.md: git log --since="{last_daydream_date}" --name-only --pretty=format:"%h %s (%ar)" -- docs/ ':!docs/_bcos-framework/methodology/' ':!docs/_bcos-framework/guides/' ':!docs/_bcos-framework/templates/'
.claude/skills/daydream/SKILL.md: Report "No document changes since last run" and skip to Phase 3 (Imagine) for forward-looking reflection only.
.claude/skills/daydream/SKILL.md: git diff {last_daydream_commit}..HEAD -- docs/path/to/changed-file.md
.claude/skills/daydream/SKILL.md: python .claude/scripts/build_document_index.py --dry-run
.claude/skills/daydream/SKILL.md: python .claude/scripts/generate_wakeup_context.py
.claude/skills/daydream/SKILL.md: **Step 5b: Run maintenance scripts**
.claude/skills/daydream/SKILL.md: Daydream is the natural time to run periodic maintenance:
.claude/skills/daydream/SKILL.md: python .claude/scripts/prune_sessions.py
.claude/skills/daydream/SKILL.md: python .claude/scripts/prune_diary.py
.claude/skills/daydream/SKILL.md: python .claude/scripts/generate_wakeup_context.py
.claude/skills/daydream/SKILL.md: python .claude/scripts/analyze_crossrefs.py
.claude/skills/daydream/SKILL.md: **Step 6: Record this run**
.claude/skills/daydream/SKILL.md: python .claude/scripts/record_daydream.py
.claude/skills/daydream/SKILL.md: **Document Index** — Run `python .claude/scripts/build_document_index.py` if files changed
.claude/skills/doc-lint/SKILL.md: If `.md`: Run markdown quality checks and cross-reference validation
.claude/skills/doc-lint/SKILL.md: If `.json`: Run JSON structure validation
.claude/skills/doc-lint/SKILL.md: Px_001: Run markdown quality check -> doc-lint (markdown category)
.claude/skills/doc-lint/SKILL.md: Px_002: Run example code validation -> doc-lint (cross_reference category)
.claude/skills/doc-lint/SKILL.md: Px_001: Run JSON structure validation -> doc-lint (json_structure category)
.claude/skills/doc-lint/SKILL.md: Px_002: Run markdown quality check -> doc-lint (markdown category)
.claude/skills/ecosystem-manager/SKILL.md: Run discovery to see what exists:
.claude/skills/ecosystem-manager/SKILL.md: bash .claude/agents/agent-discovery/find_agents.sh
.claude/skills/ecosystem-manager/SKILL.md: bash .claude/skills/skill-discovery/find_skills.sh
.claude/skills/ecosystem-manager/SKILL.md: Run it before committing.
.claude/skills/ecosystem-manager/SKILL.md: python .claude/scripts/analyze_integration.py --uncommitted
.claude/skills/ecosystem-manager/SKILL.md: Coverage gaps in install.sh, settings.json, state.json, .gitignore
.claude/skills/ecosystem-manager/SKILL.md: Add fix tasks to the plan and execute them before committing.
.claude/skills/ecosystem-manager/SKILL.md: [ ] **install.sh installs new files**
.claude/skills/ecosystem-manager/SKILL.md: Run after major development sessions or as part of monthly architecture review.
.claude/skills/ecosystem-manager/SKILL.md: Run `python .claude/scripts/wiki_schema.py list` to inspect page-types, lint-checks, and auto-fixes from `_wiki/.schema.yml` or the framework fallback.
.claude/skills/ecosystem-manager/SKILL.md: Run all 4 CI checks locally:
.claude/skills/ecosystem-manager/SKILL.md: python .github/scripts/validate_frontmatter.py # YAML metadata on all managed markdown
.claude/skills/ecosystem-manager/SKILL.md: python .github/scripts/validate_references.py # All registry paths resolve + state.json accuracy
.claude/skills/ecosystem-manager/SKILL.md: python .claude/scripts/analyze_integration.py --ci # Ecosystem wiring (install.sh, settings.json coverage)
.claude/skills/learning/SKILL.md: **Mechanism:** `python .claude/scripts/promote_resolutions.py` (the module's `__main__` calls `regenerate()`).
.claude/skills/learning/SKILL.md: Run the matching subcommand directly.
.claude/skills/lessons-consolidate/SKILL.md: python .claude/scripts/consolidate_lessons.py
.claude/skills/schedule-dispatcher/SKILL.md: Run `python .claude/scripts/update.py` first."
.claude/skills/schedule-dispatcher/SKILL.md: Report to the user: "schedule-config.json is malformed — fix before the dispatcher can run.
.claude/skills/schedule-dispatcher/SKILL.md: For each entry in `jobs`, decide if it should run today.
.claude/skills/schedule-dispatcher/SKILL.md: | `schedule` value | Runs when | |--------------------|----------------------------------------------------| | `"daily"` | Every day | | `"mon"`..`"sun"` | Only on that weekday …[+549 chars]
.claude/skills/schedule-dispatcher/SKILL.md: **For on-demand dispatch** (user said "run the audit-inbox job"): skip this step, run only the named job.
.claude/skills/schedule-dispatcher/SKILL.md: Build an ordered list of jobs to run.
.claude/skills/schedule-dispatcher/SKILL.md: python .claude/scripts/context_index.py --write
.claude/skills/schedule-dispatcher/SKILL.md: The cache TTL is 10 min (longer than a full dispatcher cycle), so all jobs in this run hit the same in-memory snapshot.
.claude/skills/schedule-dispatcher/SKILL.md: Last run timestamp per job?
.claude/skills/schedule-dispatcher/SKILL.md: Use the helper script — it creates `.claude/hook_state/` on first run and matches the allowlisted command prefix so it never prompts:
.claude/skills/schedule-dispatcher/SKILL.md: python .claude/scripts/append_diary.py '{"ts":"2026-04-15T09:04:12","job":"index-health","verdict":"green","findings_count":0,"auto_fixed":[],"actions_needed":[],"duration_s":4}'
.claude/skills/schedule-dispatcher/SKILL.md: **Fallback:** when `.bcos-umbrella.json` is absent (standalone BCOS install with no umbrella), preflight reduces to the `../` + absolute-path scans — no sibling-name list to check against.
.claude/skills/schedule-dispatcher/SKILL.md: After Step 4 completes (last job returned), verify that **every job listed in Step 2's run-list produced exactly one diary entry in this dispatcher tick**.
.claude/skills/schedule-dispatcher/SKILL.md: Read back the diary entries appended during this tick (use the dispatcher's in-memory record, or the tail of `.claude/hook_state/schedule-diary.jsonl` filtered to the current run's `ts` prefix if you're running on-demand).
.claude/skills/schedule-dispatcher/SKILL.md: **Added in schema 1.1.0.** Before applying auto-fixes (Step 5) or rendering the digest (Step 7), enrich each finding emitted in Step 4 with three computed fields and produce the run's headline string.
.claude/skills/schedule-dispatcher/SKILL.md: **Match against prior tick.** Scan diary entries from the **immediately-prior dispatcher tick** (the most-recent run before today, identified by the latest `ts` < today's run window).
.claude/skills/schedule-dispatcher/SKILL.md: | Run shape | Headline template | |---|---| | Green clean (0 findings, 0 framework) | "{Nth consecutive green run.}{recovery callout if any job verdict flipped error→green this tick.}" | | Green with frequency suggestions only | "All {N} jobs green.
.claude/skills/schedule-dispatcher/SKILL.md: And the run has a `headline` string ready for Step 7.
.claude/skills/schedule-dispatcher/SKILL.md: For each job run today, check recent diary:
.claude/skills/schedule-dispatcher/SKILL.md: **Last run was `error`** → suggest investigating, not frequency change
.claude/skills/schedule-dispatcher/SKILL.md: Both are overwritten each run.
.claude/skills/schedule-dispatcher/SKILL.md: Conditional sections render ONLY when their counts are non-zero — a green clean run is ~5 lines, an amber run with 5 findings is ~40 lines.
.claude/skills/schedule-dispatcher/SKILL.md: | 1 | `{emitted_by}` | `{primary_attr}` | {one-line meaning} | {`🔁 Nth run` if consecutive_runs ≥ 3, else blank} |
.claude/skills/schedule-dispatcher/SKILL.md: Run at {ISO timestamp} · `.claude/hook_state/schedule-diary.jsonl`
.claude/skills/schedule-dispatcher/SKILL.md: verdict emoji + finding count + inline status markers in Note column | | `💡 Suggestions` | `≥1` `frequency-suggestion` finding | Bullet list | | Footer | Always | Run timestamp, diary path, auto-commit status |
.claude/skills/schedule-dispatcher/SKILL.md: | Scenario | Verdict bar example | Top line | Action hint | |---|---|---|---| | Green clean | `**🟢 BCOS green** · 1 ran · 0 findings · 0 fixed · 4s` | `Headline string from Step 4c, e.g. "10th consecutive green run."` | `→ Nothing to act on.
.claude/skills/schedule-dispatcher/SKILL.md: Run `git rev-parse --abbrev-ref HEAD` to get the current branch.
.claude/skills/schedule-dispatcher/SKILL.md: This is the per-tick safety property: a stray hand-edit to a "generated" file on a day its owning job did not run still blocks auto-commit.
.claude/skills/schedule-dispatcher/SKILL.md: Globs are resolved against `git status --porcelain` paths (same surface the clean-tree rule already inspects).
.claude/skills/schedule-dispatcher/SKILL.md: **Emit the `job-missing-outputs-declaration` framework-finding only when** the job's run would have changed at least one path *outside* `GLOBAL_ALLOWED` (i.e. a path that *could* have been auto-committable had it been declared).
.claude/skills/schedule-dispatcher/SKILL.md: Run `git status --porcelain`.
.claude/skills/schedule-dispatcher/SKILL.md: `git commit -m "bcos: daily maintenance {YYYY-MM-DD}"` — no push, ever.
.claude/skills/schedule-dispatcher/SKILL.md: A BCOS install with no umbrella still writes the log — it just sits locally until somebody (or the dashboard) reads it.
.claude/skills/schedule-dispatcher/SKILL.md: The last thing the dispatcher does depends on whether the run produced anything that needs user judgement.
.claude/skills/schedule-dispatcher/SKILL.md: Otherwise — clean green run, zero findings, zero suggestions — output a short summary and stop.
.claude/skills/schedule-dispatcher/SKILL.md: **Why this rule:** if every run always asked a question, every scheduled run would show as "Awaiting input" in the dashboard even on clean days.
.claude/skills/schedule-dispatcher/SKILL.md: Or even shorter when the user is watching an on-demand run:
.claude/skills/schedule-dispatcher/SKILL.md: ("Do you want architecture review to run weekly?" is too abstract — `schedule-tune` handles that)
.claude/skills/schedule-dispatcher/SKILL.md: **Retry the failed job(s)** → re-run only the errored jobs (on-demand mode), then ask again with the new result
.claude/skills/schedule-dispatcher/SKILL.md: If the user says "run the {job-name} job now" or "run today's maintenance now":
.claude/skills/schedule-dispatcher/SKILL.md: Skip the schedule predicate — run only the named job(s)
.claude/skills/schedule-dispatcher/SKILL.md: ## On-demand run — {HH:MM} ({job-name})
.claude/skills/schedule-dispatcher/SKILL.md: If `daily-digest.md` does not yet exist (no scheduled run happened today), create it with a minimal header before appending the on-demand section.
.claude/skills/schedule-dispatcher/SKILL.md: DO append a diary entry per job with `"trigger":"on-demand"` so the run is tracked in history
.claude/skills/schedule-dispatcher/SKILL.md: Run another job
.claude/skills/schedule-dispatcher/SKILL.md: The morning scheduled run always OVERWRITES `daily-digest.md` fresh — so yesterday's on-demand sections are not preserved in the digest (diary retains them).
.claude/skills/schedule-dispatcher/SKILL.md: Every dispatcher run produces either a digest OR a user-facing error message.
.claude/skills/schedule-dispatcher/SKILL.md: `schedule-tune` — user-facing skill for changing config ("run audit twice a week")
.claude/skills/schedule-dispatcher/SKILL.md: If a run was wrong, add a corrective entry, don't mutate history.
.claude/skills/schedule-tune/SKILL.md: If you haven't set up BCOS scheduling yet, run `context-onboarding` Step 6.
.claude/skills/schedule-tune/SKILL.md: **Utterances:** *"run audit twice a week"*, *"change daydream to every 3 days"*, *"switch architecture review to quarterly"*, *"run index-health on weekdays only"*, *"audit on Tuesdays and Fridays"*
.claude/skills/schedule-tune/SKILL.md: **Utterances:** *"run the dispatcher at 08:30"*, *"move morning maintenance to 07:00"*
.claude/skills/schedule-tune/SKILL.md: Update the actual scheduled task's cron via `mcp__scheduled-tasks__update_scheduled_task` — that's what actually moves the run
.claude/skills/schedule-tune/SKILL.md: **Utterances:** *"what's my maintenance schedule?"*, *"when does audit run?"*, *"is architecture-review enabled?"*
.claude/skills/schedule-tune/SKILL.md: If the user proposes a cron that would run more than once per day, refuse: *"Dispatcher is designed to run once daily.
.claude/skills/schedule-tune/SKILL.md: | User says | Config edit | |----------------------------------------|----------------------------------------------------------------| | "run audit on Tuesday instead of Friday" | `jobs.audit-inbox.schedu …[+1012 chars]
.claude/skills/todo-utilities/SKILL.md: **Sequential Agent Invocation** — Tasks run one after another
CLAUDE.md: **Small changes (1-3 files)** — think briefly, execute.
CLAUDE.md: Auto-generated by `python .claude/scripts/generate_wakeup_context.py`.
CLAUDE.md: When unsure, run `context-ingest` and let it propose the route.
CLAUDE.md: **Post-work handoffs:** After integrating new content, offer to (a) rebuild the document index, (b) update related data points, (c) run an audit if architecture shifted.

Hooks (5)

.claude/settings.json (Stop): bash "$CLAUDE_PROJECT_DIR/.claude/hooks/auto_save_session.sh"
.claude/settings.json (PreCompact): bash "$CLAUDE_PROJECT_DIR/.claude/hooks/precompact_save.sh"
.claude/settings.json (PostToolUse): "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_frontmatter_check.py"
.claude/settings.json (PostToolUse): "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_edit_frontmatter_check.py"
.claude/settings.json (PostToolUse): "$CLAUDE_PROJECT_DIR/.claude/bin/python3" "$CLAUDE_PROJECT_DIR/.claude/hooks/post_commit_context_check.py"

Install scripts (1)

install.sh: sh install.sh

Medium risk: runs-instruction-instruction-network (.claude/agents/wiki-fetch/AGENT.md:93)
Medium risk: runs-instruction-instruction-network (.claude/skills/bcos-wiki/SKILL.md:150)
Medium risk: runs-instruction-instruction-network (.claude/skills/context-onboarding/SKILL.md:33)
Medium risk: runs-instruction-instruction-network (.claude/skills/context-onboarding/SKILL.md:50)
Low risk: scripts-present (.claude/agents/agent-discovery/find_agents.sh)
Low risk: scripts-present (.claude/bin/python3)
Low risk: scripts-present (.claude/hooks/auto_save_session.sh)
Low risk: scripts-present (.claude/hooks/post_commit_context_check.py)
Low risk: scripts-present (.claude/hooks/post_edit_frontmatter_check.py)
Low risk: scripts-present (.claude/hooks/precompact_save.sh)
Low risk: scripts-present (.claude/scripts/analyze_crossrefs.py)
Low risk: scripts-present (.claude/scripts/analyze_integration.py)
Low risk: scripts-present (.claude/scripts/append_diary.py)
Low risk: scripts-present (.claude/scripts/audit_node_configs.py)
Low risk: scripts-present (.claude/scripts/auto_fix_audit.py)
Low risk: scripts-present (.claude/scripts/bcos_inventory.py)
Low risk: scripts-present (.claude/scripts/build_document_index.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_archive.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_init.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_lint.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_queue_add.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_remove.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_review.py)
Low risk: scripts-present (.claude/scripts/cmd_wiki_search.py)
Low risk: scripts-present (.claude/scripts/consolidate_lessons.py)
Low risk: scripts-present (.claude/scripts/context_bundle.py)
Low risk: scripts-present (.claude/scripts/context_index.py)
Low risk: scripts-present (.claude/scripts/context_search.py)
Low risk: scripts-present (.claude/scripts/digest_sidecar.py)
Low risk: scripts-present (.claude/scripts/find_lessons.py)
Low risk: scripts-present (.claude/scripts/generate_wakeup_context.py)
Low risk: scripts-present (.claude/scripts/install_global_permissions.py)
Low risk: scripts-present (.claude/scripts/lifecycle_sweep.py)
Low risk: scripts-present (.claude/scripts/load_task_profiles.py)
Low risk: scripts-present (.claude/scripts/load_zone_registry.py)
Low risk: scripts-present (.claude/scripts/promote_resolutions.py)
Low risk: scripts-present (.claude/scripts/prune_diary.py)
Low risk: scripts-present (.claude/scripts/prune_sessions.py)
Low risk: scripts-present (.claude/scripts/record_daydream.py)
Low risk: scripts-present (.claude/scripts/record_resolution.py)
Low risk: scripts-present (.claude/scripts/refresh_ecosystem_state.py)
Low risk: scripts-present (.claude/scripts/refresh_wiki_index.py)
Low risk: scripts-present (.claude/scripts/run_wiki_canonical_drift.py)
Low risk: scripts-present (.claude/scripts/run_wiki_coverage_audit.py)
Low risk: scripts-present (.claude/scripts/run_wiki_graveyard.py)
Low risk: scripts-present (.claude/scripts/run_wiki_source_refresh.py)
Low risk: scripts-present (.claude/scripts/run_wiki_stale_propagation.py)
Low risk: scripts-present (.claude/scripts/scan_docs_structure.py)
Low risk: scripts-present (.claude/scripts/set_profile.sh)
Low risk: scripts-present (.claude/scripts/update.py)