janderscience-skills 0.0.0-stage → 1.0.0

package/sources/headcount/docs/DECISION-LOG.md

@@ -0,0 +1,1392 @@
+# Decision log
+
+One heading per decision, numbered sequentially. **Numbers are addresses: a number is assigned when
+the question is asked, not when it is answered, and is never reused.** Every decision carries
+lettered options and an explicit recommendation — never a bare question, never options without a
+recommendation.
+
+Answer by number and letter (`D7b`). Resolved decisions stay in the log with their resolution
+recorded rather than being deleted.
+
+## Status
+
+| # | Decision | Status |
+|---|---|---|
+| D1 | Import scope from discovered collections | ✅ Resolved |
+| D2 | Organizational structure | ✅ Resolved |
+| D3 | Handling of third-party licensed content | ✅ Resolved |
+| D4 | Rewrite-before-purge ordering | ✅ Resolved |
+| D5 | Vendored content remaining in branch history | ✅ Resolved |
+| D6 | Provenance of the 12 Drive-sourced skills | ✅ Resolved |
+| D7 | Audience for vertical variants | ✅ Resolved |
+| D8 | Architecture for vertical variants | ✅ Resolved |
+| D9 | Security as its own department | ✅ Resolved |
+| D10 | Which department to deepen next | ✅ Resolved |
+| D11 | Cross-org sweep of public repos | ✅ Resolved |
+| D12 | Administration department disposition | ✅ Resolved |
+| D13 | Reviewer-class agents and audit independence | ✅ Resolved |
+| D14 | Enforcing the surface map in CI | ✅ Resolved |
+| D15 | PR #2 readiness and merge timing | ✅ Resolved |
+| D16 | Repo visibility versus marketplace distribution | ✅ Resolved |
+| D17 | Which department is the next real gap | ✅ Resolved |
+| D18 | Repository visibility, now that all content is original | ✅ Resolved |
+| D19 | README drift | ✅ Resolved |
+| D20 | Publishing steps that need your hands | ✅ Resolved |
+| D21 | MIT or Apache-2.0 for the long term | ✅ Resolved |
+| D22 | What to call this | ✅ Resolved |
+| D23 | Buttoning up the repository now that it is public | ✅ Resolved |
+| D24 | Whether to add sponsorship | ✅ Resolved |
+| D25 | Whether to register a domain for the About field | ✅ Resolved |
+| D26 | Where project management lives | ✅ Resolved |
+| D27 | Splitting CIO-side IT operations out of `technology` | ✅ Resolved |
+| D28 | US English as house style | ✅ Resolved |
+| D29 | Publishing the org chart so the README can link to it | ✅ Resolved |
+| D30 | Coverage QC against public occupational taxonomies | ✅ Resolved |
+| D31 | Authority as a second axis on the surface map | ✅ Resolved |
+| D32 | Extending the skill-reference checker to skill bodies | ✅ Resolved |
+| D33 | US English check rejects the plural of "analysis" | ✅ Resolved |
+| D34 | Two skills claim social graphics | ✅ Resolved |
+| D35 | Whether description shape is a checkable convention | ✅ Resolved |
+| D36 | Where emitted vertical repositories live | ✅ Resolved |
+| D37 | Authoritative sources as a catalog of references | ✅ Resolved |
+| D38 | Running in ChatGPT as well as Claude Code | ✅ Resolved |
+| D39 | A vertical that brings its own department | ✅ Resolved |
+
+---
+
+## D1. Import scope from discovered collections — ✅ Resolved
+
+Five MIT-licensed skill collections were found across the account's own repositories, holding 106
+skills between them.
+
+- **(a) Curated subset** — take the non-overlapping, highest-quality skills. ← **chosen**
+- (b) Everything, namespaced by source.
+- (c) Engineering and org layer only.
+- (d) Inventory first, decide later.
+
+**Resolution:** (a). 84 of 106 taken; 22 skipped as duplicates, superseded variants,
+author-personalized, or intrusive meta-skills.
+
+---
+
+## D2. Organizational structure — ✅ Resolved
+
+How to structure the org as it grew past ~100 skills, given that every skill's description loads
+into context.
+
+- **(a) Departments as separate plugins**, enabled per project. ← **chosen**
+- (b) Flat `.claude/skills/`.
+- (c) Subdirectories for human organization only (no context saving).
+- (d) Defer until volume hurts.
+
+**Resolution:** (a), later extended into a C-suite hierarchy: a chief executive over eleven
+departments, each an independently installable plugin.
+
+---
+
+## D3. Handling of third-party licensed content — ✅ Resolved
+
+MIT requires the copyright notice be retained in copies and substantial portions. The repository is
+a marketplace intended to be installed, which is distribution.
+
+- (a) Keep the notices in each department's `licenses/`.
+- **(b) Rewrite every affected skill from scratch, then remove the originals and their notices
+  entirely.** ← **chosen**
+- (c) Paraphrase — rejected as the worst option: still derivative, still requires attribution, and
+  degrades the content.
+
+**Resolution:** (b). All 77 vendored skills, their references, datasets, font binaries, and license
+files removed; capabilities re-authored. A clean-room audit returns nothing for license text,
+notices, SPDX tags, upstream names, or vendored assets.
+
+**Known consequence:** part of what was removed was *data*, not prose — a bundled style/palette
+database and licensed font binaries. Those cannot be re-authored, so the replacement design skills
+teach method rather than shipping a dataset. This is a real capability reduction, accepted
+knowingly.
+
+---
+
+## D4. Rewrite-before-purge ordering — ✅ Resolved
+
+The first execution of D3 deleted the originals and then wrote replacements from a catalog of
+names and descriptions, so coverage was never verified against actual content.
+
+**Resolution:** Corrected. All 100 superseded skills were restored from git history to a scratch
+directory and audited against their successors. Every original maps to one; six had lost real
+substance and were patched — site performance and Core Web Vitals, lead scoring, SMS consent law,
+dark-mode and accessibility, campaign naming. One capability (applied behavioral science) had no
+home and became `marketing:behavioral-marketing`.
+
+**Standing rule adopted:** never delete a source before the replacement has been diffed against it.
+
+---
+
+## D5. Vendored content remaining in branch history — ✅ Resolved
+
+The working tree is clean, but commits `36d1be3`, `d091eac`, and `cd1cd22` on
+`claude/import-agents-drive-gmci3h` each still contain ~103 licensed paths. `main` is unaffected —
+PR #1 only ever carried the 12 Drive-sourced skills.
+
+- **(a) Squash-merge PR #2.** `main` gets one clean commit. Non-destructive, PR review trail intact.
+  The branch history survives on GitHub until the branch is deleted. ← **recommended**
+- (b) Rebuild the branch as a single commit and force-push. Actually satisfies "remove entirely" —
+  the old commits become unreferenced. Cost: dangles the PR's commit list and any review threads
+  anchored to those commits.
+- (c) Leave it. The content is MIT and was lawfully obtained; history is an accurate record.
+
+**Recommendation: (a), then delete the branch after merge.** That reaches the same end state as (b)
+without destroying the review trail, since deleting the merged branch unreferences the commits
+anyway. Choose (b) only if you want them gone before merge.
+
+**Resolution: (a) — done.** PR #2 squash-merged as `cc77e22`; branch deleted. `main` carries a single
+clean commit, and no licensed path was ever added on `main` across its whole history. The three
+commits carrying the vendored tree are unreachable.
+
+---
+
+## D6. Provenance of the 12 Drive-sourced skills — ✅ Resolved
+
+Twelve skills came from the shared Drive folder "12 ready-to-use Claude Skills that turn Claude into
+your own AI team," owned by an unfamiliar Gmail account. They carry **no license and no stated terms**,
+and they were never rewritten — they are the only skills in the repository that are not original work.
+
+They are already merged to `main` via PR #1, and they sit in six departments: `ceo-advisor`,
+`business-growth-consultant`, `saas-idea-validator`, `ai-research-analyst`, `ai-workflow-architect`,
+`prompt-optimizer`, `chief-content-officer`, `marketing-campaign-planner`, `newsletter-writer`,
+`landing-page-cro-expert`, `youtube-producer`, `ux-product-auditor`.
+
+This matters because the whole point of D3 was to remove third-party licensed content. No license is
+a *weaker* position than MIT, not a stronger one: MIT grants redistribution rights explicitly, while
+absent terms grant nothing. If that folder is someone's paid product, the repository currently
+redistributes it.
+
+- (a) Leave them. They were shared with you; treat that as permission.
+- **(b) Rewrite all twelve from scratch**, the same treatment the MIT collections got. Removes the
+  question entirely and fixes a second problem — they are the only skills not in the house voice, so
+  the repo currently reads as two documents. ← **recommended**
+- (c) Establish provenance first — find where the folder came from and what terms applied — then
+  decide.
+- (d) Remove them without replacement.
+
+**Recommendation: (b).** It resolves the licensing question, the voice inconsistency, and the
+quality variance in one pass, and it is the only option that does not depend on an answer you may
+not be able to get. Roughly a day of work. If you know the folder's origin and the terms are
+permissive, (a) becomes reasonable — but say so explicitly so it is recorded.
+
+**Resolution: (b).** Rewrite all twelve from scratch, the same treatment the MIT collections
+received. Removes the unlicensed content, brings them into the house voice, and unblocks D15 and D16.
+
+---
+
+## D7. Audience for vertical variants — ✅ Resolved
+
+Whether industry variants (healthcare, manufacturing, retail, food & beverage, financial, services)
+are for your own businesses or are products handed to clients.
+
+- **(a) Own use** across your businesses. ← **recommended as the working assumption**
+- (b) Distributed products sold or delivered to clients in each vertical.
+- (c) Both — internal first, productized later.
+
+**Recommendation: (a) as the assumption until you say otherwise**, because it is the reversible one.
+An overlay architecture built for own use can be packaged into standalone deliverables later; a
+generator built for distribution is heavier than internal use warrants. Answer this before D8 — it
+changes the recommendation there.
+
+**Resolution: (c) — both, internal first.** Build for own use now; treat productization as a later
+decision rather than designing for both up front. D8 therefore resolves to overlays, with the
+constraint that overlay content must stay packageable into standalone deliverables later: no
+cross-vertical references inside an overlay, and no assumption that sibling overlays are installed.
+
+---
+
+## D8. Architecture for vertical variants — ✅ Resolved
+
+Roughly 60% of the current 80 skills are vertical-neutral, 30% keep their shape but need
+vertical-specific content, and 10% would be genuinely new per vertical.
+
+- (a) **Fork per vertical.** Simple to start; every core improvement must then be applied N times,
+  and the copies diverge into unrelated repos within a quarter.
+- **(b) Core plus thin overlays.** Core stays generic and single-copy. Each vertical is a small
+  plugin holding (i) genuinely vertical-only skills and (ii) context files that core skills read
+  when present, so `privacy-and-data-protection` stays one file and gains HIPAA behavior under the
+  healthcare overlay. ← **recommended**
+- (c) **Template plus generator.** A per-vertical config emits a standalone repo. Right if variants
+  must ship without revealing the others; requires one-way generation and never hand-editing output.
+
+**Recommendation: (b) if D7 is (a); (c) if D7 is (b).** This matches §11(B) of the
+`executive:agent-hierarchy` playbook — publish-and-consume with a pinned core version — and its rule
+that a core export is never removed because it looks unused applies from the second vertical onward.
+
+**Suggested first step either way:** build one healthcare overlay against the current core and
+measure how much of that middle 30% genuinely needs context files. A few hours, and it validates the
+model before eight verticals depend on it.
+
+**Resolution: (c) — template plus generator, built now.** Chosen over the recommended overlay model
+because productization is planned (D7c) and this avoids migrating from overlays to a generator
+later.
+
+**What this commits to.** Generation must be one-way: the core plus a per-vertical config emits a
+standalone repo, and generated output is **never hand-edited** — an edit made downstream is lost on
+the next generation, silently. Every vertical change goes into the config or the core. This is
+heavier up front than overlays and the discipline is the whole cost; a generator whose outputs get
+edited is worse than a fork, because the divergence is invisible.
+
+---
+
+## D9. Security as its own department — ✅ Resolved
+
+There are currently zero security skills. `legal-risk` covers governance, risk, and audit readiness
+but no technical security work.
+
+- (a) Add security skills under `technology`.
+- **(b) Create a `security` department with its own CISO charter.** ← **recommended**
+- (c) Extend `legal-risk` to cover technical security.
+
+**Recommendation: (b).** At Fortune 500 scale the CISO reports independently precisely so security
+can overrule engineering; modeling it under the CTO reproduces the conflict the role exists to
+prevent. First skills: `threat-modeling`, `security-architecture-review`, `incident-response`,
+`vulnerability-management`, `access-and-identity`.
+
+**Resolution: (a).** A `security` department with its own CISO charter, reporting independently
+rather than under the CTO.
+
+---
+
+## D10. Which department to deepen next — ✅ Resolved
+
+Four departments have three specialists each; `administration` has none.
+
+- (a) **Security** — the largest absolute gap. (Depends on D9.)
+- (b) **Finance** — add procurement, investment analysis, cash management, revenue recognition,
+  financial controls.
+- (c) **People** — add performance management, employee relations, L&D, workforce planning.
+- (d) **Legal** — add IP and licensing, regulatory compliance, audit readiness, corporate governance.
+- (e) **Operations** — add supply-chain planning, quality management, capacity planning.
+
+**Recommendation: (a) then (e).** Security is the biggest hole. Operations comes next because it is
+the department your own businesses most immediately need — print, fulfillment, and production
+work — and because it is the department most reused by the manufacturing and food verticals in D8.
+
+**Resolution: all four, in this order — Security, Operations, Finance, People.** Security first as
+the largest absolute gap; Operations second as the department your own businesses most need and the
+one most reused by the manufacturing and food verticals.
+
+---
+
+## D11. Cross-org sweep of public repos — ✅ Resolved
+
+Two other organizations I have access to cannot be *attached* to this session (one-owner limit),
+but their **public** repositories are readable here by anonymous clone, which I verified against
+one of them.
+
+What looked likely to hold material: a set of governance, risk and compliance skill repositories,
+some ISO 27001 tooling and evidence-collection work, and one workflow-automation script skill.
+
+- (a) Sweep them now and propose a `compliance` department.
+- **(b) Sweep and catalog only** — report what is there, import nothing until D6 is settled. ←
+  **recommended**
+- (c) Defer entirely.
+- (d) Also run the private and internal sweep from a session rooted in the other organization.
+
+**Recommendation: (b).** The catalog is cheap and informs D8 and D10. Importing anything before D6
+is resolved would repeat the exact mistake D3 and D4 were about — and these are forks of
+third-party work, so the same licensing question applies to all of them.
+
+**Resolution: (d).** Catalog the public repos from this session, and additionally start a separate
+session rooted in the other organization to sweep its private and internal repositories.
+
+**Constraint carried forward:** catalog only. Nothing from either sweep is imported until its
+licensing is established, since these are forks of third-party work and D3 and D6 both turned on
+exactly that question.
+
+---
+
+## D12. Administration department disposition — ✅ Resolved
+
+`administration` holds one charter and no specialists. It exists so orphaned responsibilities have
+an owner.
+
+- (a) Keep as a placeholder.
+- (b) Staff it — corporate records, board support, insurance and continuity, workplace.
+- **(c) Fold into `legal-risk` and `executive`**, and delete the department. ← **recommended**
+
+**Recommendation: (c) for now.** At your scale corporate governance sits naturally with Legal & Risk
+and board support with the CEO's office. An empty department installed for one charter is overhead.
+Revisit if the corporate-secretary function becomes real.
+
+**Resolution: (c).** Fold corporate governance into `legal-risk` and board support into `executive`,
+then delete the `administration` department.
+
+---
+
+## D13. Reviewer-class agents and audit independence — ✅ Resolved
+
+The `executive:agent-hierarchy` skill requires that producer and auditor are never the same agent.
+The current chart violates it: every department reviews its own work.
+
+- (a) Accept it for now.
+- **(b) Designate reviewer-class departments** — `legal-risk`, and `security` if D9 is (b) — whose
+  charters explicitly cannot be overruled by the department they are reviewing. ← **recommended**
+- (c) Add a separate `internal-audit` department reporting to a board/audit-committee construct
+  rather than to the Chief Executive.
+
+**Recommendation: (b) now, (c) later.** (b) is a charter edit and costs nothing. (c) matters once
+there is real audit activity — and note that if it is ever added, placing it under `executive` would
+reproduce the independence failure it exists to prevent.
+
+**Resolution: (b).** Mark `legal-risk` and the new `security` department reviewer-class in their
+charters — explicitly not overrulable by the department under review. Internal audit deferred until
+there is real audit activity; if added, it must not report to the Chief Executive.
+
+---
+
+## D14. Enforcing the surface map in CI — ✅ Resolved
+
+`executive:agent-hierarchy/scripts/agent-guard.mjs` is present and runs, but nothing invokes it and
+no surface map exists. The playbook's own position is that an unenforced map is a suggestion.
+
+- (a) Leave it as reference material.
+- **(b) Write `docs/AGENT-SURFACES.md` mapping each department to its exclusive path glob, and run
+  `agent-guard check` in CI.** ← **recommended**
+- (c) Also run `agent-guard diff` per change.
+
+**Recommendation: (b).** The department layout already is a surface map — each department owns
+`plugins/<dept>/**` and nothing else — so writing it down is close to free, and it becomes load-bearing
+the moment more than one session edits this repo. Note the repo has no CI workflows at all yet, so
+this also means adding the first one.
+
+**Resolution: (b).** Write `docs/AGENT-SURFACES.md` mapping each department to its exclusive glob and
+run `agent-guard check` in CI. This adds the repository's first CI workflow.
+
+---
+
+## D15. PR #2 readiness and merge timing — ✅ Resolved
+
+PR #2 is a draft: 80 skills, eleven departments, merges cleanly, no CI configured, no review threads.
+
+- (a) Mark ready and merge now; treat D6 as follow-up work.
+- **(b) Resolve D6 first**, then mark ready and merge. ← **recommended**
+- (c) Keep as a draft while D7–D10 are decided, and merge one larger change.
+
+**Recommendation: (b).** D6 is the only open item that changes files already in this PR's scope.
+D7–D14 are all new work that belongs in later PRs — holding this one open for them means a
+1,000-file review nobody can do properly.
+
+**Resolution: (b).** Resolve D6 first, then mark ready and merge. D6 is the only open item touching
+files already in this PR's scope.
+
+---
+
+## D16. Repo visibility versus marketplace distribution — ✅ Resolved
+
+`cbrock84/headcount` is **private**, but the README instructs `/plugin marketplace add
+cbrock84/headcount`. A private marketplace requires each installing machine to be authenticated to
+this repository, which the instructions do not mention.
+
+- (a) Keep private, and document the authentication requirement in the README.
+- (b) Make the repository public. Note that this would publish the D6 skills, whose terms are
+  unknown — do not choose this before D6 is resolved.
+- **(c) Keep private now, decide visibility after D6 and D7.** ← **recommended**
+
+**Recommendation: (c), with the README corrected immediately** either way, since it currently
+documents an install path that will fail for anyone but you.
+
+**Resolution: (c).** Stay private until the twelve rewritten skills land, then revisit. The README
+already states the authentication requirement. Note that if D8's generator becomes the distribution
+path, the per-vertical repos rather than this one may be the artifact that needs to be public.
+
+---
+
+# Work queue
+
+Derived from the resolutions above, in dependency order. This is the execution plan, not a new set
+of decisions.
+
+| # | Work | From | Blocks | Status |
+|---|---|---|---|---|
+| 1 | Rewrite the 12 Drive-sourced skills from scratch | D6 | D15, D16 | ✅ done |
+| 2 | Fold `administration` into `legal-risk` + `executive`; delete the department | D12 | — | ✅ done |
+| 3 | Mark `legal-risk` reviewer-class in its charter | D13 | — | ✅ done |
+| 4 | Write `docs/AGENT-SURFACES.md`; add first CI workflow running `agent-guard check` | D14 | — | ✅ done |
+| 5 | Mark PR #2 ready; squash-merge; delete the branch | D5, D15 | 6+ | ✅ done |
+| 6 | Build `security` department + CISO charter, marked reviewer-class | D9, D10, D13 | — | ✅ done |
+| 7 | Deepen `operations`, then `finance`, then `people` | D10 | — | ✅ done |
+| 8 | Catalog the other organizations' public repos — no import | D11 | — | ✂️ dropped, D30 |
+| 9 | ~~Separate session for the private sweep~~ | D11 | — | ✂️ dropped, D30 |
+| 10 | Build the vertical generator: core, per-vertical config, one-way emit | D8 | — | ✅ done, D36 |
+| 11 | Revisit repo visibility | D16 | after 1 | ✅ done |
+
+Items 1–4 can proceed in parallel; all four land before item 5. Items 8 and 9 were dropped in D30.
+
+---
+
+# Open decisions
+
+Raised after the first sixteen were resolved. Same convention: numbers are addresses, assigned when
+asked.
+
+## D17. Which department is the next real gap — ✅ Resolved
+
+With `security` built, the catalog covers eleven departments. Three functions a Fortune 500 has
+that this does not:
+
+- **(a) Customer Experience / Support.** Every business has support; the catalog has none.
+  `revenue:retention` is the only adjacent skill. Needed: support operations, escalation handling,
+  voice-of-customer, service-level design. ← **recommended**
+- (b) **Data & Analytics (CDO).** `demand-generation:marketing-analytics` covers marketing
+  measurement only. No data governance, warehouse modeling, BI, or AI/ML governance — the last is
+  increasingly a board obligation.
+- (c) **Corporate Strategy / Corp Dev.** M&A, diligence, scenario planning, competitive war-gaming.
+- (d) None — deepen the eleven that exist instead.
+
+**Recommendation: (a), then (b).** Support is the most conspicuous absence to anyone reading the
+catalog — it is the department every company has and this one does not. Data & Analytics is the
+one most likely to be expected of a modern org chart. Corp Dev is real but only bites at a scale
+this repo's likely users have not reached.
+
+**Resolution: all three, treated as equally important.** `customer-experience`, `data-analytics`,
+and `corporate-strategy` built together, five skills each. Fourteen departments, 101 skills.
+
+## D18. Repository visibility, now that all content is original — ✅ Resolved
+
+D16 deferred this until the rewrite landed. It has. Nothing in the repository now carries a
+third-party obligation, and `scripts/check-provenance.py` fails the build if that changes.
+
+- **(a) Make it public under MIT.** The install path in the README then works for anyone. ←
+  **recommended**
+- (b) Stay private and document the authentication requirement.
+- (c) Public, but wait until the vertical generator (D8) decides whether per-vertical repos are the
+  distributed artifact instead.
+
+**Recommendation: (a).** The blocker was provenance and it is resolved. Publishing does not commit
+you on D8 — a generator can emit per-vertical repos later regardless of whether this one is public.
+
+**Resolution: (a).** `cbrock84/headcount` is public under MIT as of 29 August 2026, confirmed via the
+API (`visibility: public`). This also closes work-queue item 11, which existed only to revisit this.
+
+**What publishing actually changed.** The install path in the README now resolves for anyone — under
+D16 it required every installing machine to be authenticated to the account, which made the
+documented instructions untrue for everybody except the owner. That gap is closed.
+
+**Still unverified.** Nothing in this session can run `/plugin marketplace add` against a clean
+client, so the manifest is verified only up to "it parses and every referenced path exists". The
+first genuine test is an install from a machine that has never seen this repository.
+
+## D19. README drift — ✅ Resolved
+
+`scripts/build-readme.py` regenerates the README from the tree, and `check-all.sh` fails if it is
+stale. This works but means the README cannot be hand-edited.
+
+- **(a) Keep generation, edit the generator.** ← **recommended**
+- (b) Generate only the tables, hand-write the prose around them.
+- (c) Drop generation; accept that counts drift.
+
+**Recommendation: (a) for now, (b) if the prose starts wanting per-section nuance the generator makes
+awkward.** The failure this prevents is real: the README claimed eleven departments and listed a
+deleted one for two commits before it was caught by hand.
+
+**Resolution: (a), and the scope of generation has since widened twice.** The org chart's department
+table was moved inside generated markers after it drifted the same way, and the badge counts in the
+README header are now emitted from the same tree walk that builds the tables — so a wrong count is a
+CI failure rather than something a reader has to notice.
+
+The generator was also hardened after review: it discovers departments from the plugin tree instead
+of a hand-maintained list, and refuses to run when a department on disk has no display metadata. The
+earlier design would have omitted a new department from both documents while `--check` still passed,
+because it compared the files against output from the same incomplete list.
+
+**(b) remains the fallback** if the prose ever wants per-section nuance that the generator makes
+awkward. Nothing about that has changed.
+
+## D20. Publishing steps that need your hands — ✅ Resolved
+
+Repository settings are not reachable from this session — no tool exposes topics, description, or
+merge defaults, and the git proxy blocks branch deletion. These are yours to click.
+
+- (a) Do them all now, before going public.
+- **(b) Do the four that affect discoverability and hygiene now; treat the profile README as
+  optional.** ← **recommended**
+- (c) Publish first, tidy later.
+
+The list, in order of value:
+
+1. **Topics** — `claude-code`, `claude-skills`, `ai-agents`, `agent-marketplace`, `claude-plugins`.
+   This is how anyone finds it, and it is the step most often skipped.
+2. **About** — one line plus the repo URL. Suggested: *"An agent organization for Claude Code: a
+   C-suite of 14 departments and 101 skills, installable per department."*
+3. **Settings → General → Automatically delete head branches.** Three merged branches have needed
+   manual deletion so far.
+4. **Default merge to squash**, if you want one commit per change on `main`. #3 came in as a merge
+   commit.
+5. *Optional:* pin the repo on your profile, and a `cbrock84/cbrock84` profile README featuring it.
+
+**Recommendation: (b).** 1–3 matter; 4 is preference; 5 is worth doing only if you want the profile
+to lead with this.
+
+**Resolution: (b), executed 29 August 2026.** Repository renamed to `headcount` (D22), made public,
+description set, automatic head-branch deletion enabled, and the four stale merged branches deleted.
+`origin/main` is now the only remote branch.
+
+**One item outstanding, carried to D23:** topics are still empty. Verified via the API — the
+repository returns no topics array. This is the item the entry above called "the step most often
+skipped", and it was skipped, for a findable reason: **topics are not in Settings.** They live behind
+the gear icon on the About panel of the repository home page, which is where nobody looks for a
+setting. Noted here because the same confusion will recur on every vertical repo D8 emits.
+
+## D21. MIT or Apache-2.0 for the long term — ✅ Resolved
+
+Raised while preparing to publish. Apache-2.0 is the usual alternative to MIT for a project intended
+for wide reuse.
+
+**What Apache-2.0 adds over MIT:** an explicit patent grant with a retaliation clause, an explicit
+trademark carve-out, a requirement that modified files carry a notice of change, and automatic terms
+for inbound contributions.
+
+- **(a) MIT.** ← **chosen**
+- (b) Apache-2.0.
+- (c) A content license such as CC-BY-4.0.
+- (d) Dual — CC-BY for the prose, MIT for the scripts.
+
+**Resolution: (a).** The reasoning, recorded so it is not re-litigated:
+
+- **The patent grant is Apache's headline feature and is near-irrelevant here.** This repository is
+  markdown. Instructions for running a threat model or a CRO audit are not patentable subject matter
+  in any practical sense, so the protection Apache exists to provide has almost nothing to attach to.
+- **Apache §4(b) is active friction for the intended use.** It requires modified files to carry
+  prominent change notices. The whole design is people installing a department and adapting it; MIT
+  lets them, Apache asks them to annotate every file they touch.
+- **MIT is the ecosystem norm.** Every collection this repository originally drew from was MIT, and
+  the Claude skills and plugins ecosystem is MIT by convention. Lower friction, fewer legal reviews.
+- **Short licenses get complied with.** Two hundred lines of license on a prose repository invites
+  the question of whether anyone read it.
+- **(c) and (d) rejected:** Creative Commons explicitly advises against using CC for software, this
+  repository contains executable scripts alongside the prose, and a split license confuses tooling
+  and adopters for no practical gain.
+
+**The one real gap MIT leaves** — what license inbound contributions carry — is closed by
+`CONTRIBUTING.md` stating that contributions are accepted under MIT, rather than by changing the
+license.
+
+**Timing note, which is the part that matters later.** Relicensing is clean only while there is a
+single copyright holder. Once outside contributions land under MIT, you cannot retroactively un-MIT
+what has been published; you would be layering Apache over MIT-licensed parts, which is lawful but
+messy. So this decision is cheap to reverse **today** and expensive to reverse after the first
+external pull request.
+
+**Revisit if** the repository grows substantial executable code — the vertical generator in D8 is the
+plausible candidate — or if a corporate adopter's legal team specifically asks for the patent grant.
+Neither is true now.
+
+**Not legal advice.** For the productized vertical variants contemplated in D8, where money and
+third-party distribution are involved, this is worth qualified counsel rather than a decision log.
+
+---
+
+## D22. What to call this — ✅ Resolved
+
+`agents-v1` was a working title. It describes the mechanism (agents) and a version number, neither of
+which is a name, and it was about to be published — at which point the name stops being free to
+change.
+
+The binding constraint is not aesthetics. It is that the brand appears **after an `@` in every
+install command**:
+
+```
+/plugin marketplace add cbrock84/NAME
+/plugin install security@NAME
+```
+
+`security@NAME` renders as a corporate email address. That is free explanation of the whole product,
+but only for a name that reads like a company. It rules out descriptive multi-word names.
+
+- **(a) `headcount`.** ← **chosen**
+- (b) `holdco` — a holding company holds operating subsidiaries; this holds installable departments.
+  Structurally exact, and less likely to collide with an existing product.
+- (c) `boardroom`, `roster`, `charter`, `quorum` — all read as companies; each is either semantically
+  off (a boardroom is the board, not the operating org) or heavily used elsewhere.
+- (d) `company-in-a-box` and relatives — say exactly what it is, but are not distinctive and destroy
+  the `@` construction.
+- (e) Keep `agents-v1`.
+
+**Resolution: (a).**
+
+- **It names the benefit, not the mechanism.** "101 markdown skills in a plugin marketplace" is what
+  it is made of. "Headcount" is what someone wants: a CISO, a CFO, a growth lead, without the req.
+- **The install string becomes the tagline.** `/plugin install security@headcount` reads as hiring a
+  security department. Nothing further needs explaining.
+- **It survives D8.** Generated verticals are `headcount-health`, `headcount-retail`,
+  `headcount-industrial` — which parse as staffing firms with a specialty. The metaphor strengthens
+  as it is cloned, which is unusual and worth the points.
+
+**This sets the vertical naming convention for D8**, whose resolution (c) emits standalone repos:
+each generated vertical is `headcount-<vertical>`, and the generator's per-vertical config carries
+the suffix. Recorded here so the generator is not built against a different scheme.
+
+**Name-collision caveat, not resolved by this entry.** `headcount` is a common noun in HR software
+and this log is not a trademark search. The check is worth doing before any commercial use of the
+D7/D8 productized variants; for an MIT repository under a personal account the exposure is low.
+`holdco` (b) remains the fallback if a conflict surfaces, and is a cheap swap while the name is
+young — the same timing logic as D21.
+
+**Timing.** Renaming cost one commit here. After publication the install string gets copied into
+config files, posts and screenshots that never update — GitHub redirects renamed repositories, but
+it cannot rewrite what people have already pasted elsewhere. This was the last moment it was free.
+
+---
+
+## D23. Buttoning up the repository now that it is public — ✅ Resolved
+
+Going public changes the threat model and the audience. Anyone can now fork, open a pull request
+that runs CI, and judge the project in about four seconds of looking at the landing page.
+
+- **(a) Presentation and hardening together, now.** ← **chosen**
+- (b) Presentation now, hardening when there is actual traffic.
+- (c) Neither; the repository is fine as it is.
+
+**Resolution: (a).** Both are cheap, and the hardening items are the kind that are embarrassing to
+add after an incident rather than before one.
+
+**Presentation — done in this change.**
+
+The README now opens with a centered title, the tagline, and a badge row: built-for Claude Code,
+department count, skill count, license, and PRs-welcome. **The counts are generated from the same
+tree walk that builds the tables**, so they are covered by the existing staleness check — a badge
+claiming the wrong number fails CI. A hand-typed badge would have become a lie on the next
+department, which is precisely the D19 failure in a more visible place.
+
+**`.gitattributes` added.** GitHub labeled the repository *JavaScript* on the strength of a single
+`.mjs` guard script, against 101 markdown skills that are the actual product. Linguist counts bytes
+of code and does not know what a repository is for. The attributes file marks tooling as vendored
+and generated documents as generated, so the language bar reflects the deliverable.
+
+**Hardening — done in this change.**
+
+- **Explicit `permissions: contents: read` on the workflow.** It only reads the tree and runs
+  checks. Public repositories accept pull requests from forks, and being explicit means a permissive
+  account-level default cannot hand a write-scoped token to a workflow triggered by a stranger.
+- **Push trigger narrowed from `["**"]` to `[main]`.** Every push was running the workflow twice —
+  once for the push, once for the pull request, on the same commit. Pure waste either way.
+- **Deprecated actions bumped.** The first green run warned that `actions/checkout@v4` and
+  `actions/setup-node@v4` run on Node 20, which is being force-migrated to Node 24. Both are now at
+  v7, with `node-version` at 24. Versions were checked against the actions' own release pages rather
+  than assumed — the guess would have been v5, and both are three majors further on than that.
+
+**The CI blackout ended, and not for the reason recorded.** Every run from 28 August onward failed in
+three to four seconds with no steps and empty output, on this repository and on `main` alike. That
+was diagnosed as exhausted Actions minutes, with the fix being the 1 September quota reset. The
+minutes were genuinely exhausted, but the reset was never the fix: **GitHub Actions is free and
+unlimited for public repositories on standard runners** (GitHub's own billing documentation:
+"GitHub Actions usage is free for self-hosted runners and for public repositories that use standard
+GitHub-hosted runners"). Making the repository public under D18 ended the blackout immediately —
+the first run after publishing went green in eight seconds, executing all five checks.
+
+Worth recording because the wrong lesson was nearly banked. The blackout was treated as an external
+constraint to wait out, and `scripts/check-all.sh` was built to decouple verification from CI while
+it lasted. That script earns its place regardless. But the constraint was a consequence of a setting
+this project had already decided to change, and nobody connected the two for a full day.
+
+**Deliberately not done.**
+
+- **Dependabot.** There are no dependency manifests — no `package.json`, no `requirements.txt`.
+  It would have nothing to scan, and enabling it would only add a quiet integration that never fires.
+- **Branch protection requiring approvals.** With a single maintainer, required approvals block the
+  only person who can approve. A ruleset requiring a pull request into `main`, with the owner as a
+  bypass actor, is the right shape if drive-by pushes ever become a concern; it is not one yet.
+
+**Left to the owner** (settings are not reachable from an agent session — see D20): topics, secret
+scanning with push protection, and turning off the unused Wiki and Projects tabs.
+
+---
+
+## D24. Whether to add sponsorship — ✅ Resolved
+
+GitHub Sponsors would put a **Sponsor** button on the repository, driven by `.github/FUNDING.yml`.
+
+- (a) Enrol and add `FUNDING.yml` now, with the repository.
+- **(b) Not yet — revisit at a real usage signal.** ← **chosen**
+- (c) Never; keep it a pure gift.
+
+**Resolution: (b).** Not on principle — the timing is simply wrong, and the cost of asking early is
+not zero.
+
+- **There is nothing to sponsor yet.** One star, no external installs, no issues, published today.
+  A funding ask is a claim that ongoing maintenance has value to someone; that claim is currently
+  unevidenced, and a reader can tell.
+- **It changes how the first impression reads.** A brand-new repository leading with a payment link
+  invites the question of whether the catalog was assembled to be monetised. That is a costly
+  question to raise while the provenance story — 101 skills written from scratch after removing
+  every vendored collection — is the thing worth the reader's attention.
+- **It is thirty seconds whenever you want it.** Enrol at `github.com/sponsors`, then a two-line
+  `.github/FUNDING.yml` with `github: [cbrock84]`. Nothing about deferring makes it harder later.
+
+**The signal to revisit:** external installs, inbound issues from people who are not you, or a fork
+that gets used. Any one of those makes the ask legible. **Revisit sooner** if the D7/D8 vertical
+variants become a commercial product — that is a different question (pricing, not donations) and
+deserves its own entry rather than a sponsor button.
+
+---
+
+## D25. Whether to register a domain for the About field — ✅ Resolved
+
+GitHub's About panel has a Website field. The available domains were `headcount.biz`,
+`headcount.info` and similar — the short, conventional ones are gone.
+
+- (a) Register a cheap available TLD (`.biz`, `.info`) and link it now.
+- **(b) Leave the Website field empty; revisit when there is something to point at.** ←
+  **chosen**
+- (c) Register `headcount.dev` if free and hold it unused against later need.
+- (d) Point the Website field at a GitHub Pages site built from this repository.
+
+**Resolution: (b), with (c) as a cheap optional hedge.**
+
+- **`.biz` and `.info` are negative signals to this audience.** They are the TLDs of parked
+  pages and expired-domain farms. Someone deciding whether to install 101 skills into their
+  agent is making a trust judgment, and that domain in the About field reads worse than a blank
+  field. A rare case where the cheap option is worse than nothing rather than merely weaker.
+- **A domain does not serve this product yet.** Installation is `/plugin marketplace add
+  cbrock84/headcount`, typed inside Claude Code. Discovery runs through repository topics, the
+  plugin ecosystem, and word of mouth — none of which route through a domain. Nobody searches
+  the web for "headcount" and finds an agent marketplace; they find HR software.
+- **A link has to point at something.** A redirect to the repository adds a hop for no gain, and
+  a parked domain is a worse signal than an empty field. (d) has the same problem until there is
+  documentation that does not fit in the README.
+
+**The part worth keeping.** That the short TLDs are gone is *evidence for the collision caveat
+already recorded in D22*, discovered by accident. `headcount` is a common noun in HR software,
+and the domain market is confirming how crowded that space is. The name remains right for a
+repository, where the namespace is `cbrock84/headcount` and collision costs nothing — but **do
+not build an identity that depends on owning the word.** Accepting a degraded TLD would be
+exactly that mistake in miniature.
+
+**Revisit when** the D7/D8 vertical variants become something distributed or sold. That is a real
+product with a reason for a hub, and it is the same moment the trademark question in D22 needs a
+proper answer rather than a caveat. Prefer `.dev` then — correct signal for developer tooling and
+HTTPS-only — or a modified name over a degraded TLD.
+
+---
+
+## D26. Where project management lives — ✅ Resolved
+
+Project management existed only as a single `program-management` skill inside `operations`. The
+question raised was whether
+discipline belongs in silos inside each department or as an enterprise function.
+
+- (a) **Siloed.** Each department carries its own project management guidance.
+- (b) **Inside `operations`.** Expand the COO's department to hold the discipline.
+- **(c) A separate `pmo` department reporting to the COO.** ← **chosen**
+
+**Resolution: (c).**
+
+- **(a) fails this repository's founding rule.** `executive:agent-hierarchy` splits by exclusive
+  write surface, not by topic. Project management is a topic crossing all sixteen departments, so
+  siloing it produces sixteen near-identical skills — precisely the duplication that forced the
+  earlier consolidation.
+- **(c) over (b) on installability.** The premise of the marketplace is installing only what you
+  need. Someone who wants portfolio governance and stage gates should not have to take
+  `supply-chain-and-logistics` and `vendor-management` with it. An EPMO is also a distinct function
+  in practice, with its own head, rather than a subset of operations.
+
+**The `program-management` skill moved from `operations` to `pmo:program-management`.** Worth doing
+at this moment specifically: the repository published today with no external installs, so the
+address is still free
+to change. Once someone has the department installed and the address referenced, it is not — the same
+timing logic as the rename in D22 and the license in D21. Verified no reference to the old address
+survives anywhere in the tree.
+
+**Reporting line: the COO**, reflected in the org chart. The EPMO governs delivery across the
+organization; it does not own the functions whose work it governs.
+
+**Boundaries stated in the skills rather than left to collide.** `pmo:portfolio-governance` handles
+resource contention across projects while `operations:capacity-and-demand-planning` handles
+operational throughput; `pmo:dependency-and-risk-management` handles delivery risk while
+`legal-risk:enterprise-risk` owns the enterprise framework.
+
+---
+
+## D27. Splitting CIO-side IT operations out of `technology` — ✅ Resolved
+
+`technology` was labeled "CTO / CIO" and held twelve skills, all of them software development
+workflow. The request to add help desk, network administration and system administration forced the
+question of whether those belong in the same department.
+
+- (a) **Add them to `technology`.** One department, around twenty-five skills.
+- **(b) Split: `technology` for the CTO side, a new `it-operations` for the CIO side.** ← **chosen**
+- (c) Leave corporate IT out of the catalog.
+
+**Resolution: (b).**
+
+- **They are different functions with different audiences.** Product engineering and corporate IT
+  share a reporting line in some organizations and almost nothing else. Bundled, a SaaS engineering
+  team installing `technology` receives deskside support skills it will never open, and an IT
+  director receives worktree workflow they will never open. The split is what makes both installable
+  without noise.
+- **The combined "CTO / CIO" label was papering over a real division**, and the catalog was
+  honest about only one half of it.
+
+**What moved where.** `technology` gained `solution-architecture`, `api-design`,
+`technical-debt-management`, `cloud-infrastructure`, `observability-and-reliability` and
+`release-and-deployment`, reaching eighteen. `it-operations` is new with seven. `data-engineering`
+went to `data-analytics` rather than `technology`, because pipelines belong beside `data-modeling`
+and `data-governance` under the CDO.
+
+**Overlaps resolved explicitly inside the skills**, since unstated boundaries are what forced the
+earlier consolidation:
+
+- `security:access-and-identity` owns access **policy**;
+  `it-operations:identity-lifecycle-administration` owns **execution** of joiner-mover-leaver.
+- `operations:business-continuity-and-resilience` owns recovery objectives and the business process;
+  `it-operations:backup-and-recovery` owns the technical restore that delivers against them.
+- `technology:cloud-infrastructure` owns cloud environment design;
+  `it-operations:systems-administration` owns operating the systems the company runs on.
+- `security:vulnerability-management` decides what is urgent to patch;
+  `it-operations:systems-administration` executes the cadence.
+
+**Also fixed here.** Every agent charter carried a hardcoded skill count — `finance` claimed four
+while holding nine. The count added nothing and rotted silently, so it was removed rather than
+updated to a number that would rot again.
+
+---
+
+## D28. US English as house style — ✅ Resolved
+
+The catalog had drifted into British spelling across 178 occurrences in 49 files — the British
+forms of *license*, *program*, *catalog*, *behavior*, *prioritize* and *center*, among others. The
+author is in Georgia and writes in US English, so the repository was not speaking in his voice.
+
+- (a) **Fix the current occurrences.** A one-time rewrite.
+- **(b) Fix them and enforce it.** ← **chosen**
+- (c) Accept mixed spelling as unimportant.
+
+**Resolution: (b).** The one-time fix is the smaller half. Spelling drift is invisible to review and
+returns with the next contribution, and a repository of original work reading as though it came from
+somewhere else is precisely the wrong impression. `scripts/check-us-english.py` fails the build on
+British spellings and rewrites them under `--fix`; it is the ninth check.
+
+**Exact word forms, never stems.** This is the trap the check is built around: *analysis*,
+*analyst*, *specialist* and *realistic* are all correct US English already. A rewrite keyed on the
+stems those words share with their British-spelled cousins would have mangled all four across the
+catalog. The pairs list holds exact forms only, and those four words were confirmed unflagged before
+the rewrite was run.
+
+**`LICENSE` is never rewritten.** It carries the canonical MIT text, which is not ours to edit.
+
+**It exposed a latent bug rather than creating one.** Converting `CONTRIBUTING.md` to the US
+spelling of *license* immediately failed `check-provenance.py`, whose `\bMIT License\b` marker had
+never matched the British form. The provenance check had been passing that file **by accident** —
+anyone
+writing it the American way would have failed the build, for a reason that would have been
+baffling.
+
+Fixed with a deliberately narrow waiver: the `MIT License` marker alone is waived, in
+`CONTRIBUTING.md` and `README.md` alone, because naming our own license in our own documentation is
+expected. Every other marker still applies to those files, verified by planting a third-party
+copyright notice in one and Apache text in the other — both still caught.
+
+**The naming consequence.** The PMO department's display title becomes *Program Management Office*.
+The slug `pmo` and the skill addresses are unaffected, so nothing anyone could have installed
+changes.
+
+---
+
+## D29. Publishing the org chart so the README can link to it — ✅ Resolved
+
+The README now leads with a screenshot of the org chart. The screenshot is honest but static; the
+value is in the live page, and **GitHub does not render HTML from a repository** — a link to
+`docs/org-chart.html` shows a reader the source, not the chart.
+
+- **(a) GitHub Pages, serving `/docs` from `main`.** ← **chosen**
+- (b) A third-party HTML preview proxy.
+- (c) Screenshot only, no link.
+- (d) A hosted site on a purchased domain.
+
+**Recommendation: (a).** Free on public repositories, one setting, and it republishes on every push
+— so the live chart tracks the generator with no extra step. The URL becomes
+`https://cbrock84.github.io/headcount/org-chart.html`, which is what the README already points at.
+
+- **(b) rejected.** Depends on someone else's service staying up, and the URL is unpresentable.
+- **(c) rejected** as the default, though it is what you get until (a) is enabled: the screenshot is
+  the flair, the live page is the substance.
+- **(d) is D25 revisited and still premature** — Pages costs nothing and needs no domain.
+
+**Two consequences worth knowing before enabling it.**
+
+1. Pages serves everything in `/docs`, so the decision log and use cases become browsable as raw
+   files. The repository is already public, so nothing is newly exposed; it is only more visible.
+2. `docs/index.html` redirects the site root to the chart, so
+   `https://cbrock84.github.io/headcount` works rather than presenting a directory listing.
+
+**This also reopens the Website field from D25**, which was left empty for want of anything worth
+pointing at. A live, self-updating org chart is exactly that, at no cost and with none of the
+credibility risk of a degraded TLD. If Pages is enabled, the Website field should be set to the
+Pages URL. D25's reasoning about domains is unchanged: still not worth buying one.
+
+**Until enabled**, the README's two links to the Pages URL are dead. That is the one cost of
+shipping this before the setting is flipped, and it is a single line to revert if you would rather
+not publish a site.
+
+**To enable:** Settings → Pages → Source: *Deploy from a branch* → Branch: `main`, folder `/docs`.
+
+**Resolution: (a), enabled before the repository was made public.** Verified live rather than
+assumed: `/org-chart.html`, the site root and `/USE-CASES.md` all return 200, and the published
+chart reads 172 skills — the current count — so Pages is republishing on push as (a) predicted.
+The README's two links are live, not dead.
+
+**This entry sat open long after the work was done**, and was read back as current state. An open
+decision that is not open is worse than no entry, because it is trusted. Close a decision when the
+thing is done, not when someone next reads the log.
+
+---
+
+## D30. Coverage QC against public occupational taxonomies — ✅ Resolved
+
+Two questions, settled together: whether the cross-organization repository sweep was worth running,
+and whether the catalog covers what a medium-to-large business actually contains.
+
+**The sweep is dropped.** A manual pass over those repositories found little beyond
+overlap with GRC roles already covered by `legal-risk` and `security`. Work-queue items 8 and 9 are
+closed rather than deferred — a deferred item nobody intends to do is worse than a closed one,
+because it keeps appearing in every review.
+
+**Coverage was validated against external taxonomies rather than intuition.** Judging one's own
+catalog complete by inspection reliably finds the functions the author already thought of. The
+references used were the **BLS Standard Occupational Classification** major groups 11-0000
+(Management Occupations) and 13-0000 (Business and Financial Operations Occupations) — public,
+cross-industry, and the standard instrument for exactly this question.
+
+**Eight gaps found, all built.** Six were functions the taxonomy names and the catalog did not
+cover:
+
+| Function | SOC codes | Why it was missed |
+|---|---|---|
+| `operations:procurement-and-sourcing` | 11-3061, 13-1023 | Judged covered by `vendor-management`, which is post-contract only. Two separate SOC codes point at the pre-contract discipline; that judgment was wrong. |
+| `finance:tax` | 13-2081, 13-2082 | Zero coverage across nine finance skills. |
+| `people:benefits-and-leave` | 11-3111, 13-1141 | `compensation-and-leveling` covers pay bands, not health, retirement or leave. |
+| `legal-risk:regulatory-compliance` | 13-1041 | Already named as a gap; the taxonomy confirmed it. |
+| `operations:facilities-and-workplace` | 11-3013, 11-9141 | Zero coverage. Also absorbs the administrative-services function from 11-3012, so D12's dissolution of the `administration` department stands. |
+| `marketing:events-and-field-marketing` | 13-1121 | Seventeen marketing skills and no events. |
+
+**Two more were internal inconsistencies the taxonomy did not find and a structural check did.**
+Every department carried a department-head skill except `it-operations` and `pmo` — the two added
+most recently. Their charters had been written to anchor on an arbitrary skill instead, which is a
+workaround I introduced rather than a gap I reported. Fixed with
+`it-operations:chief-information-officer` and `pmo:head-of-pmo`, and both charters now anchor on
+their head like every other.
+
+The CIO skill also states the CTO/CIO boundary explicitly, which D27 split but never wrote down in
+a skill: the CIO runs the technology the company works *on*, the CTO the technology it *sells*.
+
+**What was deliberately not built.** The industry-specific management occupations in SOC 11-9000 —
+education, medical, food service, lodging, gambling, funeral, agricultural and construction — are
+correctly absent from a cross-industry core and belong to the vertical variants in D8. Labor and
+union relations (13-1075) and industrial production management (11-3051) are real but weighted
+toward manufacturing, logistics and retail, so they go to the verticals too.
+
+**Remaining Tier 1**, recorded in the org chart's gaps section: customer experience depth, legal
+depth, corporate strategy depth, and product discovery and prioritization. None is a missing
+function; all are thin coverage of a function already present.
+
+---
+
+## D31. Authority as a second axis on the surface map — ✅ Resolved
+
+The surface map answers where an agent may write. It has never answered whether that write may
+land without a decision, and the two are not the same question. In practice the second one was
+settled per dispatch, from memory, by whoever happened to be driving — which is the condition the
+surface map itself exists to eliminate.
+
+- **(a) A fourth roster column, checked by the guard.** ← **chosen**
+- (b) State it in each charter. Prose inside the agent being governed; nothing checks it, and it is
+  invisible at the moment it matters, which is the dispatch.
+- (c) Infer it from class. Conflates "cannot write" with "may not land unreviewed" — a reviewer is
+  ungated precisely because it cannot write, and a builder's blast radius has nothing to do with
+  its class.
+- (d) Leave it implicit. The status quo, and the reason this was raised.
+
+**Resolution:** (a). Three values — `autonomous` (dispatch it and take the result), `proposes` (the
+orchestrator surfaces the diff before landing it), `escalates` (do not dispatch it unasked; the
+work itself is the decision).
+
+**Eighteen of nineteen rows are `autonomous`, and that is the honest answer rather than a
+placeholder.** A department writes only inside its own plugin directory, where the worst outcome is
+a bad skill in one department. Marking rows gated to make the column look load-bearing would be the
+decoration this repository rejects everywhere else.
+
+**The one exception is `repo-meta`, and it is a real one.** It owns the CI workflows, the check
+scripts, every generator the documents are built from, and the surface map itself. A wrong change
+under `plugins/finance/**` is wrong in one department. A wrong change to `scripts/check-all.sh` can
+make every other check stop reporting, and nothing downstream would fail to say so. That is the
+shape of thing worth a checkpoint.
+
+**Two invariants are enforced rather than described**, both catching a row that reads as governed
+while governing nothing: a reviewer may not be gated, because it holds no write surface to gate;
+and a gated builder must own a surface. Both were verified against deliberately broken maps rather
+than assumed — an unproven guard is a comment claiming to be a guard.
+
+**Existing maps keep working.** The column is optional and omission means `autonomous`, but `check`
+reports which rows defaulted, so a map that never considered the question stays distinguishable
+from one that answered it. The value here is not the single gated row; it is that the axis is now
+expressible and checked instead of remembered — the same argument that justified the surface map.
+
+## D32. Extending the skill-reference checker to skill bodies — ✅ Resolved
+
+`scripts/check-skill-refs.py` verifies that every `` `department:skill` `` reference resolves. It
+scans `README.md`, `CONTRIBUTING.md` and `docs/**` — and nothing else. Skill files themselves are
+not scanned, so the 131 cross-references inside `plugins/**/SKILL.md` have never been checked.
+
+**Four of them were broken**, found by running the checker's own logic over the skill tree:
+
+| Reference | In | Actual problem |
+|---|---|---|
+| revenue:revenue-recognition | `finance:tax` | Wrong department prefix |
+| legal-risk:risk-and-controls | `legal-risk:chief-legal-and-risk-officer` | Skill never existed |
+| customer-experience:churn | `revenue:chief-revenue-officer` | Skill never existed |
+| operations:incident-management | `operations:chief-operating-officer` | Skill never existed |
+
+All four are fixed on this branch. The first three were retargeted; the fourth was a genuine
+capability gap and `operations:incident-management` now exists, which is what the reference always
+promised a reader.
+
+That leaves the checker itself, which is `repo-meta` — the one row on the surface map carrying
+`proposes` under D31, so the change is surfaced here rather than made.
+
+- **(a) Extend the checker to scan `plugins/**/SKILL.md` as well.** ← **chosen**
+- (b) Leave it. Skill-to-skill references stay unchecked, and the next broken one is found by a
+  reader rather than by CI.
+- (c) Extend it, but as a warning rather than a failure. Keeps CI green while surfacing rot; also
+  means nothing ever forces the fix, which is how the four above accumulated.
+
+**Recommendation: (a).** The checker's own docstring says a reference to a skill that no longer
+exists is a broken promise to a reader and that nothing else in the tree catches it. That argument
+does not weaken inside a skill file — it strengthens, because that is where readers follow
+references from. The measured cost is zero: 131 references, four failures, all now fixed, no
+false positives from ordinary prose.
+
+**Why it is not simply done here.** The argument that a draft pull request is itself the surfacing
+`proposes` calls for does not hold up. It would license any `repo-meta` change made overnight,
+which collapses `proposes` into `autonomous` and makes the single non-default row on the roster
+decorative — precisely what D31 refused. Note the contrast with this log entry, which is also a
+`repo-meta` write under `docs/**` and is fine because it was explicitly asked for. Same surface,
+different authorization.
+
+**One consequence worth knowing before choosing (a).** CI runs `check-all.sh` on every pull
+request, so the extension turns any unresolved reference into a red build immediately — including a
+forward reference written to a skill that has not been created yet. That is the intended behavior,
+but it changes what writing a cross-reference costs.
+
+
+**Resolution: (a).** The checker now scans `plugins/**/SKILL.md` alongside the documentation.
+Coverage went from 99 references to 244, and the tree is clean at the point of the change because
+the four broken ones were fixed when they were found.
+
+The cost named in this entry is now live: a reference written to a skill that does not exist yet
+fails CI immediately. That is the intended behavior, and it means a forward reference has to be
+written after the skill it points at, not before.
+
+## D33. US English check rejects the plural of "analysis" — ✅ Resolved
+
+`scripts/check-us-english.py` maps the British spelling of the verb *analyze* and its inflections to
+the American forms. One of those inflections collides with the plural of *analysis*, which is spelled
+identically in both dialects and is ordinary American English. Writing a sentence about several
+pieces of analysis therefore fails the check, and `--fix` rewrites the noun into the third-person
+verb form, producing a sentence that is not English in any dialect.
+
+Caught while writing `data-analytics:quantitative-analysis`, where that plural is the natural word
+in the opening line. Worked around by rephrasing, so nothing fails today.
+
+**Two things make this worth more than a shrug.** The `--fix` path corrupts correct text rather
+than merely flagging it, which is worse than a plain false positive. And the check has no exemption
+for code spans or quoted text, so the defect cannot be described in any file the check scans —
+this entry has to talk around the word rather than name it, which is the clearest demonstration of
+the problem available.
+
+The same noun/verb collision exists in principle for the *practice* and *license* families, where
+British English splits the spelling by part of speech. Both British forms are in the word list, so
+the same trap is set for anyone writing about either.
+
+- **(a) Drop the colliding inflection from the word list.** ← **chosen.** A one-line change.
+  The British verb is rare in this library's register; the noun plural is common.
+- (b) Skip matches inside backticks and block quotes. Fixes the describability problem for every
+  word at once, and leaves the false positive in ordinary prose where it actually bites.
+- (c) Make the rule context-sensitive on the preceding word. More precise, and more machinery than
+  a spelling check should carry.
+- (d) Leave it and rephrase around it, as was done here. Costs nothing today and quietly shapes
+  what people are able to write.
+
+**Recommendation: (a), and consider (b) alongside it** — they solve different halves and neither
+excludes the other. This is repo-meta and carries `proposes` under D31, which is why it is logged
+rather than fixed. It is independent of D32; either can be taken alone.
+
+
+**Resolution: (a).** The colliding inflection is gone from the word list; the British verb and its
+past form remain. Verified both directions — a sentence using the plural noun passes, and one using
+the British verb is still caught.
+
+(b), the code-span exemption, was not taken. It solves a narrower problem than it appears to: the
+reason this entry could not name the word was that the whole file is scanned, and (a) removes that
+constraint for this word without adding machinery. The exemption is worth revisiting if a second
+word hits the same wall.
+
+## D34. Two skills claim social graphics — ✅ Resolved
+
+Found by a promise-versus-coverage sweep of all 172 descriptions. `product:presentation-design`
+says "to design a banner, social graphic, or one-pager". `marketing:visual-content` says "create
+social graphics" and covers carousels, infographics, quote graphics and social imagery in depth.
+
+Both are legitimately scoped — one is about carrying an argument in a laid-out artifact, the other
+about visual assets that carry content — but they compete for the same trigger, which is the
+failure `technology:skill-authoring` calls the silent killer. A request to design a social graphic
+can load either, and they give different advice.
+
+The two sit in different departments, so resolving it moves work across surfaces rather than within
+one. That is why it is logged rather than decided.
+
+- **(a) Narrow `presentation-design` to decks and one-pagers**, and drop the social and banner
+  claim from its description. ← **chosen.** `visual-content` is substantially deeper on that
+  material — it covers format selection, carousels, infographics and generation prompts, where
+  `presentation-design` gives it two paragraphs. The narrower skill also matches its own body,
+  which is organized as decks first and everything else second.
+- (b) Narrow `visual-content` instead, leaving all static graphic design in product. Inverts the
+  depth: the shallower treatment would own the topic.
+- (c) Merge them. They are genuinely different jobs — an argument in slides versus an asset in a
+  feed — and merging produces one skill that triggers on both and serves neither well.
+- (d) Leave both. The overlap keeps costing a wrong load occasionally, at no fix cost.
+
+**Recommendation: (a).** It is a description change in one skill, no content moves, and it aligns
+each skill's trigger with where its depth actually is.
+
+**One adjacent overlap was fixed rather than logged**, because it sat inside a single department
+and was introduced by this branch: `corporate-strategy:portfolio-strategy` claimed "decide market
+entry or exit" while the new `corporate-strategy:market-entry` covers entry properly. The
+portfolio skill's description now says exit only, which is what its body is about.
+
+
+**Resolution: (a).** `presentation-design` now covers decks and one-pagers, and points at
+`marketing:visual-content` for social graphics, carousels and infographics. The description and the
+body both moved, so the trigger and the content agree.
+
+The one-pager section kept its last bullet in changed form. It had been about a social graphic at
+thumbnail size; it is now about a one-pager's real reading contexts — printed, attached, projected —
+which is the same lesson applied to the surface this skill actually keeps.
+
+---
+
+## D35. Whether description shape is a checkable convention — ✅ Resolved
+
+An outside read of all 172 skills reported that descriptions do not follow one pattern. Some open
+with a capability sentence and then a `Use this to…` trigger sentence; some run the two together;
+some name a sibling skill to route away from, most do not. Two checks already constrain
+descriptions — a minimum length, and the promise-versus-coverage relationship that D34 came out of
+— but nothing constrains their shape.
+
+This is a convention question rather than a defect, and it touches every skill in the tree, so it
+is logged rather than decided.
+
+- **(a) Leave shape unconstrained.** ← **chosen.** The two checks that exist catch the
+  failures that actually cost something: a description too thin to route on, and a description
+  that promises what the body does not cover. Shape is not one of those. Normalizing 172
+  descriptions to a template would be a large diff whose only beneficiary is the reader of the
+  diff.
+- (b) Fix a two-sentence template — capability, then trigger — and normalize all 172, with a check
+  to hold it. Consistent, and the check is easy to write. It is also 172 files of churn for a
+  problem no one has reported hitting.
+- (c) Require only the trigger sentence, leaving the rest free. Half the discipline for a third of
+  the churn, but "a sentence beginning `Use this`" is the part a checker can verify and the part
+  that matters least — the trigger's *content* is what routes, and no check can read that.
+
+**Recommendation: (a).**
+
+**Resolution: (a).** Nothing changes in the tree. The two checks that exist stay the whole of what
+is enforced about a description: it must be substantial enough to route on, and it must not promise
+what the body does not cover. Shape is left to whoever writes the skill.
+
+Recorded so the next full read does not re-raise it as a defect: the variation is deliberate, not
+drift. A description that names a sibling skill does so because that pair actually collides; one
+that runs capability and trigger together does so because the sentence reads better that way. A
+template would flatten both, and the part a checker can verify — that a sentence beginning `Use
+this` exists — is the part that matters least. What routes a request is the trigger's content, and
+no check can read that.
+
+**One item in the same report needs no decision, recorded here so the next read does not re-raise
+it.** The figure "~24 agents over a 1,500-file monorepo" in `executive:agent-hierarchy` was read as
+a claim about this roster, which currently runs 17 builders and 2 reviewers. It is not: both
+instances say the method was *extracted from* a working implementation of that size. The sentence
+describes the source the method came from, and changing the number would make it wrong.
+
+---
+
+## D36. Where emitted vertical repositories live — ✅ Resolved
+
+D8 resolved the vertical architecture to template-plus-generator with one-way emit, and roadmap item
+10 was to build it. Building it raised a question D8 did not answer: what happens to the output.
+
+Every other generated artifact in this repository — the README, the org chart, the social card — is
+committed, and a `--check` mode fails the build when the committed copy drifts from what the
+generator produces. Applying that pattern here would mean committing an entire second copy of the
+tree per vertical.
+
+- **(a) Emit to a gitignored `dist/`, and verify by emitting to a temporary directory and running
+  the emitted repository's own checks against it.** ← **chosen**
+- (b) Commit the emitted tree and `--check` it like the other generated documents. Consistent with
+  the existing pattern, and reviewable in a diff. It also roughly doubles the repository per
+  vertical, and — decisively — puts a hand-editable copy of the output in front of every
+  contributor, which is the one thing D8's rule forbids. A `--check` failure would read as "the
+  generated copy is stale" long after someone had already edited it.
+- (c) Emit straight to the downstream repository from CI. Removes the local copy entirely, at the
+  cost of making every push to this repository a publish. Publishing should be a deliberate act.
+
+**Resolution: (a).** The invariant worth holding is not "a stored copy matches the generator" but
+"the generator produces a repository that is sound." `--verify` states that directly: it emits into
+a temporary directory, initializes it the way a consumer's clone would be, runs the emitted
+repository's checks, and keeps nothing. CI runs it on every push, so the emit cannot rot unnoticed.
+
+**Two consequences worth recording.**
+
+The emitted repository does not carry the three document generators or their checks. Its README is
+written by `build-vertical.py`, so a "README is current" check downstream would be verifying the
+wrong generator; freshness is guaranteed upstream instead. It carries the other seven checks, which
+still mean what they say about a tree of skills.
+
+`verticals/**` is a new surface with its own owner, and it is the second row marked `proposes`. A
+change inside a department is wrong in one department of one repository. A change inside a vertical
+is emitted into a distributable repository carrying industry-specific advice, and because the emit
+is one-way, nothing downstream can correct it locally. The generator itself stays with `repo-meta`
+alongside the other scripts — writing industry advice and maintaining the tool that ships it are
+different jobs.
+
+---
+
+## D37. Authoritative sources as a catalog of references — ✅ Resolved
+
+A skill states what a competent practitioner knows. It does not state what the regulator published
+last month, and it cannot: the catalog is written once and the obligation moves. The ask was for
+each skill to carry the outside authorities an agent should check in real time — tax guidance,
+employment law by jurisdiction, security control catalogs, standards bodies, public datasets.
+
+The framing offered was "open source or MIT/Apache licensed sources." Investigating that turned out
+to be the decision, because **most of what a professional must cite is not open**, and the examples
+named make the point: ISO standards are sold, SANS papers are copyrighted, the FASB Codification is
+free only behind an account. What *is* freely usable is narrower and more valuable than it looks —
+US federal works are public domain by statute, statutes and regulations are uncopyrightable as
+government edicts, and EU legal texts are reusable with attribution.
+
+So the catalog cannot be a list of things we may copy. It has to be a list of things an agent may
+*read*, each carrying what it may then do with what it read.
+
+- **(a) A catalog of references, with a closed license vocabulary, emitted per skill.** ← **chosen**
+- (b) Vendor the material that permits it — US public-domain control catalogs, CISA KEV — so a
+  skill works offline. Reverses D3 and D6, needs a carve-out in the provenance check, and
+  reintroduces the staleness the catalog exists to remove: a snapshot of a live feed is wrong the
+  day after it is taken.
+- (c) Put the URLs inline in each skill body. No new machinery, and no way to check that a link
+  still resolves, no way to record what may be done with it, and one source serving three
+  departments becomes three copies to update.
+
+**Resolution: (a).** `sources/*.toml` maps a source to the skills whose answers it settles.
+`scripts/build-sources.py` emits each skill's list into its own `references/sources.md`, which is
+where Claude Code and ChatGPT both load a skill's supporting files from on demand — so the agent
+gets its own sources and not the other 171 skills'.
+
+**The license class is the load-bearing field**, and it is a closed vocabulary the checker enforces.
+Three of its ten values — `free-to-read`, `registration-required`, `paywalled` — exist specifically
+to mark the sources most often assumed open and not. An entry classed wrongly as open invites an
+agent to reproduce text it was only ever allowed to cite. The emitted file states the consequence in
+the imperative next to each source rather than leaving it to a table elsewhere.
+
+**Three things were built to keep it honest rather than merely present.**
+
+A skill with sources must carry a `## Sources` section, and a skill carrying one must have sources.
+Without that pairing the feature rots in both directions at once — a file nobody is told about, or a
+pointer to a file no longer emitted. The check enforces it both ways.
+
+Reachability is checked weekly on its own schedule, not on every push. A publisher being briefly
+down is not a reason to fail an unrelated pull request, and a check that fails for reasons outside
+the diff is a check people learn to ignore. All 37 initial URLs were verified reachable before the
+`checked` dates were claimed, and three were wrong at first writing.
+
+The provenance check gained a narrow waiver, because a file whose job is to classify licenses must
+be able to name license families. It waives the *names* only; actual license text is still caught by
+its body, which the waiver was tested against by pasting some in and watching it fail.
+
+**Coverage is `security`, `legal-risk` and `finance` first** — the three departments where citing
+the authority changes the answer rather than decorating it. Extending it is adding entries, not
+changing the mechanism.
+
+---
+
+## D38. Running in ChatGPT as well as Claude Code — ✅ Resolved
+
+The ask was to port the catalog so it works outside Claude Code. Checking what a port now requires
+turned out to make the decision, because the answer changed: **ChatGPT reads the same `SKILL.md`** —
+YAML frontmatter with `name` and `description`, a body, and optional `scripts/`, `references/` and
+`assets/` alongside. There is no content to port. What differs is where each tool looks for the
+manifests that describe a bundle.
+
+| | Plugin manifest | Marketplace |
+|---|---|---|
+| Claude Code | `plugins/<dept>/.claude-plugin/plugin.json` | `.claude-plugin/marketplace.json` |
+| OpenAI / Codex | `plugins/<dept>/.codex-plugin/plugin.json` | `.agents/plugins/marketplace.json` |
+
+- **(a) A second set of manifests over the same tree, generated and `--check`ed.** ← **chosen**
+- (b) Emit a standalone `headcount-openai` repository, the way `build-vertical.py` emits verticals.
+  Consistent with the machinery already built, and wrong here: a vertical emits a *different*
+  catalog, while this would emit the same 172 skills twice. Two install sources for identical
+  content, and every skill fix needing a re-emit before it reaches half the users.
+- (c) Commit a `Codex/` copy of the tree. This was offered to the repository as a contribution. It
+  is the fork D8 rejected, and the copy was a month stale before it was reviewed.
+
+**Resolution: (a).** Sixteen small manifests, a marketplace file and an `AGENTS.md`, all generated
+from the Claude manifests and the tree, all verified by `--check`. One clone installs in either
+tool, and a skill fixed once is fixed for both because there is only one copy of it.
+
+**Two things this settles beyond the mechanism.**
+
+The per-department split stops being merely tidy and becomes required. ChatGPT budgets skill
+descriptions at roughly 8,000 characters; 172 descriptions is about 50,000. Installing the whole
+catalog at once was never the intended use and on that surface it is not a possible one.
+
+`AGENTS.md` is generated rather than written, because it states counts. It is read by Codex, Cursor,
+Gemini CLI and Copilot among others, and describes the repository to an agent working *on* it —
+which is a different job from the skills, which describe how to do the work of a function.
+
+**The Codex category vocabulary is not published**, and Codex's own marketplace uses a small set of
+broad labels. Every department here is a business function, so all sixteen carry one conservative
+label rather than sixteen guesses. Revisit if a vocabulary is documented.
+
+---
+
+## D39. A vertical that brings its own department — ✅ Resolved
+
+The education vertical was the second one built, and it immediately failed in a way industrial never
+could. Industrial's skills belong to `operations` and `people`, which already exist; the generator
+only ever had to add skills to departments it was already emitting. A curriculum function has no
+home in a cross-industry core, because it is not a thinner version of anything every company has.
+
+- **(a) Let a vertical declare a department, and have the generator do everything a new department
+  requires.** ← **chosen**
+- (b) File the education skills under an existing department — `product`, as curriculum-as-product,
+  or `operations`. Needs no code, and misroutes every request that reaches it: a question about
+  standards alignment loading a software product skill is the silent-collision failure
+  `technology:skill-authoring` names.
+- (c) Add `education` to the core, excluded from every other vertical. Puts a department nobody
+  outside one industry wants into the default install, and inverts the exclusion list from a rare
+  exception into the normal case.
+
+**Resolution: (a).** A `[[department]]` entry in the vertical config, and the generator does what
+the surface map requires of a new department because nobody is there to do it by hand: the plugin
+manifest, the marketplace entry, the roster row, the surface block, and the charter — all in the
+same emit, which is the rule the map states for a new department.
+
+**Two adjacent things this exposed and fixed.**
+
+Vertical skills were being copied as a lone `SKILL.md` rather than as a directory, so a skill's
+`references/` never shipped. That went unnoticed while no vertical skill had any; the source catalog
+gave education four that do, and the pointer would have shipped without its target.
+
+The catalog could not reach a vertical's skills at all, because it resolved `department:skill` only
+against `plugins/`. That was backwards: a vertical is where an outside authority matters *most*,
+since the advice is industry-specific and therefore regulated by somebody. Both the checker and the
+emitter now resolve against the core and every vertical.
+
+**The emitted map drops the `verticals` and `sources` rows.** Their inputs stay upstream, so
+downstream those rows would claim paths that are not there — a map that governs nothing, which is
+the condition the authority column was added to eliminate.