Commit 1ffcd43
skills(platform): optimization flight — orphan and pointer files removed, hooks reference linked directly, requires/engines/onEnable taught (net −3,608 tokens) (#14351)
* skills(platform): delete the orphan rules/bootstrap-patterns.md (PLAT-B-01)
`rules/bootstrap-patterns.md` had ZERO inbound links repo-wide — the only
reference to its path anywhere in the tree was its own ceiling row in
`scripts/check-skills-token-ratchet.mjs`. `SKILL.md:715-717` links only
lifecycle / service-registry / hooks-events, so nothing ever routed a reader
to it; verified with `git grep -n bootstrap-patterns` against a positive
control (`git grep -n plugin-lifecycle` hits abundantly).
Its content was already carried by SKILL.md: the driver table (:66-74 =
SKILL.md:351-357), the HTTP-layer table (:76-83 = :389-397), the "no `driver:`
key, refused at load" block plus the `defineStack validation failed` sample
(:7-31,87-105 = :209-234), and manifest required fields (:29-31,107-130 =
:327-339). Its own last line pointed back at SKILL.md.
1,093 tokens of the published bundle that no customer agent could reach.
The ceiling row goes with the file: the gate treats an unreadable ratcheted
path as RED, not as a skip (#4690) — verified by a controlled probe that
re-added the row (exit 1, "cannot read ... — red, not a skip"), then restored
the script and confirmed the restore by hash match.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
* skills(platform): link the canonical hooks reference directly, delete the pointer file (PLAT-B-02, D-04, D-05, D-06)
`rules/plugin-hooks-events.md` opened by declaring itself "a compact pointer.
Complete documentation lives in the canonical reference" and then reproduced
that reference: the event table, the `data:*` warning, the custom-hook
convention, execution order, and a DO/DON'T list. SKILL.md linked only the
pointer, so the 2,628-token canonical file sat TWO hops from the entry file
behind 985 tokens that restated it.
SKILL.md now links `references/plugin-hooks.md` directly at both sites
(`:717` and `:865`) and the pointer file is deleted with its ceiling row.
Checked before deleting: the pointer carried no fact absent from the
canonical reference or from SKILL.md — its one non-hooks item ("no circular
dependencies between plugins, both kernels throw") is already the
`Dependency resolution` row of the ObjectKernel-vs-LiteKernel table. So the
merge is a relink plus a deletion, and the compact DO/DON'T shape it had is
what now closes the canonical file.
`references/plugin-hooks.md` PATH IS UNCHANGED on purpose:
`skills/objectstack-data/rules/hooks.md:202` links to it across packages, and
that link is verified still resolving.
Paid inside `references/plugin-hooks.md`, per the shrink-only ratchet:
- PLAT-D-04 — the 7-item "Best Practices" list, every item of which
restated a span of the same file, is replaced by the compact DO/DON'T
rules-of-thumb folded in from the deleted pointer.
- PLAT-D-05 — "Hook Naming Conventions" deleted; its only new rule
(lower-case) folded into the Custom Hooks convention line.
- PLAT-D-06 — the second of two near-identical vitest blocks deleted; it
differed only in asserting `receivedData` instead of `hookCalled`.
Token deltas: references/plugin-hooks.md 2628 -> 2418 (ceiling 2628);
SKILL.md 12984 -> 12982 (ceiling 12984 — the relinked paths are shorter than
the deleted ones); rules/plugin-hooks-events.md 985 -> deleted with its row.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
* skills(platform): diet the two rules files (PLAT-D-02, D-03, D-08, B-07, C-05)
`rules/service-registry.md` 2329 -> 1754 tokens (ceiling 2331):
- PLAT-B-07 — "Well-Known Service Keys" was the SAME table as
`SKILL.md:1008-1024` with the columns inverted and only 6 of its 13 rows,
and both then repeated "the REST plugin registers no service". One table
now, in SKILL.md; this file points at it.
- PLAT-D-03 — deleted "Service Naming Conventions" (generic advice: "use
descriptive names", "avoid abbreviations"), a "Testing Service
Registration" block whose only assertions were `toBeDefined()` and
`toThrow()`, and a 10-item "Best Practices" list restating this file's own
Registration Patterns section and its `null`-placeholder paragraph.
`rules/plugin-lifecycle.md` 2404 -> 1777 tokens (ceiling 2408):
- PLAT-D-08 — the ❌/✅ "getService() in init() without a declared
dependency" lesson was already in `service-registry.md:193-223`,
differing only in the names used (CachePlugin/db-pool vs
AnalyticsPlugin/objectql) and closing on the SAME paragraph about never
registering `null`. Replaced with the rule plus a link to the one worked
pair.
- PLAT-D-02 — deleted a 10-item "Best Practices" list (items 1-7 restate
this file's own Phase 1/2/3 headings; 8-10 are generic: "version your
plugin", "use reverse domain names") and a "Testing Lifecycle" section of
two vitest blocks whose only assertions were `toBeDefined()` and
`isConnected()`.
- PLAT-C-05 — dropped this file's copy of the `data:*`-boundary warning.
The boundary was stated five times in-package; the canonical statement
stays in `references/plugin-hooks.md` and SKILL.md keeps exactly one.
No content was moved to another package: each deletion either had a surviving
in-package statement or was generic advice that changed no decision.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
* skills(platform): SKILL.md diet + the three funded additions (PLAT-A/B/C/D/E/F/G)
Deletions and rewrites (SKILL.md 12984 -> 12696 tokens, ceiling 12984):
- PLAT-B-05 — `defineStack()` was 12% down the file behind 1,441 tokens of
preamble. It (with the Manifest Reference it needs) is now the first
section after the title.
- PLAT-B-03 — "When to Use This Skill" appeared TWICE, 650 lines apart,
both restating the frontmatter. A loaded package is already selected.
- PLAT-B-06 — the package narrated its own edit history ("the original
'quickstart' skill"). A customer agent never chose between two former
skills.
- PLAT-D-07 — the CRM Blueprint restated the directory tree 18 lines above
and pointed at data / i18n territory; only its `requires:` row was
platform-specific, and that is now taught properly (F-02).
- PLAT-D-01 — the ASCII Decision Guide restated the table two lines above.
- PLAT-F-05 — `composeStacks()` had a section plus a strategies table and
ZERO usages outside `packages/spec` and its own tests; real multi-app
composition is AppPlugin registration. Reduced to a pointer at the schema,
not deleted (live surface, zero measured usage).
- PLAT-F-06 — driver-as-a-`plugins:`-entry was taught as THE canonical
bootstrap; no example config does it and the CLI wires the driver itself
from the resolved DB URL. Reframed as embedding/tests only.
- PLAT-C-01 — seeds are objectstack-data's; the copy here taught a raw
literal writing `object:` by hand, which that skill forbids verbatim.
Now a pointer PLUS the `mode` table (see below).
- PLAT-C-02 — the example object file re-taught field types in a spelling
7 of 7 real object files do not use (`export default {}` vs
`ObjectSchema.create({...})`).
- PLAT-C-04, B-04 — a restatement of the rule it delegates, and a
cross-reference to a section that documents an in-process TS API and
contains no HTTP route.
- PLAT-C-05 — SKILL.md stated the `data:*` boundary twice; one statement
remains (the one that explains the silent registration).
- PLAT-E-01, E-02, E-03, E-04 — four blocks that could not compile:
`defineStack`/`SqlDriver` used un-imported with `CrmApp`/`TodoApp`
undefined; `this.pool` on a plain object literal plus `err.message` on a
`catch` binding; a type argument naming a non-exported class from another
fence; and `{ ... }` / `{ … }` ellipsis placeholders (TS1109).
- PLAT-G-01 — v5.0 vocabulary: the runtime workspace is `environment`, not
`project`, in all five spans (skills/README.md:88; the CLI surface is
`os environments`).
- PLAT-G-03 — the `os` / `objectstack` binary alias is now stated at first
use instead of 800 lines later.
- PLAT-A-01 — the frontmatter sold "adapters" and the body refutes it 385
lines in ("There are no `@objectstack/adapter-*` packages"). Both the
description and the section heading now name the Hono HTTP layer.
- The `blank` template's "in-memory driver, Hono server" was true of the
RUNNING APP and false of the file a reader opens: the template config has
neither; both arrive from CLI auto-registration.
Additions, each paid by a deletion in this same file:
- PLAT-F-01 — `manifest.engines.protocol`, stamped into every project
`create-objectstack` emits and carried by all three example apps, was
mentioned NOWHERE in this package. One manifest row + why it is checked
before anything loads.
- PLAT-F-02 — `requires: [...]` decides which service plugins boot and was
taught as one blueprint cell and one bare word. Now a token table plus the
four rules that change what you write: precedence, declaring-is-a-demand
(hard boot error vs best-effort), `auth` implies `email`, and keep
`automation` whenever `plugins:` lists a connector.
- PLAT-F-03 — the `onEnable` export, the seam where an app binds runtime
code, used by all three example apps and documented only in
objectstack-data.
- PLAT-F-04 — `os plugin build|sign|publish`: authoring stopped at
`kernel.use(plugin)` with no path to a distributable plugin.
- PLAT-F-07 — a third answer to the kernel question: `examples/embed-objectql`
uses NEITHER kernel (`@objectstack/objectql/core`, ADR-0076).
- PLAT-A-02 — the description now names the capability key.
Generated files regenerated because the frontmatter changed, as the drift gate
demands: `skills/README.md` AND `content/docs/ai/skills-reference.mdx` (one
generator writes both; `pnpm --filter @objectstack/spec gen:skill-docs`). Both
diffs are frontmatter-derived only.
`## Seed Data` keeps its `mode` table: `check:skill-identifier-liveness`
registers that section as exhaustive over `SeedMode`, and deleting the table
made five live members unreachable (caught by the gate, fixed the author's
way — the shrink-only gap ledger is maintainer-only and was not touched). The
table now also carries the Data-loss flag on `replace` that it was missing.
PLAT-E-05 is NOT implemented — its premise is false; see the PR body.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
* skills(platform): correct the requires: provider table against the real registry (review round 1)
Contract review round 1 failed the `requires:` table I added in the previous
commit. Three defects, all mine, all from reading a bounded slice of
`CAPABILITY_PROVIDERS` instead of reading it to its closing brace:
1. `audit` named `@objectstack/service-audit`. The real entry is
`@objectstack/plugin-audit` (`AuditPlugin`), serve.ts:1473-1475.
2. `triggers` named `@objectstack/service-triggers`, which does not exist. The
entry is `@objectstack/trigger-record-change` (`RecordChangeTriggerPlugin`)
with extras `@objectstack/trigger-schedule` (`ScheduleTriggerPlugin`,
`TimeRelativeTriggerPlugin`) and `@objectstack/trigger-api`
(`ApiTriggerPlugin`), serve.ts:1506-1537.
3. "the remaining vocabulary resolves the same way" was false, and so was the
claim that the map holds 14 entries. It holds TWENTY — I bounded an `awk`
range by guess and stopped at `sms`, then reported the truncation as a
correction to the audit. The audit's "~20" was right and my correction was
the error.
The table now lists all 20 provider-backed tokens against their real `pkg`
values, and the eight remaining tokens are separated into the two mechanisms
that actually resolve them: five tier-gated tokens with NO map entry, opened by
dedicated blocks in `serve.ts` `run()` (CAPABILITY_TO_TIER docblock,
serve.ts:1166-1171), and three enterprise/cloud tokens with no open-edition
provider at all — `hierarchy-security` ships in
`@objectstack/security-enterprise` via `plugins[]`, `ai-seat` and `governance`
are cloud-runtime only (platform-capabilities.ts:57-66). 20 + 5 + 3 = the 28
tokens in `PLATFORM_CAPABILITY_TOKENS`, counted from the frozen array rather
than asserted.
The `triggers` entry's own comment carries a rule an author needs — schedule
triggers run on the job service, "so pair `triggers` with `job`" — so that is
now both a row note and the fifth rule: `triggers` alone arms record-change
triggers, and autolaunched scheduled flows stay silent without `job`.
SKILL.md 12696 -> 12871 tokens, ceiling 12984 unchanged and not raised; the
growth is paid from the headroom this flight's own deletions created.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
* skills(platform): re-point the data-hooks link ahead of the data flight's consolidation
`references/plugin-hooks.md` sent readers chasing per-record validation,
defaults and audit trails to `objectstack-data`'s `rules/hooks.md`. The data
flight (PR #14427, head 061e5f4) DELETES that file and consolidates hooks into
`objectstack-data/references/data-hooks.md`, so the reference is repointed
before it can dangle.
Now a real relative link rather than two bare file names:
`../../objectstack-data/references/data-hooks.md`, verified to resolve from
`references/` to skills/objectstack-data/references/data-hooks.md. The old text
named both `rules/hooks.md` and `references/data-hooks.md`; only the surviving
one is named now, so the span is 22 bytes SHORTER — references/plugin-hooks.md
2418 -> 2413 tokens (ceiling 2628, untouched).
`git grep rules/hooks.md` over this package returns nothing further, so this
was the only site.
Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LraLgQVGq8egUwfYZpbYt1
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 9d7f725 commit 1ffcd43
9 files changed
Lines changed: 278 additions & 792 deletions
File tree
- content/docs/ai
- scripts
- skills
- objectstack-platform
- references
- rules
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
43 | 43 | | |
44 | 44 | | |
45 | 45 | | |
46 | | - | |
| 46 | + | |
47 | 47 | | |
48 | 48 | | |
49 | 49 | | |
| |||
61 | 61 | | |
62 | 62 | | |
63 | 63 | | |
64 | | - | |
| 64 | + | |
65 | 65 | | |
66 | | - | |
| 66 | + | |
67 | 67 | | |
68 | 68 | | |
69 | 69 | | |
70 | | - | |
| 70 | + | |
71 | 71 | | |
72 | 72 | | |
73 | 73 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
419 | 419 | | |
420 | 420 | | |
421 | 421 | | |
422 | | - | |
423 | | - | |
424 | 422 | | |
425 | 423 | | |
426 | 424 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
29 | 29 | | |
30 | 30 | | |
31 | 31 | | |
32 | | - | |
| 32 | + | |
33 | 33 | | |
34 | 34 | | |
35 | 35 | | |
| |||
0 commit comments