Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.aiox-core/infrastructure/scripts/codex-skills-sync/bootstrap.js:
- Around line 659-669: The code currently proceeds when loadYaml(projectRoot)
returns null, which can hide missing metadata; update the bootstrapping flow to
detect when yaml === null after calling loadYaml and emit a clear warning before
continuing with regex-only extraction (use an existing logger like
processLogger.warn if present, falling back to console.warn) so operators know
metadata may be incomplete; locate the loadYaml call and the subsequent
buildCorePlans/buildSquadPlans/dedupePlans sequence and add the warning
immediately after the loadYaml(projectRoot) assignment.
- Around line 440-457: Add short inline comments inside the squadSkillId
function to explain the purpose of each computed variable and every conditional
branch: document why alias/squadBase/entry/entryRoot are derived, why we return
coreSkillId when entry is missing, why we return `aiox-${entry}` when entry
matches or is prefixed by squadBase or alias, why genericEntryRoots are excluded
and the special handling for entryRoot prefixes and `-chief` suffixes, and why
the final fallback returns `aiox-${squadBase || alias}-${entry}` to
disambiguate; place these comments next to the variables (alias, squadBase,
entry, entryRoot, genericEntryRoots) and before each if/return to aid future
maintainers.
- Around line 202-213: The findBlockScalar function can exhibit poor performance
on extremely large inputs; add a defensive input-size guard (e.g.,
MAX_BLOCK_SCALAR_INPUT) and bail or truncate early inside findBlockScalar when
text.length exceeds that threshold, or add an optional parameter (maxLength) to
limit how much of text is scanned; ensure the guard runs before constructing the
RegExp/match to avoid catastrophic backtracking on huge payloads and
document/handle the trimmed result consistently in findBlockScalar's return
path.

In @.aiox-core/infrastructure/scripts/codex-skills-sync/README.md:
- Around line 18-23: The fenced code blocks in the README lack language
specifiers; update each opening triple-backtick for the blocks containing the
commands (the block with "npm run setup:codex-skills", "npm run
setup:codex-skills:dry", and the block with "node bootstrap.js --force" / "node
bootstrap.js --help") to include a shell/bash specifier (e.g., ```bash) so
markdown linting and syntax highlighting are satisfied.
- Around line 69-70: The README.md file ends without a trailing newline (the
final paragraph beginning "Background: students reported that squad-chief
skills..." is missing the EOF newline); update the file to ensure a newline
character is present at the end of the file so the file ends with a single
trailing newline.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.aiox-core/core/doctor/checks/ide-sync.js:
- Around line 44-53: The current construction that builds commandAgents and
skillAgents uses fs.readdirSync directly and will throw if the directory exists
but is unreadable; wrap each fs.readdirSync call in a try/catch around the
blocks that reference agentsCommandDir and agentsSkillDir (the code that assigns
commandAgents and skillAgents) so failures are caught, log or attach the error
context (including agentsCommandDir/agentsSkillDir and the operation) and fall
back to an empty array or a structured error result instead of letting the
exception bubble; ensure the filters/mapping ('.md' removal, SKILL.md lookup)
remain applied when read succeeds and that the catch branches produce the same
typed output as the success branches.
- Around line 55-80: The current check compares only counts (skillCount,
sourceCount, commandCount) which can falsely PASS; update the logic in
ide-sync.js to compare agent identity sets instead of totals by deriving unique
identifiers from sourceAgents, skillAgents, and commandAgents (e.g. agent.id or
agent.name) and computing set differences to find missing or extra agents;
replace the count-based branches (the skillCount !== sourceCount and
commandCount === sourceCount checks and the final WARN) with membership-based
checks that return WARN/FAIL when any source agent is missing from skills or
commands and include the specific missing/extra agent identifiers in the message
and appropriate fixCommand.

In @.aiox-core/core/doctor/checks/skills-count.js:
- Around line 22-26: The three bare catches around fs.readdirSync in
.aiox-core/core/doctor/checks/skills-count.js are swallowing filesystem errors
and returning 0; change each catch to capture the error (e.g., catch (err)) and
either rethrow or wrap and throw a new Error with context (include the dir path
and original err) so callers can distinguish I/O/permission failures from "no
skills found"—update the three fs.readdirSync call sites to use this explicit
error propagation instead of returning 0.

In @.aiox-core/infrastructure/scripts/codex-skills-sync/validate.js:
- Around line 64-80: extractGeneratedSquadSource currently only matches
backticked paths and misses the HTML source comment format used in generated
squad skills; update extractGeneratedSquadSource to also detect and capture the
plain HTML comment header (e.g. <!-- squads/.../agents/.../file.md -->) in
addition to the existing backtick regex, returning the captured path string when
either pattern matches so isGeneratedSquadSkill can correctly detect generated
squad files; reference the extractGeneratedSquadSource and isGeneratedSquadSkill
functions and use a second regex like
/<!--\s*(squads\/[^>]+\/agents\/[^>]+\.md)\s*-->/ (or equivalent) combined with
the current /`(squads\/[^`]+\/agents\/[^`]+\.md)`/ to support both formats.

In @.aiox-core/infrastructure/scripts/ide-sync/transformers/claude-code.js:
- Around line 41-42: The generated shim/skill metadata currently hardcodes the
agent source directory when building sourcePath (const sourcePath =
`.aiox-core/development/agents/${agentData.filename}`) which breaks non-default
IDE sync sources; change sourcePath construction to derive the base from the
agent metadata (e.g., use agentData.source or a provided source/base field with
a fallback to `.aiox-core/development/agents`) and use that computed base
everywhere the hardcoded path is used (including the other occurrence that
constructs the fallback instructions), ensuring you update both the sourcePath
declaration and the later metadata generation to reference the dynamic base (and
normalize/join paths rather than string-concatenating if available).

In @.claude/skills/AIOX/agents/aiox-master/SKILL.md:
- Around line 453-454: The guide currently references undefined command aliases
(*create-agent, *create-task, *create-workflow) which will confuse operators;
update the documentation in SKILL.md to use the actual configured command syntax
(*create {type}) or add those aliases to the command catalog. Locate the section
listing the framework dev commands (the lines showing *create-agent,
*create-task, *create-workflow) and replace each alias with the canonical form
(*create agent, *create task, *create workflow) or register corresponding
aliases that map to the existing *create {type} handler so the guide matches the
implemented command interface.
- Line 415: The Markdown at the "Epic/Story creation" heading currently uses
parentheses with asterisks that trigger emphasis (e.g. (*create-epic,
*create-story)); change those tokens to inline code by wrapping each command in
backticks (e.g. `*create-epic`, `*create-story`) so the parentheses contain code
spans instead of emphasis. Locate the line with the "Epic/Story creation" header
and replace the parenthesized tokens accordingly.
- Around line 127-163: The commands list uses inconsistent visibility types
(missing arrays, scalar values) which breaks the expected schema; normalize
every command entry (e.g., the command objects like "help", "kb", "status",
"yolo", "validate-workflow", "run-workflow", etc.) to include a visibility field
that is always an array of keys (e.g., visibility: [full] or visibility: [key,
full]) and add explicit key-visible entries where omitted so the "Available
Commands" generator can reliably read visibility; update the scalar instances
(the "yolo" entry and any other commands using scalar visibility) to the array
form and add visibility arrays for commands that currently have no visibility
field.

In @.claude/skills/AIOX/agents/data-engineer/SKILL.md:
- Around line 43-44: The commands schema is inconsistent: Step 3 expects each
command entry under the commands: section to include a visibility array checked
for the value "key", but current command objects lack the visibility field;
update all command entries (the objects in the commands: list) to include a
visibility: ["key", ...] array (or other appropriate visibility values)
consistently, or alternatively change the Step 3 logic/string in "Available
Commands" to check an existing field (e.g., a new isKey boolean) if you prefer
not to add visibility arrays; ensure every command object referenced by the
"commands" symbol and the "Available Commands" rendering uses the same shape so
the check for "key" succeeds.
- Around line 267-274: Update the outdated command names in the usage_tips:
replace references to the deprecated commands '*rls-audit', '*explain', and
'*analyze-hotpaths' with the current commands '*security-audit' and
'*analyze-performance' (use '*security-audit' for RLS/security checks and
'*analyze-performance' for explain/analyze style performance checks), and apply
the same replacements for the other occurrences noted (around the previously
mentioned lines 487-489) so all tips reflect the current command set.

In @.claude/skills/AIOX/agents/devops/SKILL.md:
- Around line 131-143: Replace the hard-coded "--base main" usage in the
CodeRabbit commands with the repository's detected default branch from
gitStatus; specifically, read the branch info available in gitStatus and
substitute that value into the coderabbit invocations found under
quality_gates.mandatory_checks (the "coderabbit --prompt-only --base main"
entry) and the pre_pr_against_main string (the shell command that includes
"~/.local/bin/coderabbit --prompt-only --base main"), so both use the dynamic
default branch variable instead of "main" (update references under
quality_gates, coderabbit_gate, and pre_pr_against_main to pull the branch value
from gitStatus).

In @.claude/skills/AIOX/agents/po/SKILL.md:
- Line 282: The relative link in the line "Reference: [Command Authority
Matrix](../../docs/architecture/command-authority-matrix.md)" is broken because
it does not ascend far enough from .claude/skills/AIOX/agents/po/SKILL.md to
reach the repository docs directory; update that markdown link to the correct
relative depth (use
../../../../../docs/architecture/command-authority-matrix.md) so the link
resolves, i.e., replace the existing link target in the Reference line
accordingly.

In @.claude/skills/AIOX/agents/qa/SKILL.md:
- Around line 262-275: The self-healing execution policy is inconsistent: the
self_healing block (self_healing.behavior with CRITICAL/HIGH: auto_fix)
contradicts the QA advisory-only stance and canExecute: false elsewhere; pick
one consistent policy and update all related symbols accordingly. Either change
self_healing.behavior entries for CRITICAL and HIGH from auto_fix to
document_as_debt (or another advisory action) to honor the QA advisory-only
policy, or flip the advisory policy/canExecute flag (set canExecute: true and
update the QA role text) so auto_fix is allowed; update the QA advisory
description and the canExecute setting to match the chosen behavior.
- Line 291: Replace the hardcoded Windows path in the runnable command string
("wsl bash -c 'cd /mnt/c/.../aiox-core && ~/.local/bin/coderabbit --prompt-only
-t committed --base main'") with the reusable project variable used elsewhere
(${PROJECT_ROOT}); edit the SKILL.md entry that contains that command and change
the cd target to ${PROJECT_ROOT} (matching the pattern used on Lines 317-318) so
the workflow is portable across environments.

In @.claude/skills/AIOX/agents/sm/SKILL.md:
- Around line 243-244: Update the two table rows that currently reference the
delegate handle "@devops" so they use the consistent handle "@github-devops";
specifically change the delegate for the "Push to remote" entry (command
`*push`) and the "Create PR" entry (command `*create-pr`) from "@devops" to
"@github-devops" so handoffs are routed consistently with the rest of the file.
- Line 237: The markdown link "[Command Authority
Matrix](../../docs/architecture/command-authority-matrix.md)" is using an
incorrect relative path; update that link in SKILL.md to point correctly (either
fix the relative path to reach docs/architecture/command-authority-matrix.md
from this file’s directory or replace it with a repo-root absolute path like
/docs/architecture/command-authority-matrix.md) so the reference resolves
properly.

In @.claude/skills/AIOX/agents/ux-design-expert/SKILL.md:
- Line 307: The commands list in SKILL.md uses mismatched placeholders (*build
{atom}, *extend {variant}) that don't match the declared command signatures
which use {component}; update the commands array entry (the line with commands:
['*build {atom}', '*compose {molecule}', '*extend {variant}']) to use the
{component} placeholder for build and extend (e.g., '*build {component}',
'*extend {component}') and scan the file for any other occurrences of {atom} or
{variant} to replace with {component} so invocation guidance is consistent with
the declared command signatures.

In `@docs/migration/ACORE-CLAUDE-SKILLS-PREFLIGHT-2026-05-01.md`:
- Line 16: The committed doc contains a workstation-specific absolute path
string "/Users/rafaelcosta/Projects/AIOX/aiox-core" in the "Repo" table cell;
replace it with a repo-relative or placeholder value (e.g., "./", "<repo-root>"
or "REPO_PATH_PLACEHOLDER") so the document no longer exposes local
user/environment details and remains portable; update the table row that
currently reads `| Repo | /Users/rafaelcosta/Projects/AIOX/aiox-core |` to use
the chosen placeholder.

---

Nitpick comments:
In @.aiox-core/infrastructure/scripts/validate-claude-integration.js:
- Around line 85-86: The current literal string check against skillContent
causes false negatives for valid YAML frontmatter variants; update the
validation to robustly detect activation_type: pipeline by either parsing the
frontmatter YAML (using a YAML/front-matter parser) or matching with a tolerant
regex that accepts optional quotes and whitespace (e.g.,
activation_type:\s*["']?pipeline["']?), and then push the error using the same
errors.push call with sourceAgent if the parsed/normalized value is not
"pipeline"; locate the check that references skillContent, errors.push and
sourceAgent to apply the change.

Verify each finding against the current code and only fix it if needed.

Outside diff comments:
In @.aiox-core/data/entity-registry.yaml:
- Around line 16322-16341: The registry entry currently maps codex-skills-sync
to the wrong file and dependency graph: the fields purpose, dependencies,
usedBy, and keywords in the entity for codex-skills-sync must reflect the real
source at .aiox-core/infrastructure/scripts/codex-skills-sync/index.js rather
than the IDE sync values shown; open the actual codex-skills-sync/index.js to
extract its real purpose string, keywords, usedBy list and dependencies (replace
entries like redirect-generator, validator, gemini-commands that belong to
ide-sync), then update the entity in entity-registry.yaml so purpose points to
.aiox-core/infrastructure/scripts/codex-skills-sync/index.js and
dependencies/usedBy/keywords match the source (or regenerate the entity from the
source file if you have a generator).

---

Nitpick comments:
In @.aiox-core/infrastructure/scripts/validate-paths.js:
- Around line 75-78: Extract the duplicate regex helper into a single shared
utility and import it where needed: create a module exporting
extractGeneratedSquadSource (the function that matches
/(squads\/[^`]+\/agents\/[^`]+\.md)/ and returns match[1] or ''), update the
current extractGeneratedSquadSource implementation in validate-paths.js to
import and use that shared function, and do the same replacement in
codex-skills-sync/validate.js so both files reference the single source of
truth.
- Around line 62-64: The current check short-circuits when content includes
GENERATED_SKILL_MARKER and generatedSquadSource is truthy, but it doesn't verify
the referenced squad source file actually exists; update the condition in the
same block to also check fs.existsSync(generatedSquadSource) (import or require
fs if not present) so the code only treats the file as a valid generated-squad
reference when the extracted generatedSquadSource path exists on disk, mirroring
the isGeneratedSquadSkill behavior in codex-skills-sync/validate.js.

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.aiox-core/development/agents/qa.md:
- Around line 263-264: The agent defines behavior tokens request_fix,
document_as_debt, and ignore but the executor (executeSelfHealingPhase and
attemptAutoFix in workflow-executor.js) ignores them; update the executor to
read the issue.behavior token and act accordingly (for request_fix call a real
auto-fix routine inside attemptAutoFix that returns true/false and applies
patch/commit, for document_as_debt create a debt record/logging path instead of
attempting fixes, and for ignore skip the issue), or alternatively remove those
tokens from the agent config so behavior tokens match actual executor
capabilities; modify executeSelfHealingPhase to branch on issue.behavior and
implement/replace the stub attemptAutoFix to perform the appropriate
fix/apply/skip logic and surface results.

In @.aiox-core/infrastructure/scripts/ide-sync/agent-parser.js:
- Around line 122-127: The guard that sets sourcePath uses relativeSourcePath &&
!relativeSourcePath.startsWith('..') but misses checking whether path.relative
returned an absolute path on Windows; update the condition that computes
result.sourcePath in agent-parser.js to also verify the relative path is not
absolute (use !path.isAbsolute(relativeSourcePath)) before converting separators
and assigning to sourcePath so cross-drive absolute paths like "D:\file.md" are
not leaked into generated files.

In @.gemini/rules/AIOX/agents/data-engineer.md:
- Around line 262-263: Update the "Typical Workflow" block to use the new
command names: replace the deprecated `*rls-audit` with `*security-audit rls`
and replace `*explain {sql}` with `*analyze-performance` (leave `*policy-apply`
as-is); make this change in the authoritative source copy of the document and
re-run the sync so the synced copy (which currently still shows `*rls-audit` /
`*explain {sql}`) is updated.

---

Duplicate comments:
In @.aiox-core/development/agents/data-engineer.md:
- Around line 262-263: Replace the stale deprecated command references
'*rls-audit' and '*explain {sql}' in the guide section with the current commands
used elsewhere (e.g., replace '*rls-audit' with '*security-audit' and '*explain
{sql}' with the appropriate '*analyze-performance' form or '*explain-plan' as
used in the repo), updating the lines that currently mention those old commands;
after making the change in the source (data-engineer.md) run npm run sync:ide to
propagate the edits to the synced copies.

In @.claude/skills/AIOX/agents/aiox-master/SKILL.md:
- Line 424: The parenthesized command tokens "*create-epic, *create-story" are
being parsed as emphasis; update the "Epic/Story creation" line to wrap each
command token in inline code backticks (e.g., `*create-epic`, `*create-story`)
so they render literally in Markdown; locate the string in the SKILL.md content
near the "Epic/Story creation" heading and replace the unquoted tokens with
their backticked equivalents.

In @.claude/skills/AIOX/agents/data-engineer/SKILL.md:
- Around line 487-489: The guide runbook still uses deprecated commands
"*rls-audit" and "*explain {sql}" — update the entries in the guide section that
reference those commands to the consolidated names "*security-audit" and
"*analyze-performance" respectively (the same names used in the usage_tips
block). Locate the guide/runbook text that contains "*rls-audit" and "*explain
{sql}" and replace them with "*security-audit" and "*analyze-performance", and
run a quick grep/search for any other occurrences to ensure consistency across
the SKILL.md.
- Around line 133-172: The commands list uses shorthand YAML scalars (e.g., "-
help: Show all available commands") while the codebase expects structured
command objects with fields like name, description, and visibility; update the
commands block so each entry is an object with explicit keys (name, description,
visibility when available) to match the aiox-master SKILL.md schema and the
activation step that checks for missing visibility metadata; ensure entries
referenced in this diff (help, guide, yolo, exit, doc-out, execute-checklist,
create-schema, create-rls-policies, create-migration-plan, design-indexes,
model-domain, env-check, bootstrap, apply-migration, dry-run, seed, snapshot,
rollback, smoke-test, security-audit, analyze-performance, policy-apply,
test-as-user, verify-order, load-csv, run-sql, setup-database, research) are
converted to objects and include a default visibility value where none is
provided so the activation logic can uniformly parse them.

In @.codex/agents/data-engineer.md:
- Around line 262-263: Replace the stale deprecated command references
(*rls-audit and *explain {sql}) with the current commands used in the source doc
and re-sync so this guide inherits the fix: update occurrences of *rls-audit to
`*security-audit rls` and replace *explain {sql} with the new analyze form
(e.g., `*analyze-performance query {sql}`), making sure to edit the source file
.aiox-core/development/agents/data-engineer.md and then re-sync to propagate the
corrected strings into .codex/agents/data-engineer.md.

---

Nitpick comments:
In `@tests/synapse/engine.test.js`:
- Around line 247-251: The test uses expect.arrayContaining([0,1,2]) which only
asserts those IDs are present and allows extras, so replace the loose subset
check with an exact membership assertion: compare engine.layers.map(l =>
l.layer) to the exact expected array [0,1,2] (or assert sorted equality) to
ensure layer 3 cannot be silently missing or extra layers added; update the test
block that references engine.layers and the layerIds variable so it asserts
equality (or length + set-equality) instead of using expect.arrayContaining.