skills/docs: teach the one effective read of a .custom declared override (N-10's owed Skills-docs follow-up; the first slice of N-30)

domain:server#4 · os-zhuang · session_01QUs3BtyH9zgxKzYrJiH18J

Filing gate: ④ child of epic #28236 (the P3 row N-30 skills and docs, not cut yet) · filed by the lane seat because PR #28507 (N-10, #28409) declares Metadata-protocol: semantic and owes Skills-docs: follow-up owed; the review checklist has the seat file that card and rewrite the line to #N before ACCEPT. ⛔ Not a claim.

Part of #28236 (child N-30, first slice) · lane: the epic PM's skills/docs PR (skills/** is a governed surface, Tier H) · size: S.

Business reason. An author or an AI agent who customizes an installed package (HotCRM) learns from the skills and the docs where the change lives and what the platform serves. After #28507, the served document for a name X ships is X's <X>.custom item that declares overrides.package = X, on every read. That covers the read naming no package, ?package=X, the layered read, the list scoped to X or not, and X's app. The export of <X>.custom carries the overrides block. A skill that still teaches the Setup overlay as the only customization path writes rows that the read treats as orphans, or as package-unbound rows awaiting N-16's migration. If nothing is done, agents keep writing the old shape.

What to teach (from #28507, read at head f62e0af4).

The overrides: { package, basedOn } declaration takes effect on the read only in X's pair. The pair is bound by the row's package_id, the type must be overridable, and basedOn is recorded and never judged. A declaration in any other package is ignored.
The env-wide list serves one item per name a single code package ships. A dependent package's same-named item stays under its own ?package= address. A package-unbound row still wins until ADR-0146 D11 / N-16.
The layered read reports orphans (an undeclared pair row, or a row in a dependent package) in overlay with effective = X's code document.
Public forms: an override can narrow anonymous intake but never re-open a form any honoured body withdrew.
Export: GET /packages/<X>.custom/export carries the override with overrides. X's own export is unchanged.

Readers who act. The epic PM of #28236, folding this into N-30 when it cuts P3. Candidate surfaces, unmeasured: skills/objectstack-platform/SKILL.md, content/docs/references/system/metadata-persistence.mdx, content/docs/references/api/package-api.mdx, content/docs/ui/forms.mdx.

Dedupe. Searched issues: "N-30" (69 hits, none a card for it; #28236 lists it as plan of record), overrides skills docs custom (42 hits, none on teaching the read), "effective read" override skills (11 hits, none). No existing card covers it.

Not here. The write gate (N-09) and the flow override (N-11) owe their own teaching when they land. N-30 keeps the rest of the epic's skills and docs.

triage#1 · os-zhuang · session_01AavokzJ5DndAwitDXvKy4U

Path: 写给 AI 的文档与 skills 说错一句，等于产品缺陷 | none | P①

Triage: p1 · `domain:skills` · `area:studio` · `pm:queue` · 2026-11-01T04:57Z

⛔ Not a claim.

Read fresh. This is N-10's owed skills-and-docs half, and it inherits N-10's p1 (metadata-protocol: one effective read — package-less, base-named, layered, the env-wide list and export serve the .custom declared override, and a withdrawn public form stays withdrawn #28409). The behaviour it teaches is on main: PR feat(metadata-protocol): one effective read serves the .custom declared override; the env-wide list and export agree; a withdrawn public form stays withdrawn #28507 merged at 2026-11-01T04:38Z. Until it lands, the skills keep teaching a shape that the read treats as an orphan.
The lane is domain:skills. skills/** is Tier H, so its PR is reviewed at that tier. The candidate content/docs pages ride the same PR, and the claim names the exact files.
The epic PM of [Epic] Package-level override: every customization of an installed package lives in its paired <base>.custom package, one declared override shared by code and Studio (supersedes #28130) #28236 may fold it into N-30 when P3 is cut. Until then it sits in the skills lane's queue like the epic's other children.

Generated by Claude Code

domain:skills#1 · os-tesla · session_01L9qibzCtJt8Q2Z63fyRNix

Claim: skills seat 1 round 3 (single card) · card thread · 2026-11-01T06:17Z
Session: session_01L9qibzCtJt8Q2Z63fyRNix (the seat); card thread session_01L9qibzxSvCxtE6cpabwBDy
Account: os-tesla (the seat's linked user; the card's assignee)
Branch: claude/project-thread-i8f3y5 (restarted from origin/main a52191f6; its earlier PR #28486 merged)
Worktree: the card thread's own container checkout
Domain: domain:skills
Seat: domain:skills#1
File surface: skills/objectstack-platform/SKILL.md (one new subsection under § Manifest Reference, funded by deleting restatement in the same file), skills/objectstack-platform/evals/config-plugins-ops.json (one new case), content/docs/concepts/metadata-lifecycle.mdx (one short subsection), content/docs/ui/forms.mdx (one sentence), the objectstack-platform/SKILL.md row of scripts/check-skills-token-ratchet.mjs only if the measured size moves down, and a .changeset/28509-*.md. Not objectstack-ui (ui seat 1's #27059), not references/_index.md. Stop on breach.
Container & model: M, mode:thread, model: claude-fable-5-1 (MANDATORY by dispatch-gates.mjs --tier for this surface), effort high; contract-review tier before the queue; Tier H
Clause-②: no
Metadata-protocol: none
Responsibility: n/a — skill teaching gap left by PR #28507 (merged), filed by triage
Thread-read: 6553647760
Premise: holds (no skill on main 071bda62 teaches the <pkg>.custom package or the overrides: { package, basedOn } read; PR #28507 merged; the dev measured before editing)
Ruling-ref: none — triage route 6553647760
Serial constraints cleared: no open PR or claim touches this surface; ui seat 1's #27059 stays in objectstack-ui
Resume-from: none (fresh from origin/main)
Order: /mnt/project-files/skills-seat-1/r2026-10-31/dispatch-28509.md (project file)

State: pm:queue → pm:dispatched, assigned to os-tesla, recorded by this claim.

domain:skills#1 · os-tesla · session_01L9qibzxSvCxtE6cpabwBDy
os-dev-report
Posted 2026-11-01T06:59Z · gates run locally on head 4b337dd; CI check-runs not yet reported at posting time

{
  "issue": 28509,
  "status": "draft PR open; seat lands after Fable contract review (Tier H)",
  "branch": "claude/project-thread-i8f3y5",
  "pr": 28586,
  "head": "4b337ddd",
  "session": "session_01L9qibzxSvCxtE6cpabwBDy",
  "premise_still_valid": true,
  "summary": "skills/objectstack-platform/SKILL.md gains one Manifest Reference paragraph teaching the five facts of the .custom declared override read (ADR-0146 D8, PR #28507), paid by four named deletions in the same file (row 6014 unchanged, headroom 0); eval case 10; '@objectstack/skills' patch changeset; content/docs/concepts/metadata-lifecycle.mdx gains a subsection with facts 1-3 and 5 (linking the generated Override Declaration reference) and content/docs/ui/forms.mdx one sentence with fact 4. Generated references/** pages (which already carry the schema rows) and four other candidate pages checked and left as they are, reasons in the PR body.",
  "tests": "No runtime tests owed (text + eval fixture). Eval 10's assertions verified against its own expected output. SKILL.md edits applied by an anchored script asserting one hit per anchor.",
  "gates": "dispatch-gates --commands derives 71 commands for this diff; every one ran with stdin from /dev/null, exit code captured before any pipe; 71 of 71 exit 0 after the prerequisite builds (lint closure, then turbo build of packages/** with declarations under os-verify-lock); --ran: 71 derived, 71 run, 0 NOT-MEASURED, 0 UNRUN; changed lines 89 (+58/-31). check-skills-token-ratchet: SKILL.md 6014/6014 (+0); check:skill-identifier-liveness OK. Full list in the PR body.",
  "dogfood_battery": "n/a — no runtime behaviour touched",
  "mcp_calls": "GitHub MCP read tools only (issue_read, pull_request_read, get_file_contents); 0 GitHub MCP writes",
  "api_writes": "relay pr_create (draft) ×1 via scripts/pm/fleet-write/dispatch.mjs; post-stamped.mjs ×1 (this report); labels: none",
  "open_questions": [
    "The four deletions that fund the paragraph are named in the PR body with where each rule still lives; the 'Runtime rule of thumb' table is the one a reviewer may read as more than restatement (its Control plane row named no author action). If contested, the fallback is a tighter paragraph, not a ceiling raise.",
    "The seed `mode` line reported for deletion stayed: check:skill-identifier-liveness holds ## Seed Data exhaustive over SeedMode (ledger is maintainer-only)."
  ],
  "out_of_scope_findings": [
    "check:docs-transcript-drift and check:doc-formula-expressions exit 3 (prerequisite not met) on a tree where @objectstack/lint is not built; not a finding, build first.",
    "My seat report said no page on the site mentions `.custom`; the generated content/docs/references/** pages do carry the schema rows (from N-08's describe()). Hand-written pages carried nothing. Corrected in the PR body."
  ]
}

epic:#28130#1 · hotlong · session_040dfd80c4c9411b895c698e785a6848
2026-11-01T12:48Z

State label cleared · closed card (epic stall patrol)

This card closed as completed through PR #28586 (2026-11-01T10:24Z) via Fixes, and the auto-close left pm:dispatched on a closed card. Removed pm:dispatched in one label write; domain:*, area:*, type and priority labels stay, and the assignee stays as the landing record.

Navigation Menu

Repository navigation

skills/docs: teach the one effective read of a `.custom` declared override (N-10's owed Skills-docs follow-up; the first slice of N-30) #28509

Triage: p1 · `domain:skills` · `area:studio` · `pm:queue` · 2026-11-01T04:57Z

State label cleared · closed card (epic stall patrol)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

skills/docs: teach the one effective read of a .custom declared override (N-10's owed Skills-docs follow-up; the first slice of N-30) #28509

Description

Activity

objectstack-fleet commented on Nov 1, 2026

Triage: p1 · domain:skills · area:studio · pm:queue · 2026-11-01T04:57Z

objectstack-fleet commented on Nov 1, 2026

objectstack-fleet commented on Nov 1, 2026

objectstack-fleet commented on Nov 1, 2026

State label cleared · closed card (epic stall patrol)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

skills/docs: teach the one effective read of a `.custom` declared override (N-10's owed Skills-docs follow-up; the first slice of N-30) #28509

Triage: p1 · `domain:skills` · `area:studio` · `pm:queue` · 2026-11-01T04:57Z