Files

T

Build: Production / build (push) Failing after 12m39s

Details

fix(skills): pull upstream skill runtime resolution to stop event-loop starvation

The fork's listRuntimeSkillEntries rematerialized every skill's files from
the DB on every heartbeat run dispatch — fs.rm + fs.mkdir + per-file
readFile/writeFile, sequentially per skill. With 24 configured skills and
5 concurrent agents, this saturated the Node event loop badly enough that
executeRun continuations couldn't reach activeRunExecutions.add() within
the orphan-reaper's 5-min threshold, causing reaper to false-positive runs
as "process_lost".

Upstream's listRuntimeSkillEntries calls resolveRuntimeSkillSource, which
checks if the materialized directory already exists on disk and short-
circuits when it does. Fixes the symptom at the root.

Replaces these files with upstream/master content:
  - server/src/services/company-skills.ts
  - server/src/services/heartbeat.ts
  - server/src/services/workspace-runtime.ts
  - server/src/services/company-portability.ts
  - server/src/routes/company-skills.ts
  - server/src/routes/agents.ts
  - packages/adapter-utils/src/server-utils.ts

Pulls in supporting upstream files:
  - server/src/services/catalog-provenance.ts
  - server/src/services/skills-catalog.ts
  - server/src/services/github-fetch.ts
  - server/src/services/portable-path.ts
  - packages/skills-catalog/ (new package)
  - packages/db document_annotation_* schema + migration 0091
  - packages/shared document-annotation types/validators

Drops fork features (to be re-evaluated later):
  - Gitea/Forgejo git skill sources (server/src/services/git-source.ts deleted)
  - PAT support for private skill repos
  - Fork-specific secret-export portability extensions

Adds agentId: null to acquireRunLease test-probe call in routes/agents.ts
to satisfy the fork's environment-runtime agentId requirement (kept).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

2026-05-29 09:26:51 -04:00

4.4 KiB

Raw Blame History

name, description, key, recommendedForRoles, tags

name

description

key

recommendedForRoles

Doc Maintenance

Keep the documentation honest with minimum churn. The goal is alignment between docs and behavior, not stylistic rewrites or cosmetic re-organization. Reviewers should be able to read a diff and see "this updates docs to match recent behavior changes".

When to use

A PR or recent set of merges changed user-visible behavior: CLI flags, API shapes, default values, configuration keys, endpoints, environment variables, supported versions.
A user-reported bug traced back to outdated documentation.
A release is being cut and the docs need a pass against the merged commits.
A new feature shipped but only the engineer's PR description describes how to use it.

When not to use

The change is internal-only (private helper rename, refactor) with no user-visible impact.
You want to "improve the docs" without a behavior anchor. That is a separate scoped project, not maintenance — make a plan first.

The pass

Establish the baseline. Get the commit range you are documenting against (since last release tag, since last merged-doc commit, or since a specific PR).
Enumerate user-visible changes. Read commits and PR descriptions. List, for each change, what a user can now do differently.
Map changes to docs. For each change, find every page that mentions the affected concept. Common targets: README, CLI reference, API reference, configuration reference, migration guide, FAQ, examples.
Update precisely. Edit only the lines that need to change. Do not rewrap paragraphs you did not modify — it pollutes the diff.
Add new entries where needed. New CLI flag → CLI reference entry. New env var → configuration reference entry. New endpoint → API reference entry. Don't only add it to the changelog.
Update examples and snippets. Code blocks in docs are wrong faster than prose. Re-run any example that touches new behavior.
Write the release note. One sentence per user-visible change. Group by Added / Changed / Fixed / Deprecated / Removed. Link to the relevant PRs and docs section.
Cross-check. Search the docs for the old behavior wording and remove or update stragglers.

Style baseline

Voice: second person ("you can pass --json to ..."). Avoid "we" except in narrative pages.
Tense: present, not future. The behavior exists once shipped.
Headings: imperative ("Configure the cache") or noun-phrase ("Cache configuration"), match the surrounding page.
Code blocks: include the language tag so syntax highlighting works.
Cross-links: link the first mention of a concept on each page; do not link every occurrence.
Avoid promising future behavior. If something is unreleased, mark it experimental or omit it.

Drift detection

A doc page is drifting if any of these are true:

It documents a flag, key, or endpoint that no longer exists.
An example does not run as written.
A default value in the docs does not match the code.
A supported-versions list excludes a version the project actually supports, or includes one it dropped.
A "Coming soon" section references a feature that shipped or was cancelled.

When you find drift, fix it in the same pass and note it in the release note's Fixed group.

Release-note rules

One sentence per item. If two sentences are needed, the item is likely two items.
User impact first, internal cause second. Faster cold start (avoid full bundle download on first run) beats Refactor bootstrap loader.
Link the PR for engineering readers and the docs page for users.
Mark breaking changes explicitly: **Breaking:** prefix. Include migration steps inline or via link.

Anti-patterns

Massive doc PRs that bundle stylistic rewrites with real updates. Reviewers cannot tell which lines reflect actual behavior changes.
"Updated docs" commit messages with no detail. Make the commit say what changed and why.
Adding to the changelog without updating the reference docs the changelog points to.
Marking a feature as available before its code lands. Documentation must follow behavior, not promise it.

4.4 KiB Raw Blame History