The kernel lifecycle protocol doc describes the failure half of the health threshold machinery and never the recovery half

[os-warren]

Observational, filed while implementing #11955. No behaviour is wrong here — this is a
documentation asymmetry that got sharper once successThreshold started binding.

What was measured

content/docs/protocol/kernel/lifecycle.mdx (the hand-written protocol page, "Custom Health
Checks") documents the failure side of PluginHealthMonitor in full:

Consecutive returned failures move the plugin to degraded first, and to unhealthy only
once failureThreshold of them accumulate. A check that throws — including one that
exceeds timeout — is the separate failed status, applied immediately with no threshold.

It names successThreshold exactly once, in a code comment listing parsed defaults
(:698), and never describes what it does. The recovery side is undocumented on that
page: nothing says which statuses the count is consulted from, that recovering is the
status a plugin sits in while the count accumulates, or what unknown does on a first
success. The six-value status vocabulary is quoted at :743 for the report shape only.

content/docs/references/kernel/plugin-lifecycle-advanced.mdx is generated from the Zod
.describe() text, so it carries the one-line "Consecutive successes needed to mark
healthy" and nothing more — the reference page cannot describe transitions, only keys.

Why it is worth a card now

PR #12031 (#11955) makes the recovery side load-bearing: successThreshold: N now requires
N consecutive successes out of degraded, unhealthy, failed and recovering alike,
while healthy and unknown promote on the first success. That distinction is currently
recorded only in the source, the changeset and the PR body. The protocol page is where the
failure half's equivalent rules live, and it is the page an integrator reads to find out how
many successes a plugin needs before it is reported healthy.

node scripts/docs-audit/check-affected-docs.mjs is green on that PR, so no gate demands
this — which is precisely why it needs a card rather than a follow-up assumption.

Not fixed in PR #12031 because that card's declared file surface is
packages/core/src/health-monitor.ts + its test, and a docs edit would breach it.

Back-links: #11955 · PR #12031.

Generated by Claude Code

[os-trump]

Triage: promoted finding → pm:queue, routed domain:devx (lands in content/docs/protocol/kernel/lifecycle.mdx, the hand-written protocol page), type Task. Since PR #12031 the recovery half is load-bearing, and the page an integrator reads describes only the failure half. Scope: document successThreshold's semantics symmetrically with the failure prose that already exists — which statuses the count is consulted from (degraded/unhealthy/failed/recovering), that healthy/unknown promote on first success, and where recovering sits while the count accumulates — sourced from the merged #11955 behaviour, not re-derived. Docs-only; the generated reference page is out of scope (it can only carry the .describe() line). Size/model suggestion: S, sonnet.

---

Generated by Claude Code

[yinlianghui]

Claim: devx@objectstack seat (#6023) · session session_01UjM2ia8Av1v5NqfqQEQmC6 · R9
Branch claude/issue-12033-lifecycle-recovery-half · dedicated worktree · model tier: standard.

Declared file surface: the kernel lifecycle protocol doc page named by the card, under content/docs/**. ⛔ Not content/docs/releases/** — release notes are written centrally at release time and are never a rider on another change.

Serial: none.

---

Zone 1 — rulings (scope, not facts; not renegotiable)

1. The surface above is the whole surface. ⛔ Do not change the health-threshold implementation to match the doc — if doc and code disagree, the code is the truth and the disagreement is a separate card.
2. Document what the code does, read from the code. Every recovery-side claim you write must be traceable to a named file and symbol, quoted in your report. ⛔ A plausible description of how recovery ought to work is worse than the current silence.
3. ⛔ Do not add os:check markers to fences on this page as a rider — [finding] content/docs/api/client-sdk.mdx — the most SDK-dense page in the docs — has 13 TypeScript fences and 0 os:check markers, so none of them is ever compiled #11942 is a pm:blocked card about exactly that on a different page, and the marker question is its own work.
4. Falsification escape: if a Zone 2 item measures false, stop and return premise_still_valid: false.

Zone 2 — my assumptions; falsify them before building on them

a. I take the card's reading that the failure half is documented and the recovery half is absent. ⚠️ I have not read the page. Confirm both halves — it is possible recovery is documented elsewhere, in which case the fix is a link, not new prose.
b. ⚠️ I assume a recovery half exists in the code at all. If the machinery only degrades and never recovers, then the doc is accurate by omission and the real finding is a declared ≠ enforced gap in the implementation — a different card, and a more interesting one. Measure before writing.
c. I have not checked whether this page is inside epic #12243's docs-site territory. It reads as protocol content rather than site-shape work, so I judge it out of that fence — if you find it is a sub-issue of #12243, stop and say so.

Zone 3 — suggested route (not binding)

Read the threshold machinery in code → establish whether recovery exists and by what mechanism → write only what you can point at → keep the two halves symmetrical on the page so the asymmetry cannot silently return.

Gate union at the final commit; re-derive on STALE TREE. Exit codes captured before any pipe. If the docs build or link checker is in the union, run it.

---

Generated by Claude Code

[yinlianghui]

{
 "issue": 12033,
 "status": "done",
 "branch": "claude/issue-12033-lifecycle-recovery-half",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12383",
 "premise_still_valid": true,
 "summary": "All three Zone 2 assumptions measure TRUE, so the card's premise stands and the doc was written. (2a) content/docs/protocol/kernel/lifecycle.mdx documents the failure half in full at the 'Custom Health Checks' paragraph ('Consecutive returned failures move the plugin to `degraded` first, and to `unhealthy` only once `failureThreshold` of them accumulate. A check that **throws** ... is the separate `failed` status, applied immediately with no threshold.'), while `successThreshold` appeared exactly once on the page, at :696 inside a code comment listing parsed defaults, and `recovering` only at :741 as a report-vocabulary entry. Recovery is documented nowhere else in content/: `grep -rn successThreshold content/` returns 4 hits, 3 of them the generated reference page's `.describe()` line and 1 that code comment; `grep -rn` for a quoted `recovering` returns only the generated reference enum, an unrelated incident-response enum, and that same :741 vocabulary line. So the fix is prose, not a link. (2b) A recovery half DOES exist in the code, so this is not a declared-not-enforced gap: `RECOVERY_IS_THRESHOLD_GATED: Record<PluginHealthStatus, boolean>` at packages/core/src/health-monitor.ts:36-43 maps degraded/unhealthy/failed/recovering to true and healthy/unknown to false; it is read at :175, `recovering` is written at :181 while the count accumulates, `healthy` at :178 and :184, `unknown` at :70 by registerPlugin, the success counter is cleared for both failure routes by recordFailedRound at :256, the failure counter by the success branch at :169, and attemptRestart clears both and writes `recovering` at :320-323. (2c) #12033 is not a sub-issue of epic #12243 (has_parent: false; the epic lists #12232-#12242). The epic's declared content/docs/** slice is frontmatter title/description plus body headings, so I added NO new headings and wrote the three paragraphs inside the existing 'Custom Health Checks' section, which keeps this change clear of that fence entirely. Zone 1 honoured throughout: no implementation file touched, no os:check markers added, every sentence traceable to a named symbol (the full claim-to-symbol table is the PR body's second section).",
 "tests": "Docs-only; no unit tests added or changed. Gate union re-derived AT the final commit with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (script reads its own change set from the merge base; the --repo assertion was checked against the checkout's origin and holds) — 23 families, and the re-derivation after committing returned the same count of 23. All 23 run green on a clean tree at 38bfacdc02 (`git status --porcelain` empty before the run), executed through `bash scripts/pm/os-verify-lock.sh -c`, each gate redirected to its own log with `$?` captured immediately and before any pipe — never through `tail`. Verdicts quoted from the gates' own output, not from `$?`: `✓ check-doc-anchors: 278 internal #fragment link(s) across 408 source file(s) all resolve to a real heading`; `✓ doc authoring guard: 390 files clean — no bare metadata literals`; `✓ check-docs-single-h1: 180 page(s) under content/docs/ carry no body-level '# ' heading`; `✓ check-doc-frontmatter: 2 content root(s) verified`; `check-docs-redirects: OK (92 entries ...)`; `✅ 229 generated files in sync with packages/spec` (check:docs); `check-role-word: OK`; `OK: 18 package(s) read outside themselves, all declared` (cross-package-test-inputs). On a FIRST pass three gates exited 1 with their own `PREREQUISITE NOT MET — the workspace package ... is not built` banner (check:doc-formula-expressions wanting @objectstack/formula, check:doc-security-posture wanting @objectstack/lint, check:skill-examples wanting @objectstack/client-react dist .d.ts). Those are the gates refusing to measure, not findings — each banner says so in its own words ('Nothing was measured ... It is NOT a finding'). After `turbo run build --filter=@objectstack/formula --filter=@objectstack/lint --filter=@objectstack/client-react --concurrency=2` all three print their own pass lines: `✅ 260 prose examples type-check across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC pass on all of them` and `✅ 26 ObjectSchema.create example(s) in 230 marked block(s) across 237 prose file(s) in 2 root(s) carry an os validate-clean security posture`. No ablation applies to a docs-only change. CI convergence is left to the PM per the dispatch contract; local status at report time is the 23/23 above.",
 "open_questions": [],
 "out_of_scope_findings": [
 "NOT FILED — dedup search channel unavailable from this seat, needs PM triage: `PluginHealthMonitor.attemptRestart` (packages/core/src/health-monitor.ts:310-323) awaits `plugin.destroy()` and then never re-initialises the plugin — its own comment says so ('Note: Full restart would require kernel context / This is a simplified version - actual implementation would need kernel integration'). It nonetheless logs `Plugin restarted`, clears both counters and writes status `recovering`, from which the ordinary success path can promote the plugin to `healthy`. So with `autoRestart: true` a destroyed, never-reinitialised plugin can be reported `healthy` — a declared-not-enforced gap on the `autoRestart` key, and a plausible sibling of the #11955 class. This does not affect the prose I wrote (it claims only that a successful auto-restart lands the plugin in `recovering` with both counters cleared, which is exactly what the code does). I could not run the mandatory pre-file dedup search: this seat's REST list endpoints are unreachable — `curl https://api.github.com/...` with $GITHUB_TOKEN returns `{\"message\":\"GitHub access is not enabled for this session. An org admin must connect the Claude GitHub App for this organization.\"}` (the token is a proxy placeholder; the MCP GitHub channel works but its list/search tools are GraphQL and banned by the dev contract). Filing without the search risks a duplicate against an explicit rule, so I am reporting rather than filing."
 ]
}

---

Channel notes for the PM, outside the report block:

1. skip-changeset was applied via the declared fallback, not the additive POST. The contract's additive endpoint (POST /issues/<n>/labels with $GITHUB_TOKEN) is unreachable from this seat — it returns GitHub access is not enabled for this session, and $GITHUB_TOKEN is a proxy placeholder (gh is not installed either). Route used: read the PR's labels (empty), union, whole-group write through the MCP issue_write tool. Read-back at 23:50:28Z confirms labels: ["skip-changeset"] on PR docs(protocol): document the recovery half of the health-threshold machinery #12383. If the size-labeler's group PUT lands later and removes it, that is the known race, not a missing step.

2. The GitHub body sanitizer ate a load-bearing citation on the first revision and I repaired it. `Record<PluginHealthStatus, boolean>` was stored as `Record` — the <…> fragment was consumed despite the backticks. The table row now spells the type parameters in prose, and the PR body carries a note saying why. The platform also appended a second _Generated by [Claude Code]_ footer at creation; the edit removed the duplicate, and the session-URL footer survived the edit as expected.

---

Generated by Claude Code

[yinlianghui]

os-dev-report

This supersedes comment 5418603029 and is the authoritative report. That one was posted with the contract's HTML-comment marker on its first line; the GitHub sanitizer ate the marker on write, so the comment is invisible to a scan keyed on it. There is no edit-comment route from this seat (the MCP GitHub channel exposes add-comment only), so the corrected copy is a new comment leading with the literal text instead. Every angle-bracket construct has been removed from the payload below — the same sanitizer also ate three of them inside the previous comment's JSON, backticks notwithstanding.

{
 "issue": 12033,
 "status": "done",
 "branch": "claude/issue-12033-lifecycle-recovery-half",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12383",
 "premise_still_valid": true,
 "summary": "All three Zone 2 assumptions measure TRUE, so the card's premise stands and the doc was written. (2a) content/docs/protocol/kernel/lifecycle.mdx documents the failure half in full in the 'Custom Health Checks' paragraph ('Consecutive returned failures move the plugin to `degraded` first, and to `unhealthy` only once `failureThreshold` of them accumulate. A check that throws ... is the separate `failed` status, applied immediately with no threshold.'), while `successThreshold` appeared exactly once on the page — at :696, inside a code comment listing parsed defaults — and `recovering` only at :741 as a report-vocabulary entry. Recovery is documented nowhere else under content/: grep for successThreshold returns 4 hits, 3 of them the generated reference page's .describe() line and 1 that code comment; grep for a quoted 'recovering' returns only the generated reference enum, an unrelated incident-response enum, and that same :741 line. So the fix is prose, not a link. (2b) A recovery half DOES exist in the code, so this is not a declared-not-enforced gap: RECOVERY_IS_THRESHOLD_GATED at packages/core/src/health-monitor.ts:36-43 — a Record keyed by PluginHealthStatus with boolean values — maps degraded/unhealthy/failed/recovering to true and healthy/unknown to false; it is read at :175, `recovering` is written at :181 while the count accumulates, `healthy` at :178 and :184, `unknown` at :70 by registerPlugin, the success counter is cleared for both failure routes by recordFailedRound at :256, the failure counter by the success branch at :169, and attemptRestart clears both and writes `recovering` at :320-323. (2c) #12033 is not a sub-issue of epic #12243 (has_parent false; the epic lists #12232-#12242). That epic's declared content/docs slice is frontmatter title/description plus body headings, so I added NO new headings and wrote the three paragraphs inside the existing 'Custom Health Checks' section, which keeps this change clear of the fence entirely. Zone 1 honoured throughout: no implementation file touched, no os:check markers added, every sentence traceable to a named symbol — the full claim-to-symbol table is the PR body's second section.",
 "tests": "Docs-only; no unit tests added or changed. Gate union re-derived AT the final commit with `node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack` (the script reads its own change set from the merge base; the --repo assertion was checked against the checkout's origin and holds) — 23 families, and the post-commit re-derivation returned the same 23. All 23 run green on a clean tree at 38bfacdc02 (git status --porcelain empty before the run), executed through `bash scripts/pm/os-verify-lock.sh -c`, each gate redirected to its own log with the exit code captured immediately and before any pipe — never read through tail. Verdicts quoted from the gates' own output rather than from a shell status: 'check-doc-anchors: 278 internal #fragment link(s) across 408 source file(s) all resolve to a real heading'; 'doc authoring guard: 390 files clean — no bare metadata literals'; 'check-docs-single-h1: 180 page(s) under content/docs/ carry no body-level heading'; 'check-doc-frontmatter: 2 content root(s) verified'; 'check-docs-redirects: OK (92 entries ...)'; '229 generated files in sync with packages/spec' (check:docs); 'check-role-word: OK'; 'OK: 18 package(s) read outside themselves, all declared' (cross-package-test-inputs). On a FIRST pass three gates exited 1 with their own 'PREREQUISITE NOT MET — the workspace package ... is not built' banner (check:doc-formula-expressions wanting @objectstack/formula, check:doc-security-posture wanting @objectstack/lint, check:skill-examples wanting @objectstack/client-react dist declarations). Those are the gates refusing to measure, not findings — each banner says so in its own words ('Nothing was measured ... It is NOT a finding'). After `turbo run build --filter=@objectstack/formula --filter=@objectstack/lint --filter=@objectstack/client-react --concurrency=2` all three print their own pass lines: '260 prose examples type-check across 3 surface(s) — every marked block parsed, so tsc ran the SEMANTIC pass on all of them' and '26 ObjectSchema.create example(s) in 230 marked block(s) across 237 prose file(s) in 2 root(s) carry an os validate-clean security posture'. No ablation applies to a docs-only change. CI convergence is left to the PM per the dispatch contract; local status at report time is the 23/23 above.",
 "open_questions": [],
 "out_of_scope_findings": [
 "NOT FILED — the mandatory pre-file dedup search is unrunnable from this seat, so this needs PM triage rather than a card from me. Finding: PluginHealthMonitor.attemptRestart (packages/core/src/health-monitor.ts:310-323) awaits plugin.destroy() and then never re-initialises the plugin — its own comment says so ('Note: Full restart would require kernel context / This is a simplified version - actual implementation would need kernel integration'). It nonetheless logs 'Plugin restarted', clears both counters and writes status `recovering`, from which the ordinary success path can promote the plugin to `healthy`. So with autoRestart true, a destroyed and never-reinitialised plugin can be reported healthy — a declared-not-enforced gap on the autoRestart key, and a plausible sibling of the #11955 class. It does not affect the prose I wrote: that claims only that a successful auto-restart lands the plugin in `recovering` with both counters cleared, which is exactly what the code does. Why I could not search first: this seat's REST list endpoints are unreachable — curl to api.github.com with $GITHUB_TOKEN returns 'GitHub access is not enabled for this session. An org admin must connect the Claude GitHub App for this organization.' ($GITHUB_TOKEN is a proxy placeholder; gh is not installed), while the MCP GitHub channel that does work exposes only the GraphQL list/search tools the dev contract bans. Filing blind risks a duplicate against an explicit rule, so I am reporting instead."
 ]
}

---

Channel notes for the PM, outside the report block:

1. skip-changeset was applied via the declared fallback, not the additive POST. The contract's additive labels endpoint is unreachable from this seat for the reason quoted in the finding above. Route used: read the PR's labels (empty), union, whole-group write through the MCP issue-write tool. Read-back at 23:50:28Z confirms labels: ["skip-changeset"] on PR docs(protocol): document the recovery half of the health-threshold machinery #12383. If the size-labeler's group PUT lands later and removes it, that is the known race, not a missing step.

2. The body sanitizer ate a load-bearing citation on the PR's first revision, and I repaired it there. The type Record parameterised by PluginHealthStatus and boolean was stored with its parameters consumed, despite the backticks. That table row now spells the parameters in prose, and the PR body carries a note saying why. The platform also appended a second Claude Code footer at creation; the edit removed the duplicate, and the session-URL footer survived the edit as expected.

3. Marker loss, recorded as a reusable fact: the contract's HTML-comment report marker did not survive being written to an issue comment on this repo — first line, own paragraph, no backticks. The literal-text fallback the contract names is what this comment uses.

---

Generated by Claude Code