ci(check-links): 恢复 pull_request 断链门,仅检仓内链接、advisory-first (#6028) (#6304)

* ci(check-links): 恢复 pull_request 断链门,仅检仓内链接 (#6028)

按维护者 2026-08-07 裁决恢复 `Check Links`:重新启用 `pull_request`
触发(branches: main),保留 `workflow_dispatch`,`fail: true` 不变;
方向②(留空壳写注释)已被否决,故被注释掉的 `push:` 残骸按
「declared = enforced」直接删除,而不是留在文件里继续误导读者。

⛔ advisory-first:不进 required 集,也不加 `merge_group` —— advisory
车道不该消耗合并队列容量。日后若晋级 required,必须按 #6121 的教训在
同一次改动里补上 `merge_group`,否则队列会卡在一个永不上报的必需检查上。

仅检仓内链接的机制选 `--offline`,写在调用处而不是 lychee.toml:
实测 `offline = true` 这个配置键在 lychee 0.19.1 上被静默忽略、在
action 当前钉住的 0.24.2 上才生效,确定性保证不能取决于 action 恰好
装了哪个版本。`^https?://` 这类 exclude 也不够 —— 它要逐个枚举远程
scheme,漏一个就重新引入外网依赖。

门休眠半年期间配置已经漂移到跑不起来,这次一并修好(否则恢复触发器
只会让门以 exit 3 直接死掉,连链接都不检):
- `follow_redirects` 在 0.24.2 上根本不是合法键 —— 硬解析错误;
- `include_fragments` 已从 bool 变成枚举,裸 `false` 同样硬报错,
  改为 `"none"` 保持原语义(不检 fragment)。

root-relative 链接是 content/** 的主力写法,而 lychee 在没有 root-dir
时对它们直接报错。补 `--root-dir <workspace>/content` +
`--fallback-extensions mdx,md` 之后,1286 条此前完全没被检查的
`/docs/*` 链接首次纳入检查面(134 → 1476 条被检)。原来的 `remap`
块一次都没生效过(URI 构造在 remap 之前就失败),已按 declared =
enforced 删除,能力由真正生效的 root-dir 承接。

修掉门首次真正运行后暴露的 22 条既有真断链(仅改链接目标,不改散文):
- 14 条 ADR 链接归一到仓内既有约定(29 处在用的 GitHub blob URL):
  `/adr/*` 站点路由并不存在,apps/docs 只有 /[lang]/docs 与
  /[lang]/blog 两条路由,也没有任何 /adr 重定向 —— 这些链接在线上
  就是 404;
- quick-reference 三行指向已退役 schema 的表项删除(audit.zod 按
  ADR-0056 移除、registry.zod 按 #4939 退役、graphql.zod 全仓无踪),
  并同步修正两处小节计数;connector-auth 有 schema 无页面,改为不带
  链接保留信息;plugin-security 页面在 references/kernel 而非 cloud;
- README 两处:`@objectstack/account` 已迁到 packages/apps/account;
  `service-feed` 已在 #1955 删除,整行移除。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3

* fix(spec): ADR-0020 链接改到源头 JSDoc,而不是只改生成物 (#6028)

`content/docs/references/**` 是 `packages/spec` 的生成物(文件头写着
AUTO-GENERATED — DO NOT EDIT),上一个 commit 只改了生成出来的
state-machine.mdx,下一次 `gen:docs` 就会把它冲掉 —— 由 os-regen
pre-commit 钩子当场拦下。

按 contract-first 修在生产者:`packages/spec/src/automation/state-machine.zod.ts`
的 JSDoc 里那条 ADR 链接原本写作 `../../../docs/adr/0020-...md`,从
`packages/spec/src/automation/` 出发解析到 `packages/docs/adr/...` —— 这个
目录并不存在,所以源头本身就是断的,生成物只是忠实地把它复制了出来。
改为仓内既有约定的 GitHub blob URL(全仓 29 处在用),它与文件位置无关,
生成到任何深度的目录都成立。

重新生成后 `content/docs/references/automation/state-machine.mdx` 与本次
生成输出完全一致(regen 后工作树对该文件零 diff),生成物与源头就此对齐。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3

* test(check-links): 反向验证探针 —— 故意把一条相对链接改指不存在路径 (#6028)

声明 B(咬合面)的红段:预期本次 push 让 Check Links 变红,且报错点名
content/docs/kernel/services-checklist.mdx:188 指向的
./services-probe-6028-does-not-exist.mdx。下一个 commit 会 git revert
本提交,预期转绿;最终该文件相对 origin/main 净零 diff。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3

* chore(spec): 合并 main 后按新生成器重新生成 state-machine 参考页 (#6028)

main 带来了 docs 生成器改动(changeset
`docs-gen-description-line-layout-and-nested-links`:去掉逐行空行布局、
不再把行内代码路径转成嵌套链接)。该参考页是生成物,两边都改过,
文本合并的结果并不等于生成器的输出 —— os-regen 钩子说的正是这种
「被合并但没有真正重新生成」的状态。

`gen:schema && gen:docs` 后仅此一个文件有 diff(232 个生成文件里的
1 个),内容即新生成器的输出;本单在源头 JSDoc 里改的 ADR-0020 链接
原样保留。

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01BDmDsu2575gDxeMCxXhDE3

* Revert "test(check-links): 反向验证探针 —— 故意把一条相对链接改指不存在路径 (#6028)"

This reverts commit 34b5d9f.

---------

Co-authored-by: Claude <noreply@anthropic.com>

Author: hotlong

.github/workflows/check-links.yml

@@ -1,21 +1,33 @@
 name: Check Links
 
+# Repo-internal link gate (#6028).
+#
+# `pull_request` was commented out in a59dc59e (2026-01-28) as a rider on an
+# unrelated commit, with no rationale recorded; the gate then sat dormant for
+# six months while `lychee.toml` and `fail: true` kept it looking alive.
+# Maintainer ruling 2026-08-07: restore the trigger, check REPO-INTERNAL links
+# only, and land it advisory-first (NOT in the required set) until it has shown
+# a stable green streak.
+#
+# ⛔ No `merge_group` trigger on purpose: this is an advisory lane, and an
+# advisory gate does not get to consume merge-queue capacity. If it is ever
+# promoted into the required set, `merge_group` MUST be added in the same
+# change or the queue stalls on a required check that never reports (#6121).
 on:
   workflow_dispatch:
-  # push:
-  #   branches:
-  #     - main
-  # pull_request:
-  #   branches:
-  #     - main
+  pull_request:
+    branches:
+      - main
 
 jobs:
   link-checker:
     name: Check Documentation Links
     runs-on: ubuntu-latest
+    # Least privilege: the job only reads the tree and runs lychee offline.
+    # There is no issue-filing step, and `--offline` makes zero network
+    # requests, so neither `issues: write` nor a GITHUB_TOKEN is needed.
     permissions:
       contents: read
-      issues: write
 
     steps:
       - name: Checkout repository
@@ -24,14 +36,32 @@ jobs:
       - name: Check links with lychee
         uses: lycheeverse/lychee-action@v2
         with:
-          # Use configuration file for path remapping and settings
+          # `--offline` is the internal-only mechanism, and it lives HERE rather
+          # than in lychee.toml on purpose: the equivalent `offline = true`
+          # config key is silently ignored by older lychee (measured: ignored on
+          # 0.19.1, honoured on the 0.24.2 this action pins). A determinism
+          # guarantee must not depend on which lychee the action happens to
+          # install, so it is asserted at the invocation site.
+          #
+          # Offline means only `file://` targets are resolved -- every http(s)
+          # link is reported EXCLUDED, never requested. That is what makes this
+          # gate deterministic and free of external-network flake.
+          #
+          # --root-dir is what makes ROOT-RELATIVE links checkable. Most internal
+          # links in content/** are site routes (`/docs/permissions`), and lychee
+          # hard-errors on those unless it is told which directory `/` means.
+          # The Fumadocs content root is `content/`, so `/docs/x` resolves to
+          # content/docs/x -- and --fallback-extensions supplies the .mdx/.md
+          # suffix that a site route omits. Without this pair the gate cannot go
+          # green at all: 1286 root-relative links fail as "Cannot resolve
+          # root-relative link ... provide a root dir".
           args: >-
+            --offline
+            --root-dir ${{ github.workspace }}/content
+            --fallback-extensions mdx,md
             --config lychee.toml
             'content/**/*.md'
             'content/**/*.mdx'
             'README.md'
           # Fail the job if broken links are found
           fail: true
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-

README.md

@@ -321,7 +321,6 @@ For the browser, the typed client SDK and React hooks (`useQuery` / `useMutation
 | [`@objectstack/service-analytics`](packages/services/service-analytics) | Analytics — aggregations, time series, funnels, dashboards |
 | [`@objectstack/service-automation`](packages/services/service-automation) | Automation engine — flows, triggers, and workflow state machines |
 | [`@objectstack/service-cache`](packages/services/service-cache) | Cache — in-memory, Redis, multi-tier |
-| [`@objectstack/service-feed`](packages/services/service-feed) | Activity feed / chatter |
 | [`@objectstack/service-i18n`](packages/services/service-i18n) | Internationalization service |
 | [`@objectstack/service-job`](packages/services/service-job) | Cron & interval job scheduler |
 | [`@objectstack/service-package`](packages/services/service-package) | Package registry — publish, version, retrieve metadata packages |
@@ -343,7 +342,7 @@ For the browser, the typed client SDK and React hooks (`useQuery` / `useMutation
 | [`@objectstack/cli`](packages/cli) | CLI binary (`os` / `objectstack`) — `init`, `dev`, `start`, `serve`, `compile`, `publish`, `validate`, `generate`, `lint`, `doctor` |
 | [`create-objectstack`](packages/create-objectstack) | Project scaffolder (`npx create-objectstack`) |
 | [`@object-ui/console`](https://github.com/objectstack-ai/objectui/tree/main/apps/console) | Fork-ready runtime console SPA (lives in objectstack-ai/objectui, served via `@object-ui/console` on npm) |
-| [`@objectstack/account`](apps/account) | Account & identity portal — sign in, organizations, connected apps |
+| [`@objectstack/account`](packages/apps/account) | Account & identity portal — sign in, organizations, connected apps |
 | [`@objectstack/docs`](apps/docs) | Documentation site (Fumadocs + Next.js) |
 
 ### Examples

content/blog/metadata-driven-architecture.mdx

@@ -583,4 +583,4 @@ ObjectStack is our answer.
 
 ---
 
-*Want to dive deeper? Explore our [technical specifications](/docs/specifications) or join the discussion on [GitHub](https://github.com/objectstack-ai/spec/issues).*
+*Want to dive deeper? Explore our [technical specifications](/docs/references) or join the discussion on [GitHub](https://github.com/objectstack-ai/spec/issues).*

content/docs/ai/connect-mcp.mdx

@@ -113,7 +113,7 @@ full-authority local agent, mint the key on a platform-admin or dedicated
 **service** identity; for a scoped one, mint it on a user with exactly the
 access it should have. See
 [environment variables](/docs/deployment/environment-variables#mcp-server) for
-the switches and [ADR-0101](/adr/0101-mcp-stdio-principal-admission) for the
+the switches and [ADR-0101](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0101-mcp-stdio-principal-admission.md) for the
 decision.
 
 ## What the agent gets

content/docs/getting-started/quick-reference.mdx

@@ -76,13 +76,12 @@ Plugin architecture, manifests, and kernel runtime.
 | **[Metadata Loader](/docs/references/kernel/metadata-loader)** | `metadata-loader.zod.ts` | MetadataLoaderContract | Metadata loading |
 | **[Package Registry](/docs/references/kernel/package-registry)** | `package-registry.zod.ts` | InstalledPackage, InstallPackageRequest | Package resolution |
 
-## System Protocol (19 schemas)
+## System Protocol (18 schemas)
 
 Runtime environment, logging, jobs, caching, and observability.
 
 | Protocol | Source File | Key Schemas | Purpose |
 |:---------|:-----------|:------------|:--------|
-| **[Audit](/docs/references/system/audit)** | `audit.zod.ts` | AuditEvent, AuditConfig | Audit trail logging |
 | **[Auth Config](/docs/references/system/auth-config)** | `auth-config.zod.ts` | AuthConfig | Authentication configuration |
 | **[Cache](/docs/references/system/cache)** | `cache.zod.ts` | CacheConfig | Caching layer |
 | **[Change Management](/docs/references/system/change-management)** | `change-management.zod.ts` | ChangeRequest, RollbackPlan | Change tracking |
@@ -120,7 +119,7 @@ AI/ML capabilities - agents, skills, tools, MCP exposure, RAG, and cost tracking
 | **[Usage](/docs/references/ai/usage)** | `usage.zod.ts` | AIUsageRecord, TokenUsage | AI usage and cost tracking |
 | **[Solution Blueprint](/docs/references/ai/solution-blueprint)** | `solution-blueprint.zod.ts` | BlueprintObject, BlueprintApp | Blueprint format for AI app generation |
 
-## API Protocol (19 schemas)
+## API Protocol (17 schemas)
 
 REST/GraphQL endpoints, real-time subscriptions, and discovery.
 
@@ -130,7 +129,6 @@ REST/GraphQL endpoints, real-time subscriptions, and discovery.
 | **[Endpoint](/docs/references/api/endpoint)** | `endpoint.zod.ts` | ApiEndpoint, ApiMapping | REST endpoint configuration |
 | **[Router](/docs/references/api/router)** | `router.zod.ts` | Router, Route | API routing rules |
 | **[OData](/docs/references/api/odata)** | `odata.zod.ts` | ODataQuery | OData protocol support |
-| **[GraphQL](/docs/references/api/graphql)** | `graphql.zod.ts` | GraphQLConfig, FederationEntity | GraphQL API config |
 | **[Realtime](/docs/references/api/realtime)** | `realtime.zod.ts` | Subscription, RealtimeEvent | WebSocket subscriptions |
 | **[WebSocket](/docs/references/api/websocket)** | `websocket.zod.ts` | WebSocketConfig | WebSocket protocol |
 | **[Discovery](/docs/references/api/discovery)** | `discovery.zod.ts` | Discovery, ServiceInfo | API discovery and metadata |
@@ -143,7 +141,6 @@ REST/GraphQL endpoints, real-time subscriptions, and discovery.
 | **[Analytics](/docs/references/api/analytics)** | `analytics.zod.ts` | Analytics | API usage analytics |
 | **[Documentation](/docs/references/api/documentation)** | `documentation.zod.ts` | Documentation | API docs generation |
 | **[Metadata](/docs/references/api/metadata)** | `metadata.zod.ts` | Metadata | API metadata endpoints |
-| **[Registry](/docs/references/api/registry)** | `registry.zod.ts` | Registry | API registry |
 | **[Storage](/docs/references/api/storage)** | `storage.zod.ts` | Storage | API storage operations |
 
 ## Automation Protocol (5 schemas)
@@ -188,7 +185,7 @@ Environments, marketplace, licensing, and multi-tenancy.
 | **[Environment](/docs/references/cloud/environment)** | `environment.zod.ts` | Environment, EnvironmentType | Deployment environments |
 | **[Marketplace](/docs/references/cloud/marketplace)** | `marketplace.zod.ts` | MarketplaceListing, PackageSubmission | Plugin marketplace |
 | **[Plugin Registry](/docs/references/kernel/plugin-registry)** | `plugin-registry.zod.ts` | PluginRegistryEntry, PluginVendor | Plugin registry entries and quality metrics |
-| **[Plugin Security](/docs/references/cloud/plugin-security)** | `plugin-security.zod.ts` | PluginSecurityProtocol, SBOM | Plugin security policies |
+| **[Plugin Security](/docs/references/kernel/plugin-security)** | `plugin-security.zod.ts` | PluginSecurityProtocol, SBOM | Plugin security policies |
 | **[Tenant](/docs/references/cloud/tenant)** | `tenant.zod.ts` | Tenant | Multi-tenancy isolation |
 
 ## Integration Protocol (1 schema)
@@ -214,7 +211,7 @@ Common utilities used across all protocols.
 | **[HTTP](/docs/references/shared/http)** | `http.zod.ts` | HttpRequest, HttpMethod, CorsConfig | HTTP utilities |
 | **[Identifiers](/docs/references/shared/identifiers)** | `identifiers.zod.ts` | SystemIdentifier, SnakeCaseIdentifier | Standard ID patterns |
 | **[Mapping](/docs/references/shared/mapping)** | `mapping.zod.ts` | FieldMapping | Field mapping utilities |
-| **[Connector Auth](/docs/references/shared/connector-auth)** | `connector-auth.zod.ts` | ConnectorAuthConfig | Connector auth patterns |
+| **Connector Auth** | `connector-auth.zod.ts` | ConnectorAuthConfig | Connector auth patterns |
 
 ## QA Protocol (1 schema)
 

content/docs/permissions/attachments-access.mdx

@@ -103,7 +103,7 @@ an auth service is wired, and stamp `owner_id` on the new `sys_file`.
 
 Deleting attachments does not immediately delete the underlying bytes (a file
 can be shared across records). Reclamation is handled by the platform LifecycleService via declarative
-[reap guards](/adr/0057-system-data-lifecycle-and-retention):
+[reap guards](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0057-system-data-lifecycle-and-retention.md):
 
 - **`sys_file`** — when the last `sys_attachment` referencing an
   attachments-scope file is deleted, the file is tombstoned; a reap guard

content/docs/permissions/authorization.mdx

@@ -409,16 +409,16 @@ The complete, prioritized gap map lives in issue **#2561** (the production
 
 | ADR | Owns |
 |---|---|
-| [0049](/adr/0049-no-unenforced-security-properties) | No unenforced security properties (enforce / mark / remove) |
-| [0054](/adr/0054-runtime-proof-for-authorable-surface) | Prove-it-runs — high-risk classes need runtime proofs |
-| [0056](/adr/0056-permission-model-landing-verification) | Permission-model landing: OWD, anonymous deny default, D10 matrix |
-| [0057](/adr/0057-erp-authorization-core-business-units-and-scope-depth) | Business units, scope depth, declarative RBAC seeding, platform-owned assignment |
-| [0066](/adr/0066-unified-authorization-model) | Unified model: capability registry, posture, precedence, future refinements |
-| [0068](/adr/0068-unified-user-context-and-built-in-identity-roles) | Built-in identity positions (formerly "identity roles"), `EvalUser` |
-| [0069](/adr/0069-enterprise-authentication-hardening) | Enterprise authentication hardening (phased) |
-| [0078](/adr/0078-no-silently-inert-metadata) | No inert declarable metadata |
-| [0086](/adr/0086-authz-metadata-config-boundary-and-cross-package-composition) | Metadata↔config boundary, package provenance, cross-package composition |
+| [0049](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0049-no-unenforced-security-properties.md) | No unenforced security properties (enforce / mark / remove) |
+| [0054](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0054-runtime-proof-for-authorable-surface.md) | Prove-it-runs — high-risk classes need runtime proofs |
+| [0056](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0056-permission-model-landing-verification.md) | Permission-model landing: OWD, anonymous deny default, D10 matrix |
+| [0057](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0057-erp-authorization-core-business-units-and-scope-depth.md) | Business units, scope depth, declarative RBAC seeding, platform-owned assignment |
+| [0066](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0066-unified-authorization-model.md) | Unified model: capability registry, posture, precedence, future refinements |
+| [0068](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0068-unified-user-context-and-built-in-identity-roles.md) | Built-in identity positions (formerly "identity roles"), `EvalUser` |
+| [0069](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0069-enterprise-authentication-hardening.md) | Enterprise authentication hardening (phased) |
+| [0078](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0078-no-silently-inert-metadata.md) | No inert declarable metadata |
+| [0086](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0086-authz-metadata-config-boundary-and-cross-package-composition.md) | Metadata↔config boundary, package provenance, cross-package composition |
 | 0090 | Permission Model v2: position rename + vocabulary freeze, profile removal, fail-closed OWD default + external dial, audience anchors, principal taxonomy, publish linter, delegated administration, explain engine + access matrix |
 | 0091 | Grant lifecycle: validity windows + resolution-time filtering (L1, landed), delegation, break-glass, recertification substrate |
-| [0096](/adr/0096-execution-surface-identity-admission) | Execution-surface identity admission — no data-engine call without an explicit principal (the MCP HTTP surface admits identity here) |
-| [0101](/adr/0101-mcp-stdio-principal-admission) | MCP stdio principal admission — env-supplied API-key identity, fail-closed, no `system` bypass |
+| [0096](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0096-execution-surface-identity-admission.md) | Execution-surface identity admission — no data-engine call without an explicit principal (the MCP HTTP surface admits identity here) |
+| [0101](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0101-mcp-stdio-principal-admission.md) | MCP stdio principal admission — env-supplied API-key identity, fail-closed, no `system` bypass |

content/docs/references/automation/state-machine.mdx

@@ -16,7 +16,7 @@ transition the machine never declared.
 
 The ledger carried these shapes as `authorable (p)` — provisional, because
 nobody had checked. Checking matters here more than usual, because
-[ADR-0020](../../../docs/adr/0020-state-machine-converge-and-enforce.md)
+[ADR-0020](https://github.com/objectstack-ai/objectstack/blob/main/docs/adr/0020-state-machine-converge-and-enforce.md)
 **retired this shape as a record-lifecycle declaration**: the top-level
 `workflow` metadata type and `object.stateMachines` are both gone, and a
 record's legal transitions are declared as a `state_machine` **validation