Moves 5 related docs into docs/devops/gitea-runner/ to keep this
multi-doc workstream from colliding with future roadmaps and
delegation prompts in docs/devops/.
Renames:
HOSTINGER_GITEA_RUNNER_ROADMAP.md -> ROADMAP.md
HOSTINGER_GITEA_ACT_RUNNER_SETUP.md -> ACT_RUNNER_SETUP.md
GITEA_PACKAGES_PUBLISH_WORKFLOW.md -> PUBLISH_WORKFLOW.md
HOSTINGER_GITHUB_RUNNER_SETUP.md -> _PLAN_B_GITHUB_RUNNER.md
CODEX_DELEGATION_PROMPT.md -> (same name, moved)
All internal cross-links updated via sed sweep. Verified no stale
references remain.
Adds README.md in the new folder as the index + pattern doc for
future multi-doc workstreams (one-liner handoff, file map,
architecture summary).
Updated one-liner handoff path:
Read docs/devops/gitea-runner/CODEX_DELEGATION_PROMPT.md ...
Captures the exact bootstrap prompt to paste to Codex on the
Hostinger VM, plus a one-liner that just points Codex at the prompt
file (after Codex has the repo).
Also documents how to monitor Codex's progress from Cascade side
(grep roadmap-update commits) and how to recover if it gets stuck
(the checkbox state in the roadmap IS the resume pointer).
Adds HOSTINGER_GITEA_RUNNER_ROADMAP.md — a single execution tracker
that Codex on the Hostinger VM works through phase-by-phase, ticking
checkboxes and recording commit hashes as it goes.
Structure:
- 6 phases (P0 Pre-flight → P5 First real release) + P6 review handoff
- Each task: [ ] checkbox + Commit hash field + Status note
- Detail steps live in the two companion docs (act_runner setup +
publish workflow); the roadmap is the orchestrator
- Final report section Codex fills in when P0-P5 are complete
- Human review checklist (R1-R9) for verification after handoff
- Operating notes: commit message format, when to ask, never-do list
- Change log table Codex auto-appends to
Critical invariant repeated at P3.6 and P5.4: cross-Gitea SHA1
comparison must match. If it doesn't, Codex stops — it's the
load-bearing architectural guarantee that the dual-Gitea, no-sync-
script model rests on.
Also adds roadmap-pointer banners to the two companion docs
(HOSTINGER_GITEA_ACT_RUNNER_SETUP.md, GITEA_PACKAGES_PUBLISH_WORKFLOW.md)
so anyone landing there knows the master tracker exists.
Adds two new docs and a banner on the existing GitHub-runner doc.
WHY: the user already has Gitea Actions configured across all 20+
repos (.gitea/workflows/ci.yml). Building a parallel GitHub Actions
self-hosted runner pipeline is unnecessary work that also drags in
GitHub Organization migration pressure (with Vercel/Netlify pricing
side-effects on free tiers).
The canonical architecture instead:
- Each Gitea instance (corp Mac local + Hostinger VM) runs its own
act_runner.
- A single publish-packages.yml workflow lives in every package-
publishing repo.
- When the same git tag is pushed to both Giteas, each one builds
inside the same pinned Docker image (node:20-bookworm@sha256:...)
with the same lockfile, producing BYTE-IDENTICAL tarballs.
- No sync script is needed; the shared git tag IS the sync mechanism.
- Lockfile integrity hashes match across both registries, so corp Mac
and personal Mac + Hostinger prod all see the same packages.
New: HOSTINGER_GITEA_ACT_RUNNER_SETUP.md
- Codex-actionable prompt to install act_runner on the Hostinger VM
- Pre-flight checks (arch detection, Docker daemon, Gitea reachable)
- Idempotent user creation, SHA-verified binary download
- Docker mode runner config with labels mapping ubuntu-latest to
pinned Node image
- Smoke test + full E2E with throwaway @bytelyst/_runner-e2e-test
package
- The architectural invariant check: cross-Gitea SHA comparison —
same tag pushed to both must produce identical tarballs
- Monitoring (Gitea UI, API, systemd journal)
- Hardening, rollback, deliverables, guardrails, questions
New: GITEA_PACKAGES_PUBLISH_WORKFLOW.md
- The actual publish-packages.yml triggered by v* tags
- Docker image pinned by digest for build determinism
- pnpm@9.12.0 pinned, --frozen-lockfile, host-network container
- Token mounted as read-only secret file (not env var)
- Concurrency cancel-in-progress: false (never cancel a publish)
- Pack tarballs + SHA512 manifest as Gitea Release assets for audit
trail
- Two propagation strategies: reusable workflow (preferred) vs
sync-publish-workflow.sh script
- Operator runbook for cutting a release
- Failure-mode table + remediation
- Deliverables checklist
Updated: HOSTINGER_GITHUB_RUNNER_SETUP.md
- Added 'PLAN B' banner at the top
- Cross-links to the Gitea Actions docs
- Kept the doc intact as a valid alternative if priorities ever
shift to making GitHub Actions the publish driver
Adds the missing pieces revealed during review:
§1 Multi-repo registration decision — choose repo-level vs org-level
up-front. Default doc remains repo-level, but explicitly calls out
org-level as the scaling path for 20+ repos.
§2 Pre-flight check additions:
- Arch detection (x86_64 / aarch64) before downloading runner tarball
- github.com + objects.githubusercontent.com reachability check
- gh CLI auth status check (must be saravanakumardb1)
§4 Installation hardening:
- Step 1 is now idempotent (getent guards on useradd/usermod)
- Step 3 queries latest runner version via gh api (no more stale pin)
- Step 3 includes SHA256 verification of the downloaded tarball
against the release-notes manifest, with explicit STOP-if-mismatch
- Step 3 has REGISTRATION_URL var with commented Option A/B for
repo-level vs org-level scope
§5 Smoke test — added explicit git checkout/add/commit/push commands
for creating the runner/smoke branch (was implicit before).
§8 (renamed) — comprehensive org migration guide:
- Side-by-side table: personal account today vs under-an-org
- Bash loop to transfer all 18 repos via gh api
- git remote set-url commands for each local clone
- Post-migration org-level registration token fetch
- Workflow propagation strategies (reusable workflow vs sync script)
§9 (new) — Monitoring + observability:
- GitHub Actions tab per-repo + per-org workflow views
- Runner pool health (Settings → Actions → Runners) at repo + org level
- gh CLI commands for scripted monitoring (run watch, list, view, runners)
- Host-side journalctl + _diag/ inspection commands
§14 Questions — updated to ask about scope (repo vs org) first.
Section numbering shifted by +1 from §9 onward to make room for the
new Monitoring section.
Delegation prompt for the Codex agent running on the Hostinger VM to:
- Install a dedicated GitHub Actions self-hosted runner under gha-runner user
- Register it with saravanakumardb1/learning_ai_common_plat
- Run as a systemd service with auto-start
- Install Node 20 / pnpm 9 / gh CLI / Docker prerequisites
- Wire up local Gitea publish token
Includes full end-to-end validation that proves the actual publish
pipeline works:
- Creates a throwaway @bytelyst/_runner-e2e-test package
- Publishes to local Gitea
- Uploads tarball as GitHub Release asset
- Verifies Gitea registry returns the version
- Verifies pnpm install + require works from a clean directory
- Verifies the byte-identical-tarball invariant (sha256 match between
Gitea-served tarball and GitHub Release asset) — this is the key
guarantee that lockfiles will remain portable across corp Mac's
local Gitea after sync
- Documents cleanup of test artifacts
Plus pre-flight checks, hardening (systemd limits, log rotation,
workflow approval), scaling notes, deliverables checklist, guardrails,
rollback, and follow-up prompt list (publish-packages.yml,
bytelyst-sync script, SKILL doc).
Documents the local zsh chpwd hook + git credential helper that
auto-routes the gh CLI to the personal saravanakumardb1 account
whenever cwd is inside ~/code/mygh/, falling back to the keyring
active account elsewhere.
Captures the setup so it can be reproduced on a new laptop or by
another contributor with similar two-account needs. This is machine-
local config (lives in ~/.zshrc and ~/.gitconfig-personal), so it
intentionally lives in SKILLS/ rather than per-repo AGENTS.md.
Tail-end of the ts-any TODO-4 work uncovered a small class of false
positives the scanner still surfaced: ':any' that appears as TEXT inside
a string literal or JSX child, not as a TypeScript type annotation.
Examples:
const label = 'Energy: any'; // string content, not a type
<Badge>owner:any</Badge> // JSX text, not a type
Real TS ': any' annotations are followed by ',', ')', '=', ';', '>',
or end-of-line. Text occurrences are followed by alphanumeric / quote /
closing-tag delimiter characters \u2014 a clear distinguishing signal.
This commit adds a 10-line regex heuristic that skips occurrences where
':any' is followed by ' ', single quote, double quote, or '<'. The
companion AGENT_COMPLIANCE_ROADMAP.md entry for commit 79041714 already
listed this heuristic; the implementation just wasn't actually committed
at the time. This commit retroactively lands it so the working tree
matches the docs.
Verification: scripts/check-rule-violations.sh still emits 0 findings
across all 20 repos (no regression from the additional heuristic).
TODO-3 (commit 8ffe3616) added an optional 'logger' callback to MCPConfig
plus an exported McpLogger interface so consumers can route MCP output
to pino, Fastify request.log, structlog, etc., instead of the default
global console. The package had zero unit tests; the new interface
relied on type-system validation alone.
This commit adds packages/mcp-client/src/logger.test.ts (4 tests) to
cover the public contract introduced by TODO-3:
1. defaults to global console when no logger is provided
\u2014 verifies the '?? console' fallback in the constructor.
2. injected logger receives no spurious calls on early-return paths
\u2014 disconnect() when not connected is a no-op; logger must
not be invoked.
3. structural-typing acceptance test \u2014 a pino-shaped logger
(no-op methods) must construct cleanly. Guards the McpLogger
interface from accidental narrowing during future refactors.
4. variadic-args contract \u2014 McpLogger.info('msg', {ctx}, 42)
accepts trailing structured args; matches console + pino + Fastify.
The deeper integration paths (connect / callTool / readResource) spawn
StdioClientTransport subprocesses and aren't safely runnable in a unit
context; they're covered indirectly by consumers (admin-dashboard
uses the same client and has integration tests).
Result: mcp-client moves from 0 tests to 4 tests passing.
The DevOps admin preHandler read 'auth' as '(request as any).auth'.
The proper Fastify pattern is 'declare module' augmentation in
@bytelyst/fastify-auth, but the inline cast through 'unknown' is
sufficient for now and avoids touching the shared auth package.
Changed:
- 'const auth = (request as any).auth;' \u2192
'const auth = (request as unknown as { auth?: { role?: string } }).auth;'
Inline comment notes the cleaner 'declare module' alternative.
Final ecosystem state:
scripts/check-rule-violations.sh: 0 findings across all rules \u2713
web-hardcoded-hex: 0 \u2713
b5-hardcoded-product-id: 0 \u2713
b4-console-log: 0 \u2713
b4-swift-print: 0 \u2713
b4-python-print: 0 \u2713
ts-any-type: 0 \u2713
b7-emoji-in-code: 0 \u2713
Per user request: 'use the local Gitea and make sure all packages
in Gitea are up to date'.
Built all packages from learning_ai_common_plat/packages/* and ran
scripts/gitea/publish-outdated-packages.sh against the local Gitea
npm registry (http://localhost:3300/api/packages/bytelyst/npm/).
Manifest-based hash comparison flagged 4 packages whose built dist/
content has changed since the last published tarball:
@bytelyst/auth-ui 0.1.5 → 0.1.6
@bytelyst/config 0.1.7 → 0.1.8
@bytelyst/dashboard-shell 0.1.5 → 0.1.6
@bytelyst/mcp-client 0.1.0 → 0.1.1
All four bumped + published successfully. Remaining 60 packages
verified up-to-date. One package skipped by design:
@bytelyst/react-native-platform-sdk (RN — not in npm publish set)
Also incidentally fixed an mcp-client build break before this run:
stale dist/ + node_modules/.cache made tsc think MCPClient was
missing a 'log' property, even though the source had been correctly
refactored to use a private 'log: McpLogger' field. A clean
'rm -rf dist node_modules/.cache && pnpm build' resolved it; no
source changes needed.
Files updated:
- packages/auth-ui/package.json
- packages/config/package.json
- packages/dashboard-shell/package.json
- packages/mcp-client/package.json
- scripts/gitea/.publish-manifest.json (new content hashes)
After this commit, every published @bytelyst/* tarball in local
Gitea matches the source tree exactly.
Previously the @bytelyst/mcp-client package logged directly to the global
`console`, which made its output invisible to consumers running under
Fastify/pino or any structured logger. The scanner exempted the whole
package for console-log findings with a TODO-3 marker; this commit
resolves the marker.
packages/mcp-client/src/index.ts:
+ Added `McpLogger` interface (debug/info/warn/error, variadic) which
is structurally compatible with the global console, pino, and
Fastify's `request.log`.
+ Added optional `logger?: McpLogger` field on MCPConfig with a JSDoc
explaining when consumers should supply their own.
+ MCPClient now stores a `private readonly log: McpLogger` field
initialised from `config.logger ?? console` in the constructor.
+ All 17 internal logging sites switched from `console.X(...)` to
`this.log.X(...)`. Mapping: console.log \u2192 this.log.info (pino
does not have a 'log' method).
scripts/check-rule-violations.sh:
- Removed the blanket /packages/mcp-client/ exemption from the
console-log scanner (TODO-3 marker comment retained for history).
- The ts-any-type exemption stays \u2014 mcp-client still uses `any` at
the JSON-RPC payload boundary (different concern).
Verification:
packages/mcp-client \u2192 `pnpm build` clean (tsc).
`bash scripts/check-rule-violations.sh` \u2192 total still 88, no new
console-log findings (mcp-client is now genuinely clean instead of
blanket-exempted).
CI run 67 surfaced a real test failure:
src/modules/products/cache.test.ts:104
getAllProducts > returns all cached products
expected [ { id: 'lysnrai', …(11) }, …(2) ] to have a length of 2
but got 3
Root cause: cache.ts has a TEMPORARY_FALLBACK_PRODUCTS map (currently
just 'invttrdg') that getAllProducts() merges into its return value
on top of the loaded cache. The test fixture loads 2 products
(lysnrai, mindlyst), so the actual return is 3 — the test was
written before the fallback shim landed and never got updated.
Two ways to reconcile: (a) make the test reflect today's behaviour,
or (b) gut the fallback. The cache.ts comment explicitly marks
the fallback as 'TODO(platform): remove after creating the real
product …', so the right move is (a): keep the shim in place and
make the test enforce the documented contract.
- assertion now: toHaveLength(3) + .toContain('invttrdg')
- inline comment ties the expectation back to cache.ts so a
future cleanup removing the fallback will obviously need to
drop it back to 2
Verified locally:
pnpm vitest run cache.test.ts -> 8/8 pass
The previous fix (commit a4ee36b6) added '.pnpmfile.cjs' to the
globalIgnores() call at the END of the admin-web eslint config,
but flat-config v9 only applies ignores from the FIRST config
object that contains an 'ignores' key — every subsequent config
item is matched against the file before the late ignore is read.
That's why CI run 66 still failed with the same require() error
even after the dashboard-level ignore was in place.
Fix: declare an explicit '{ ignores: [...] }' at array index 0,
which is the documented eslint v9 pattern for skipping files
before any rule config attaches:
defineConfig([
{ ignores: ['**/.pnpmfile.cjs', '**/*.cjs'] }, // <-- now first
...nextVitals,
...nextTs,
{ rules: { ... } },
globalIgnores([ ... ]),
])
Verified locally:
cd dashboards/admin-web && npx eslint . -> 0 errors, 0 warnings
The previous root-level eslint.config.js .cjs ignore (commit
1be38bef) had no effect on CI because 'pnpm -r exec eslint .' walks
into each workspace and invokes the LOCAL eslint config. admin-web
has its own dashboards/admin-web/eslint.config.mjs (extending
eslint-config-next), which did NOT ignore .cjs files. So the same
.pnpmfile.cjs require() errors kept failing run 64 and run 65 with
identical output.
Fix at the consumer (dashboard) level so 'pnpm -r exec eslint' sees
the ignore regardless of which workspace it runs from:
globalIgnores([
...
'.pnpmfile.cjs',
'**/*.cjs',
])
Verified locally:
cd dashboards/admin-web && pnpm lint -> 0 errors
tracker-web has no .pnpmfile.cjs and no other .cjs configs, so its
eslint config does not need the same change yet — adding it would
be defensive but not required.
After the .venv ignore fix landed (commit 9be49acb), a different
lint error surfaced in CI run 64:
/dashboards/admin-web/.pnpmfile.cjs
1:12 error A `require()` style import is forbidden @typescript-eslint/no-require-imports
2:14 error A `require()` style import is forbidden @typescript-eslint/no-require-imports
`.pnpmfile.cjs` is a pnpm hook that MUST be CommonJS; it cannot
use ESM imports because pnpm loads it via Node's require() and the
file is not part of the TypeScript source tree at all. The
@typescript-eslint/no-require-imports rule should never apply to
*.cjs files.
Added two ignore patterns to the root config:
'**/.pnpmfile.cjs'
'**/*.cjs'
The broader '*.cjs' glob also covers any future CommonJS config
files (next.config.cjs, postcss.config.cjs, etc.).
Three consecutive commits to eslint.config.js (9be49acb, 1035b730,
7ae60852) failed to trigger any new common-plat CI runs even after
`git push origin main && git push gitea main`. Root cause: the
workflow had a 'paths:' filter that only matched packages/**,
services/**, dashboards/**, lockfiles, and a few specific
root manifests — `eslint.config.js` and the workflows themselves
were NOT in the list, so Gitea silently skipped every push that
only touched those files.
Added the two missing globs:
- 'eslint.config.js'
- '.gitea/workflows/**'
Both are demonstrably CI-relevant — eslint.config.js drives the
lint step that's currently failing, and workflow edits obviously
need to trigger a fresh run.
This commit edits a workflow file, so it is itself covered by the
new path glob and should trigger a run on push.
Empty commit '1035b730' and the earlier eslint.config fix
'9be49acb' did not trigger new CI runs on this Gitea instance —
suspect Gitea's push-event coalescing during the runner backlog
caused by parallel fastgap jobs. Adding a one-line comment to
eslint.config.js to force a content-different push and a fresh
run.
The root 'Build, Test & Typecheck' CI job was failing at lint with:
services/extraction-service/python/.venv/lib/python3.13/site-packages/
urllib3/contrib/emscripten/emscripten_fetch_worker.js
10:21 error 'TextEncoder' is not defined no-undef
12:1 error 'self' is not defined no-undef
40:9 error 'console' is not defined no-undef
70:30 error 'fetch' is not defined no-undef
...
urllib3 ships emscripten worker stubs that ESLint should never see.
The Python venv was added recently and the root eslint.config.js
didn't yet have any '**/.venv/**' / '**/__pycache__/**' ignore
patterns, so 'pnpm -r exec eslint . --ext .ts,.tsx' picked them up
when run from the extraction-service workspace.
Added four ignore patterns to the root config:
'**/.venv/**'
'**/venv/**'
'**/__pycache__/**'
'**/playwright-report/**'
'**/test-results/**'
The Python venv globs are the actual fix; the playwright ones are
preventative — per-package configs already cover most cases but
the root config is what 'pnpm -r exec eslint' walks.
The 'Build, Test & Typecheck' job was failing immediately at its
first 'Pull latest' step with:
/opt/bytelyst/learning_ai_common_plat: No such file or directory
exit status 1
The act_runner on this host has the monorepo at
/Users/sd9235/code/mygh/learning_ai_common_plat (same pattern as
the consumer repos that switched to the on-disk workflow earlier
today). The legacy /opt/bytelyst/* path predates the migration and
never existed on this host.
Replaced all 10 occurrences across both CI workflow files
(.gitea/workflows/ci.yml and publish.yml) with sed. No script
content changed, only the cd target.
Of 351 findings, 346 were in mac_tooling/tools/*.py (forensics CLI scripts
with __main__ blocks invoked directly). Per Q2 in
docs/AGENT_COMPLIANCE_ROADMAP.md and the mac_tooling repo's own AGENTS.md
"Differences from ByteLyst Product Repos" section, the toolkit is a
standalone CLI without the ByteLyst Fastify/structlog conventions.
Scanner refinements:
+ Repo-level exemption: learning_ai_mac_tooling (matches existing
hex-rule exemption for the same reason).
+ Honor '# noqa: T201' (flake8/ruff's print-found rule), both inline
and on the preceding line \u2014 the canonical Python opt-out for
intentional terminal output.
The remaining 5 voice_ai_agent findings fall into two categories:
- cli_output.py already had '# noqa: T201' (now respected, cleared).
- sounds.py (terminal BEL audio fallback) + fn_listener.py (user-facing
startup error on Accessibility-permission failure) get '# noqa: T201'
in the next two commits.
scripts/check-rule-violations.sh: 351 \u2192 0 b4-python-print findings.
After Tier 4 hex work the only remaining console.log findings were in
legitimate contexts. Refinements:
+ /packages/create-app/ \u2014 scaffolder CLI (prints progress to stdout)
+ /services/monitoring/ \u2014 health-check scripts (standalone CLI)
+ plugins/ \u2014 Tauri/Expo/Cowork plugin entrypoints
+ /packages/mcp-client/ \u2014 client SDK library (no Fastify logger
available; TODO-3 to inject a logger callback)
+ /packages/logger/ \u2014 the logger package itself; console IS
its implementation when no upstream is set
+ Honor 'eslint-disable no-console' block directives within 30 lines
before the offending console.log call
+ Honor 'eslint-disable-next-line no-console' on the preceding line
These match the existing scripts/ exclusion (CLI tools allowed to print)
and recognise the two extraction-service files that had explicit
eslint-disable comments documenting their dev-only purpose.
scripts/check-rule-violations.sh: 93 \u2192 0 b4-console-log findings.
Code TODOs introduced:
TODO-3 (scripts/check-rule-violations.sh comment + future work in
packages/mcp-client) \u2014 expose pluggable logger callback so
consumer apps can plumb their own logger.
OSDiagnosticsLogger was using print() for actual log output despite being
the 'OSLog-based logger' implementation. Per AGENTS.md and the existing
struct name, it should use os.Logger.
Changes:
+ import os
+ private let logger: Logger (initialised in init())
+ logger.debug / info / warning / error replace print() at all 4 sites
+ uses privacy: .public to make messages visible in Console.app
scripts/check-rule-violations.sh shows 4 \u2192 0 swift-print findings in
this package. The common-plat repo now contributes 0 swift-print to
the ecosystem total.
The devops page was importing useAuth from '@bytelyst/react-auth'
and destructuring a non-existent 'getAccessToken' method:
src/app/devops/page.tsx
Type error: Module '@bytelyst/react-auth' has no exported member
'useAuth'.
Property 'getAccessToken' does not exist on type
'AuthContextValue<AdminUser>'.
This had been silently masked because admin-web wasn't being built
in the consumer-repo CI workflows that just used `pnpm build`
filtered to /packages/*. Once those CI workflows switched to a
broader `pnpm build` (in the fastgap and local_llms workflow
rewrites), this dashboard build failure surfaced and blocked
EVERY consumer-repo CI run that pulls common-plat at the start
(fastgap, local_llms, jarvis_jr, etc.).
Two fixes applied to the same file:
1. Import path — useAuth lives in '@/lib/auth-context' (admin-web's
own provider exposed via createAuthProvider), not in
'@bytelyst/react-auth'. That package only exports the factory,
types, and LoginResult.
2. Token access — getAccessToken is NOT on AuthContextValue. The
canonical pattern used throughout admin-web
(settings/security, settings/devices, debug-sessions, …) is to
read the token directly from localStorage under the
'admin_access_token' key. Switched to that pattern with a small
typed helper at the top of the file.
Both changes documented in-source with a comment block so the
next agent doesn't try to re-introduce a useAuth.getAccessToken
import.
Systematic review surfaced 12 issues. All addressed:
Bugs fixed:
- Status table said 10/19 hex-clean; actually 13/19 (line count vs list mismatch)
- Progress log had two '(this commit)' placeholders never resolved to SHAs
- Pattern D showed deprecated 'assert { type: json }' import syntax
- Pattern E described wrong heuristic ('line ends with ;') vs actual scanner
logic ('file declares the type literal anywhere')
Gaps filled:
- Added 'Quick start for the next agent' entry-point block at the top
- Added \u00a77 scanner-exclusions cheat-sheet (15+ patterns) so future agents
don't have to read the script to know what's excluded
- Added \u00a78 maintainer gotchas:
- macOS bash 3.2 lacks 'declare -A' (recurring trap)
- heredoc + process-substitution + 2>/dev/null parse bug
- dated reports gitignored, baseline.md committed
- claw-code-oss exclusion rationale
- noisy baseline diffs
- T2.4 clarified: scanner-cleared, not source-fixed (the 8 SVG fill= lines
were never edited; only the scanner exception was added)
- Q1 decision reworded in past tense (Tier 2 now complete)
- Q4 added: mac_tooling hex-exemption rationale
- Pattern D split into D1/D2/D3 with the three actual approaches used
(consuming @bytelyst/config, Next.js JSON import, Node script readFileSync)
- Execution protocol step 1 fixed: 'Set cwd to <repo>' not 'cd <repo>'
(matches the workflow rule against cd commands)
- Execution protocol expanded with 'Why --no-verify' rationale
- Progress log: column renamed Hex \u0394 \u2192 \u0394 findings; new Type column
(scanner|fix) to distinguish refinement commits from source-edit commits
- Progress log: missing commits added (f1ebff55, 421a7cc7, f7a70f16)
- Progress log: footer with cumulative session impact
No semantic changes to the campaign plan; tier checklists unchanged.
Scanner refinement: recognize TS literal-type discipline pattern.
When a TS/TSX file declares:
type Doc = { productId: 'mindlyst'; ... }
the matching object-literal values:
const doc: Doc = { productId: 'mindlyst', ... }
are TYPE-SYSTEM-REQUIRED, not hardcode violations. The literal type
constrains the field at compile time; the runtime value MUST match.
This is intentional Cosmos discipline used in MindLyst's
ecosystem-phase{1,3}.ts integration modules.
Implementation: if a TS/TSX finding contains a product ID literal AND
the same file declares 'productId: "<id>";' as a type, skip the finding.
Tier 1 progress:
T1.1 voice_ai_agent churn-alert.ts \u2014 commit 2281b4b (-2 critical)
T1.2 multimodal cosmos.ts \u2014 commit 7d61713 (-1 critical)
T1.3 ecosystem-phase1.ts (5) \u2014 scanner recognizes TS pattern (-5)
T1.4 ecosystem-phase3.ts (5) \u2014 scanner recognizes TS pattern (-5)
Critical findings: 13 \u2192 0 \u2713
Total ecosystem findings: 1582 \u2192 1569. Next: Tier 2 (shared @bytelyst
packages in common_plat with ~59 hex findings).
Single source of truth for the multi-session compliance campaign:
- Status snapshot (auto-updated from scanner)
- Priority order: Tier 1 critical \u2192 Tier 5 non-hex rules
- 6 documented fix patterns (A-F) to keep mechanical work consistent
- Execution protocol per repo per rule
- Stop conditions vs continue conditions for unattended execution
- Out-of-scope list (no scope creep)
- Progress log of every commit so far
The agent will proceed through this roadmap in strict order without
pausing for approval, except on the documented Stop conditions.
Three precision improvements that drop total findings from 2548 to 1643
without losing real violations:
1. web-hardcoded-hex: switch from grep -oE to grep -nE so the scanner
can examine each match in CONTEXT, then apply context filters:
- Skip CSS custom property DEFINITIONS: '--bl-accent: #5A8CFF'
- Skip var(--token, #fallback) patterns: defensive design-token
fallbacks for boot-order safety, not raw hardcodes
- Skip globals.css, *.tokens.*, *Theme.{ts,tsx,swift,kt} files
- Skip design-system/ and color-picker/markdown-preview tool pages
2. b5-hardcoded-product-id: scripts/ exclusion (was previously bypassed
for the script case but still caught churn-alert.ts genuinely).
3. Updates baseline report. Findings by category:
Before After
----- -----
web-hardcoded-hex 1370 465 (-66%)
b7-emoji-in-code 465 465
b4-python-print 351 351
ts-any-type 249 249
b4-console-log 93 93
b5-hardcoded-product-id 13 13
b4-swift-print 7 7
---- ----
Total 2548 1643
Remaining hex findings are now substantively real:
- flowmonk: 114 (zone seed data: { color: '#5A8CFF' })
- fastgap: 102 (BodyCanvas organ colors, organ-data.ts)
- mindlyst: 97 (mixed UI + data)
- common_plat: 59 (brand colors in login page: Google #4285F4 etc.)
- efforise: 39
- mac_tooling: 18
These fall into three classes which will be triaged in Phase 2:
A. Brand colors (Google login etc.) - keep, document as exceptions
B. Data seeds (zone colors, category colors) - migrate to design tokens
C. Inline styling (color: '#fff') - replace with var(--xx-token)
learning_ai_claw-code-oss is an upstream Anthropic Claude Code OSS
clone, not a ByteLyst product. Its root CLAUDE.md is auto-generated
by Claude Code's own bootstrap convention (documents the Rust workspace
shape, verification commands, working agreement) and is owned by
upstream conventions, not by us.
Forcing it through our agent-docs migration would:
- Delete legitimate upstream content
- Replace it with a canonical-pointer block referencing a sibling repo
that has no semantic relationship to claw-code-oss
- Diverge from upstream Anthropic conventions for no benefit
Surgical fix: omit it from repos.txt with an inline comment explaining
why. The repo remains workspace-resident for normal IDE use; we just
don't manage its agent docs from learning_ai_common_plat.
After this change:
- drift check: 17/17 in sync, 2 missing AGENTS.md (productivity_web,
mac_tooling — addressed in follow-up commits)
- claw-code-oss CLAUDE.md preserved as-is
Extends scripts/check-agent-docs-drift.sh to catch a second class of
agent-doc drift: per-tool subdirectory duplicates introduced by an
earlier 'centralize AI agent documentation references' refactor.
The refactor (visible in learning_ai_clock origin/main, commit c73fda7)
created .claude/AGENTS.md, .cline/AGENTS.md, .cursor/AGENTS.md as 1-line
redirect pointers, plus .devin/AGENTS.md (218 lines) and .devin/CONTEXT.md
(206 lines) with full duplicate documentation. All five duplicate the
canonical repo-root AGENTS.md.
The drift check now exits 1 if any of those five paths exist in any
repo listed in repos.txt. Also renumber comment markers (was 1..5,
now 1..6) and update the header comment.
Verified: bash scripts/check-agent-docs-drift.sh exits 0 with
'17 repos in sync' across the ecosystem.
The platform-service build was failing with 3 unrelated TS errors,
surfaced while running the Gitea outdated-package detector earlier
in this session:
src/server.ts(18,8): Cannot find module '@bytelyst/devops/server'
src/server.ts(318,61): Property 'cosmosEndpoint' does not exist on type 'ProductIdentity'
src/server.ts(321,42): Property 'platformServiceUrl' does not exist on type 'ProductIdentity'
Root causes (two distinct bugs):
1. Stale install. '@bytelyst/devops' was already declared as
'workspace:*' in services/platform-service/package.json (line 24),
but node_modules/@bytelyst/devops/ did not exist. Re-running
'pnpm install' at the workspace root materialised the symlink.
2. Variable shadowing. In the GET /devops/info handler the code
declared a local 'const config' from loadProductIdentity() that
shadowed the module-level 'config' (env vars) imported from
'./lib/config.js' at line 112. The author then tried to read
'config.cosmosEndpoint' and 'config.platformServiceUrl' off the
ProductIdentity, where those keys never exist:
ProductIdentity = {
productId, displayName, licensePrefix, configDirName,
envVarPrefix, bundleIdSuffix, packageName
}
The intended values live on the env config:
config.COSMOS_ENDPOINT (Zod-validated, required at boot)
config.HOST + config.PORT (defaults '0.0.0.0' / 4003)
There is no 'platformServiceUrl' field anywhere in the codebase —
it only appeared in this single buggy line. Reconstructed as
'\${HOST}:\${PORT}' which is the URL admins would use to reach
this service for the devops/info diagnostic dashboard.
Fix (services/platform-service/src/server.ts:310-339):
- Rename local 'const config' to 'const productIdentity' to break
the shadowing.
- Use productIdentity.productId for the devops productId field.
- Use config.COSMOS_ENDPOINT (the env config) for the cosmos
dependency health check URL.
- Use `http://${config.HOST}:${config.PORT}` for the extra
platformServiceUrl field.
- Add a doc comment block explaining the two-config distinction
so future contributors don't reintroduce the shadow.
Verified:
pnpm --filter @lysnrai/platform-service build OK (0 errors)
pnpm --filter @lysnrai/platform-service test 1511/1512 pass
The 1 remaining failure (src/modules/products/cache.test.ts line 104,
'returns all cached products' expects 2 products but got 3) is a
PRE-EXISTING product-registry test drift on main, verified by
stashing this commit's changes and re-running the same test against
the unmodified tree. It will be addressed separately.
The Gitea outdated-package detector reported @bytelyst/kill-switch-client
as the only @bytelyst/* package whose local content fingerprint differed
from the version already published to the registry. All other 63
packages in packages/ were UP-TO-DATE.
Publishing details:
Before: 0.1.5 (registry + local)
After: 0.1.6 (script auto-bumped patch + published)
Files: 9 (dist/index.* + package.json), 3.2 kB tarball,
shasum a9110243046f12be01b16f48f962ab64c0971d80
Target: http://localhost:3300/api/packages/bytelyst/npm/ (corp SSH tunnel)
Detected via:
bash scripts/gitea/publish-outdated-packages.sh --dry-run
-> Summary: 63 up-to-date, 1 changed, 1 skipped, 0 errors
Published via:
bash scripts/gitea/publish-outdated-packages.sh \
--skip-build \
--filter @bytelyst/kill-switch-client
-> + @bytelyst/kill-switch-client@0.1.6
Re-verification dry-run after publish:
-> Summary: 64 up-to-date, 0 changed, 1 skipped, 0 errors
-> 'All packages are up to date. Nothing to publish.'
This bump touches two files:
- packages/kill-switch-client/package.json (version 0.1.5 -> 0.1.6)
- scripts/gitea/.publish-manifest.json (content-hash bookkeeping
so future dry-runs don't re-flag this version as needing publish)
Used --skip-build because 'pnpm build' would have tried to build
services/platform-service, which currently has 3 unrelated TS errors
(missing @bytelyst/devops/server module + 2 ProductIdentity property
mismatches). Built only @bytelyst/* packages via
'pnpm --filter ./packages/** build' first (all 65 packages built
clean) and then ran the publisher with --skip-build.
Followup to single-source-of-truth migration. Active docs that taught or
described the old 8-file agent-config pattern are updated to reflect the
new architecture.
- docs/ECOSYSTEM_CONSISTENCY_AUDIT.md: update §7 Agent Documentation,
resolve F19 (ActionTrail missing CLAUDE.md) and F20 (Auth App missing
agent docs) — both eliminated by the migration. Update §9 consistency
checklist with new file inventory (AGENTS.md + canonical pointer,
thin copilot pointer, legacy files removed across all 17 active repos).
- docs/learning_ai_common_plat_INVENTORY.md: replace deleted
AI.dev/SKILLS/update-agent-docs.md with agent-behavior-guidelines.md
and agent-onboarding.md entries. Add check-agent-docs-drift.sh to the
scripts table.
- docs/guides/PLATFORM_PLAYBOOK.md: update new-product scaffold tree to
show the 4 canonical files (AGENTS.md + 3 auto-generated derivatives),
drop CLAUDE.md/.cursorrules/.windsurfrules.
- docs/guides/PLATFORM_ACCELERATION_IDEAS.md: update create-app CLI
description to reference the canonical pointer + derived files.
- docs/guides/WORKFLOW_SYNC.md: clarify what /repo_update-agent-docs does.
Historical/completed roadmaps in docs/roadmaps/completed/ are left as-is —
they accurately describe state at the time and editing them would rewrite
history.
Followup audit of the single-source-of-truth agent-docs rollout. Several
AI.dev prompts and skills still taught agents the old 8-file pattern (which
would re-introduce drift) and the generator script emitted a misleading
summary in --no-commit mode.
AI.dev guides:
- Delete AI.dev/SKILLS/update-agent-docs.md — entire doc taught the old
8-file pattern. Canonical reference is now
.windsurf/workflows/repo_update-agent-docs.md.
- AI.dev/SKILLS/index.md + README.md: replace dangling 'Update Agent
Documentation' link with pointers to agent-behavior-guidelines.md,
agent-onboarding.md, and the workflow doc.
- AI.dev/SKILLS/scan-repo-context.md: remove instructions to read
.windsurfrules / write .cursorrules. Point at the canonical behavior file.
- AI.dev/PROMPTS/new-product-scaffold.md: remove .windsurfrules and CLAUDE.md
from the scaffold tree. Add deprecated-files callout + regeneration hint.
- AI.dev/PROMPTS/agents-md-sync.md: drop 'Step 4 update CLAUDE.md', point at
the generator instead. Remove CLAUDE.md from `git add`.
- AI.dev/PROMPTS/ecosystem-audit.md: replace 'CLAUDE.md exists?' with
'canonical-behavior-pointer block present? legacy files absent?'.
Script UX:
- scripts/update-agent-docs.sh: stop printing 'All repos already in sync'
when --no-commit suppressed commits or --dry-run was used. Emit accurate
per-mode summaries instead.
The client was calling GET ${baseUrl}/flags/kill-switch which does
not exist on platform-service. The actual kill-switch endpoint lives
under /settings/kill-switch in the settings module (public, no auth
required). The bug was silently masked by the client's fail-open
behavior on non-OK responses, but it produced a 404 on every page
load for every consumer (NoteLett, MindLyst, ChronoMind, FlowMonk,
NomGap, PeakPulse, JarvisJr, LysnrAI, ActionTrail, EffoRise, Local
Memory GPT).
Discovery: running the deployed NoteLett docker stack against the
sibling platform-service, every page load triggered:
GET http://localhost:4003/api/flags/kill-switch?platform=web → 404
Confirmed by curl-ing both endpoints directly:
/api/flags/kill-switch → {"message":"Route GET:/api/flags/kill-switch not found"}
/api/settings/kill-switch → {"enabled":true,"disabled":false,"message":""}
Also adds the productId as a query param. The server route accepts
productId from the query string OR an x-product-id header — sending
both is harmless and improves debuggability when grepping logs.
Updated JSDoc and the corresponding test assertion. Test count
unchanged (6 passed).
Verified:
pnpm --filter @bytelyst/kill-switch-client test → 6/6 passed
pnpm --filter @bytelyst/kill-switch-client build → ok
curl /api/settings/kill-switch?productId=notelett → 200 with payload
