docs: align ecosystem with release-procedure SOP + add Issue 10 troubleshooting - #745
Merged
Merged
Conversation
…ooting Cross-cutting cleanup so the operator/student/agent ecosystem references the canonical release SOP (introduced in PR #744) consistently and exposes the npm-hijack troubleshooting path to students. ## docs/guides/installation-troubleshooting.md Added Issue 10: "Pro activation failed: Installed Pro artifact did not create node_modules/@aiox-squads/pro" — the exact error that affected cohorts for 30 days before PR #742 shipped. Documents symptom, root cause (npm hijack into ancestor with package.json/workspaces), fix (5.2.6+), and a two-tier recovery procedure (simple retry first, then cache cleanup + residual-install removal if state is fouled). ## docs/guides/aiox-pro-access.md "Erros comuns" section gains an explicit entry for the install failure with a direct link to Issue 10 above. Previously the guide only covered auth-side errors; students hitting the install-side error googled into silence. ## .aiox-core/development/tasks/publish-npm.md ## .aiox-core/development/tasks/release-management.md Both converted to slim wrappers that delegate to docs/guides/release-procedure.md as the authoritative source. The full procedures previously inlined here (757 and 257 lines respectively) were missing the gotchas paid for in 11 patches across 30 days: two- system branch protection bypass, publish race conditions, Windows path escape in node -e, npm CDN propagation budget, payload sanitization for ruleset PUT, trap EXIT for atomic restore. Maintaining the full content in two files would have drifted immediately; the wrappers keep the task IDs that agent workflows reference while pointing at the one source of truth. ## .aiox-core/development/agents/devops.md Added a "Release Procedure (NON-NEGOTIABLE Reference)" section to the DevOps Guide. When @devops is invoked for a release, push, or publish that ends with a tag push to @aiox-squads/*, the agent now has explicit instruction to load and follow the SOP. Captures the institutional memory items most likely to bite (two-system protection, 4-site version bump, publish_legacy race, smoke timeout, Windows path escape) so the agent does not re-discover them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rafaelscosta
requested review from
Pedrovaleriolopez and
oalanicolas
as code owners
May 17, 2026 12:14
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
github-actions
Bot
added
area: agents
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Path: .coderabbit.yaml Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (6)
WalkthroughConsolidates release/publish documentation to a canonical SOP, updates DevOps agent and task wrappers to reference it (including a tagging snippet change), refreshes manifest hashes, and adds Pro activation troubleshooting fixed in v5.2.6. ChangesRelease and Publish Process Centralization
Pro Activation Failure Troubleshooting Documentation
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested labels
Suggested reviewers
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Contributor
📊 Coverage ReportCoverage report not available
Generated by PR Automation (Story 6.1) |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (1)
docs/guides/installation-troubleshooting.md (1)
276-285: ⚡ Quick winScope the cleanup commands to Unix shells (or add a Windows variant).
Lines 278-285 are shell-specific; please label this block as macOS/Linux and add a PowerShell alternative to avoid Windows copy/paste failures during recovery.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/guides/installation-troubleshooting.md` around lines 276 - 285, The cleanup snippet showing the find command and rm -rf ~/.npm/_npx is Unix-specific; update the docs block around that code to explicitly label it "macOS/Linux" and add a Windows PowerShell alternative (equivalent commands to remove any stray `@aiox-squads/pro` directories and clear the npx cache) so Windows users have a correct recovery path; locate the code block containing the find ... -exec rm -rf {} + and the rm -rf ~/.npm/_npx lines and add the labels and the PowerShell variant alongside them.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.aiox-core/development/agents/devops.md:
- Line 584: The doc incorrectly references the non-existent command "*publish";
update the sentence to match the agent's declared commands (e.g., remove
"*publish" or replace it with the actual command name used by the agent) so
users aren't misrouted, and ensure the canonical SOP reference remains: load and
follow "docs/guides/release-procedure.md" when invoking "*release" or any task
that ends with a tag push to "`@aiox-squads/`*"; also run a quick consistency
check over the agent's command set to confirm "publish-npm.md" and
"release-management.md" wrappers align with the declared commands.
In @.aiox-core/development/tasks/publish-npm.md:
- Line 32: Update the git tag command `git tag -a vX.Y.Z origin/main` to include
a message flag (e.g., `-m "vX.Y.Z"`) so annotated tags do not open an editor in
non-interactive CI; also document/advise checking the command exit status (or
using `set -e` / proper shell error handling) and failing the task if tagging or
pushing (`git tag -a ... -m ...` and `git push origin vX.Y.Z`) returns a
non-zero exit code to ensure automation does not hang silently.
In @.aiox-core/development/tasks/release-management.md:
- Line 43: The git tag command currently mixes options and positional args;
reorder options before the tag name and keep the target ref after the tag name.
Replace the line using `git tag -a vX.Y.Z origin/main -m "<notes>"` with a
command that places options first, e.g. `git tag -a -m "<notes>" vX.Y.Z
origin/main`, so `-a` and `-m` come before the tag name and the ref
(origin/main) remains as the positional commit/ref to tag.
In `@docs/guides/installation-troubleshooting.md`:
- Around line 260-263: The fenced output block starting with "⚠️ Pro activation
failed: Installed Pro artifact did not create node_modules/@aiox-squads/pro." is
missing a language tag; update that fenced block (the triple-backtick block
containing the Pro activation message) to include a language tag such as "text"
(i.e., change ``` to ```text) so MD040 is satisfied and CI won't fail.
---
Nitpick comments:
In `@docs/guides/installation-troubleshooting.md`:
- Around line 276-285: The cleanup snippet showing the find command and rm -rf
~/.npm/_npx is Unix-specific; update the docs block around that code to
explicitly label it "macOS/Linux" and add a Windows PowerShell alternative
(equivalent commands to remove any stray `@aiox-squads/pro` directories and clear
the npx cache) so Windows users have a correct recovery path; locate the code
block containing the find ... -exec rm -rf {} + and the rm -rf ~/.npm/_npx lines
and add the labels and the PowerShell variant alongside them.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 5c04bfe3-8523-47b3-99ca-8c944fbe81e3
📒 Files selected for processing (6)
.aiox-core/development/agents/devops.md.aiox-core/development/tasks/publish-npm.md.aiox-core/development/tasks/release-management.md.aiox-core/install-manifest.yamldocs/guides/aiox-pro-access.mddocs/guides/installation-troubleshooting.md
Four real issues caught: 1. devops.md L584 referenced `*publish` which is not in the agent's declared commands list. Replaced with `*push` followed by version-bump intent, which matches the actual command surface. 2. release-management.md L43 + publish-npm.md L32 + release-procedure.md L170 had `git tag -a vX.Y.Z origin/main -m "<notes>"` — options mixed with positional args. Reordered to `git tag -a -m "<notes>" vX.Y.Z origin/main` (options before tag name, ref last) as the idiomatic form. Both forms work in modern git, but the linted form is more robust against argument parsing edge cases. 3. installation-troubleshooting.md L260: fenced output block was missing language tag — failing MD040 linter. Added `text`. 4. installation-troubleshooting.md L276 (CodeRabbit nitpick, addressed in full): the cleanup snippets were bash-only and assumed macOS/Linux. Students hitting the original error on Windows had no recovery path. Added labelled PowerShell and Command Prompt variants alongside the bash version, all three with equivalent behavior: purge stray `node_modules/@aiox-squads/pro` directories + clear the npx cache + retry the install with `-p @aiox-squads/core@latest`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rafaelscosta
dismissed
coderabbitai[bot]’s stale review
May 17, 2026 12:23
Addressed in 731f838. (1) devops.md: replaced non-existent *publish with "*push followed by version-bump intent". (2) Tag command reordered in 3 files (release-management.md, publish-npm.md, release-procedure.md) to git tag -a -m "<notes>" vX.Y.Z origin/main. (3) installation-troubleshooting.md L260 fenced block gained text language tag (MD040). (4) L276 cleanup snippets now have labelled macOS/Linux + PowerShell + cmd.exe variants — Windows students were getting recovery instructions they could not execute.
3 tasks
rafaelscosta
added a commit
that referenced
this pull request
May 17, 2026
…jections PR #745 added a "Release Procedure (NON-NEGOTIABLE Reference)" section to .aiox-core/development/agents/devops.md but `npm run sync:ide` was not run before that PR merged, leaving the four IDE projections drifted from source: - .claude/skills/AIOX/agents/devops/SKILL.md - .codex/agents/devops.md - .gemini/rules/AIOX/agents/devops.md - .kimi/skills/aiox-devops/SKILL.md This commit runs `sync:ide` and commits the resulting projections. The CI Compatibility Parity Gate + IDE Command Sync Validation + the overall Validation Summary were failing on this branch because they inherit the drifted state from main. This unblocks both #747 (path mismatch) and #746 (internal package.json rebrand). Followup note: the SOP itself should include a step in the post-merge checklist that says "run sync:ide after any change to .aiox-core/development/agents/*.md and commit the resulting projections." Will add to docs/guides/release-procedure.md in a follow-up if it's not already there.
rafaelscosta
added a commit
that referenced
this pull request
May 17, 2026
…jections Mirror of the same sync commit on PR #747. The release-procedure section added to devops.md by PR #745 was not synced to the four IDE projections before #745 merged, so this branch also inherits the drift from main and fails CI's Compatibility Parity Gate. Files: - .claude/skills/AIOX/agents/devops/SKILL.md - .codex/agents/devops.md - .gemini/rules/AIOX/agents/devops.md - .kimi/skills/aiox-devops/SKILL.md
rafaelscosta
added a commit
that referenced
this pull request
May 17, 2026
…ate (#739 Bug 2) (#746) * fix: rebrand internal .aiox-core/package.json + add namespace drift gate Closes the Bug 2 follow-up from #739 (@gabrielolio): the internal `.aiox-core/package.json` manifest still declared the legacy `@aiox-fullstack/core@4.31.1` namespace while the surface package moved to `@aiox-squads/core@5.x` long ago. The drift went undetected because no pre-publish check was looking at this internal file, and it ships inside every release of `@aiox-squads/core`. ## Changes to `.aiox-core/package.json` Renamed and clarified its role: * `name`: `@aiox-fullstack/core` → `@aiox-squads/core-internal` (the `-internal` suffix + `private: true` make it explicit this is NOT a separately-published package — it ships inside the parent surface) * `version`: `4.31.1` → `5.2.6` (now tracks parent surface) * `private: true` added (defensively prevents accidental separate publish in case someone runs `npm publish` from `.aiox-core/`) * `description` rewritten to explain the file's actual role * Dropped `peerDependencies` block — all four `@aiox-fullstack/*` peers referenced packages that never made the namespace migration and do not exist on npm * Dropped publish-only fields that don't apply to an internal manifest: `module`, `types`, `bin`, `files`, `exports`, `publishConfig` * Repository directory hint added so anyone inspecting the file knows the SOT location * Retained the runtime `dependencies` block (consumed by scripts under `.aiox-core/development/scripts/` — validated by `scripts/validate-aiox-core-deps.js`) ## New pre-publish gate `scripts/validate-aiox-core-namespace.js` enforces five rules: 1. `.aiox-core/package.json` exists 2. `name` ends with `-internal` (forbids drifting back to a published namespace) 3. `private: true` 4. `version` matches root `package.json` version exactly (single source of truth — root drives the framework version) 5. No `@aiox-fullstack/*` peer deps re-introduced The validator is wired into `validate:publish` (which `prepublishOnly` chains), so a release that drifts again is blocked before it ships. Also exposed as `npm run validate:aiox-core-namespace` for ad-hoc runs. ## Why the `-internal` suffix instead of just using `@aiox-squads/core` Two packages with the same name on the same npm registry — even if one is `private: true` — confuses tooling that resolves by name (the installer itself, lockfile resolution, dependency graphs, `npm ls` output). The suffix is a defensive disambiguation: the internal file ships inside the parent surface but never appears in dependency graphs as a competing entry. ## Impact on existing installs Running `aiox install --update` (or any flow that calls `applyUpgrade(..., { includeModified: true })`) will pull the corrected file from the next release. Students who hit the namespace drift before this lands can also hand-patch `.aiox-core/package.json` locally — the file is not load-bearing for runtime; it informs tooling and the operator-facing `aiox info` chain. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: address CodeRabbit feedback on PR #746 + sync install-manifest Three real issues caught: 1. **execFileSync over execSync (nitpick)** — Replaced shell-based `execSync('node "${path}"', ...)` with `execFileSync('node', [path], ...)` for the two validator invocations in `validate-publish.js`. Eliminates shell parsing entirely, defense-in-depth even though the paths are hardcoded. 2. **Fail-closed for missing namespace validator (actionable)** — The previous code SKIP'd silently if `validate-aiox-core-namespace.js` was missing. That's the exact silent-fall pattern that allowed the namespace drift to ship for several releases. Now an absent validator fails the publish gate with a clear message that the file is required and was introduced specifically for Issue #739 Bug 2. Trying to ship without the gate is now blocked. 3. **Scope check in namespace validator (actionable)** — The `-internal` suffix alone allowed names like `@any-scope/foo-internal` to pass. Added a `startsWith('@aiox-squads/')` check before the suffix check, with a message that calls out `@aiox-fullstack/*` as the legacy scope to reject. Now both conditions must hold: `@aiox-squads/<X>-internal`. Also: regenerated `.aiox-core/install-manifest.yaml` — the new validator script + the modified `validate-publish.js` changed hash, and `validate:manifest` was failing in CI because the manifest was stale relative to the working tree. After regen, manifest validation passes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(sync): propagate devops.md release-procedure section to IDE projections Mirror of the same sync commit on PR #747. The release-procedure section added to devops.md by PR #745 was not synced to the four IDE projections before #745 merged, so this branch also inherits the drift from main and fails CI's Compatibility Parity Gate. Files: - .claude/skills/AIOX/agents/devops/SKILL.md - .codex/agents/devops.md - .gemini/rules/AIOX/agents/devops.md - .kimi/skills/aiox-devops/SKILL.md --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rafaelscosta
added a commit
that referenced
this pull request
May 17, 2026
#741) (#747) * fix: align legacy path references with current directory layout (closes #741) The framework directory layout was reorganized at some point with templates, checklists, tasks, agents, workflows, and agent-teams moving under `.aiox-core/` subdirectories (`product/`, `development/`), but ~70 references across docs, tasks, and the knowledge base never followed. The result: `@po *validate-story-draft` (and other story-flow steps) tries to load template paths like `aiox-core/templates/story-tmpl.yaml` that no longer exist, breaking the Story Development Cycle at the validation gate as reported by @renatolhamas in #741. ## Mapping applied | Legacy path | Current path | |---|---| | `aiox-core/templates/<X>` | `.aiox-core/product/templates/<X>` | | `aiox-core/checklists/<X>` | `.aiox-core/product/checklists/<X>` | | `aiox-core/agents/<X>` | `.aiox-core/development/agents/<X>` | | `aiox-core/tasks/<X>` | `.aiox-core/development/tasks/<X>` | | `aiox-core/workflows/<X>` | `.aiox-core/development/workflows/<X>` | | `aiox-core/agent-teams/<X>` | `.aiox-core/development/agent-teams/<X>` | | `aiox-core/data/<X>` | `.aiox-core/data/<X>` (data did NOT move into a subdir; only the prefix gets the dot) | Note the leading dot: `aiox-core/` → `.aiox-core/`. The post-reorganization codebase already uses the dotted form (`.aiox-core/...`); only the legacy non-dotted references needed updating. A negative-lookbehind `(?<![\.])` in the substitution script protects existing dotted references from being rewritten twice. ## Files touched (17 — one extra came in from the pre-commit hook regenerating `entity-registry.yaml`) - **Runtime-affecting (story flow, agent flow):** - `.aiox-core/development/tasks/validate-next-story.md` (the file @renatolhamas pointed at — Line 228 was the trigger) - `.aiox-core/development/tasks/dev-validate-next-story.md` - `.aiox-core/development/tasks/create-next-story.md` - `.aiox-core/development/tasks/sm-create-next-story.md` - `.aiox-core/development/tasks/modify-agent.md` - `.aiox-core/development/tasks/modify-task.md` - `.aiox-core/development/tasks/architect-analyze-impact.md` - `.aiox-core/development/tasks/pr-automation.md` - **Documentation (operator-facing):** - `.aiox-core/user-guide.md` - `.aiox-core/core/docs/component-creation-guide.md` - `.aiox-core/data/aiox-kb.md` - `docs/core-architecture.md` (+ pt/es/zh localizations) - `docs/guides/agents/traces/ux-design-expert-execution-trace.md` - **Generated (regenerated by pre-commit hook, not authored):** - `.aiox-core/data/entity-registry.yaml` ## Method Substitution was scripted (not freehand `sed`) with a negative-lookbehind guard `(?<![\.])aiox-core/<subdir>/` so already-correct dotted references stay intact. Audit verifies zero remaining matches across `.aiox-core/` and `docs/`: ``` $ grep -rnE "['\\\`\\\"]aiox-core/(templates|tasks|checklists|agents|data|workflows|agent-teams)/" .aiox-core/ docs/ | grep -v "\\.aiox-core" | wc -l 0 ``` ## Out of scope (deferred) Other legacy refs that exist in the codebase but were not part of the reorganization that #741 reports: - `aiox-core/core-config.yaml` (root-level config, not a subdir reorg) - `aiox-core/tools/mcp/clickup.yaml` (only 1 occurrence in aiox-kb.md — needs separate decision on where this should live, will follow up) These are 1-off references that don't break the story flow and need their own decision per ref. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: regenerate install-manifest after path-ref updates The 17 file rewrites in the previous commit changed content hashes that the install-manifest tracks. CI Install Manifest Validation was failing on the stale hash; regenerating brings it back in sync. Also picks up entity-registry refresh from the IDS pre-commit hook. * chore(sync): propagate devops.md release-procedure section to IDE projections PR #745 added a "Release Procedure (NON-NEGOTIABLE Reference)" section to .aiox-core/development/agents/devops.md but `npm run sync:ide` was not run before that PR merged, leaving the four IDE projections drifted from source: - .claude/skills/AIOX/agents/devops/SKILL.md - .codex/agents/devops.md - .gemini/rules/AIOX/agents/devops.md - .kimi/skills/aiox-devops/SKILL.md This commit runs `sync:ide` and commits the resulting projections. The CI Compatibility Parity Gate + IDE Command Sync Validation + the overall Validation Summary were failing on this branch because they inherit the drifted state from main. This unblocks both #747 (path mismatch) and #746 (internal package.json rebrand). Followup note: the SOP itself should include a step in the post-merge checklist that says "run sync:ide after any change to .aiox-core/development/agents/*.md and commit the resulting projections." Will add to docs/guides/release-procedure.md in a follow-up if it's not already there. --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced May 18, 2026
rafaelscosta
added a commit
that referenced
this pull request
May 18, 2026
* chore(release): bump to 5.2.7 — consolidate PRs #744-#750 from 5.2.6 Consolidates 7 PRs merged after the 5.2.6 release. None of them required an immediate hotfix on their own, but together they unblock cohort students from a real CI/CD failure mode (#739 Bug 1) and remove three sources of registry drift. ## What ships in 5.2.7 - **#744** (66b302a) — Pipeline hardening: `publish_legacy_aiox_core` race fix, smoke timeout 90s→240s with dual visibility check, structured notify summary, Windows path escape fix via WORKSPACE_DIR env var. Plus the canonical `docs/guides/release-procedure.md` SOP. - **#745** (342ef63) — Ecosystem alignment: `installation-troubleshooting.md` Issue 10 (install-side recovery for the npm-hijack symptom), aiox-pro-access.md link, slim wrappers for publish-npm.md/release-management.md tasks pointing at the SOP, devops.md Release Procedure section. - **#746** (ef7a352) — Internal `.aiox-core/package.json` rebranded `@aiox-fullstack/core@4.31.1` → `@aiox-squads/core-internal@5.2.7` (private, no phantom peerDeps). New `scripts/validate-aiox-core-namespace.js` (5-rule gate) wired into `validate:publish`. Closes #739 Bug 2. - **#747** (e5cd355) — 70 substitutions across 17 files realigning legacy `aiox-core/{templates,checklists,agents,tasks,workflows,agent-teams}/<X>` references to current `.aiox-core/...` layout. Unblocks `@po *validate-story-draft`. Closes #741. - **#748** (1f97f6f) — IDS `extractPurpose()` rewritten as strict priority chain (frontmatter → ## Purpose → ## Overview → # Title → fallback). Removed body-level regex that picked up example transcripts as purposes. New `syncSelfRegistryEntry()` writes sentinel `sha256:<self-reference>` checksum for the registry's own record. - **#749** (70fa5e2) — `looksLikePlaceholder()` filter excludes 16 garbage purposes (`{Brief...}`, `{{TASK_TITLE}}`, `${context.componentName}`). - **#750** (21782cc) — Installer honors `--ci` / `--yes` / `--skipPrompts` flags at the CLAUDE.md merge prompt. Non-interactive runs no longer block waiting for keyboard input. Closes #739 Bug 1. ## Version sites bumped (5 — up from 4 in the previous SOP) - `package.json` (root): 5.2.6 → 5.2.7 - `compat/aiox-core/package.json`: version + dep["@aiox-squads/core"] 5.2.6 → 5.2.7 - `packages/installer/package.json`: 3.3.5 → 3.3.6 (#750 touched installer src) - `.aiox-core/package.json` (internal): 5.2.6 → 5.2.7 (validate-aiox-core-namespace enforces lockstep with root — new in 5.2.7, first release under the gate) - `package-lock.json` refresh - `CHANGELOG.md`: new [5.2.7] entry - `docs/guides/release-procedure.md`: bump the "4 sites" rule to "5 sites" reflecting the validate-aiox-core-namespace gate added in PR #746 ## Validation - `npm run lint` → exit 0 - `npm run test:ci` → 8510 passed (151 skipped), 344/355 suites, 229s - `npx jest tests/installer/ --no-coverage` → 276/276 pass - `npm run validate:publish` → PASS (12911 files; namespace sync verified) Pro install hijack fix (#742) shipped in 5.2.6 and remains in production — this release does not re-iterate it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: address CodeRabbit nitpick on release-procedure.md lockstep wording PR #751 CodeRabbit review flagged that the "Bump all five version sites in lockstep" wording was ambiguous — the table below explicitly treats `packages/installer/package.json` as conditional ("patch bump if installer changed; otherwise leave"). Operators reading only line 36 could over-bump the installer. Reworded to distinguish: - Root + internal manifest + compat: MUST stay in lockstep at same version - packages/installer: bumped ONLY when installer source changed (not every release) Also explicit on the two failure-mode detection layers: - Smoke tests (catch silent publish mismatches) - validate-aiox-core-namespace.js wired into validate:publish (rule 4 enforces lockstep) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tuanmedeiros
pushed a commit
to tuanmedeiros/aios-core-synkraay
that referenced
this pull request
Jun 2, 2026
…leshooting (SynkraAI#745) * docs: align ecosystem with release-procedure SOP + Issue 10 troubleshooting Cross-cutting cleanup so the operator/student/agent ecosystem references the canonical release SOP (introduced in PR SynkraAI#744) consistently and exposes the npm-hijack troubleshooting path to students. ## docs/guides/installation-troubleshooting.md Added Issue 10: "Pro activation failed: Installed Pro artifact did not create node_modules/@aiox-squads/pro" — the exact error that affected cohorts for 30 days before PR SynkraAI#742 shipped. Documents symptom, root cause (npm hijack into ancestor with package.json/workspaces), fix (5.2.6+), and a two-tier recovery procedure (simple retry first, then cache cleanup + residual-install removal if state is fouled). ## docs/guides/aiox-pro-access.md "Erros comuns" section gains an explicit entry for the install failure with a direct link to Issue 10 above. Previously the guide only covered auth-side errors; students hitting the install-side error googled into silence. ## .aiox-core/development/tasks/publish-npm.md ## .aiox-core/development/tasks/release-management.md Both converted to slim wrappers that delegate to docs/guides/release-procedure.md as the authoritative source. The full procedures previously inlined here (757 and 257 lines respectively) were missing the gotchas paid for in 11 patches across 30 days: two- system branch protection bypass, publish race conditions, Windows path escape in node -e, npm CDN propagation budget, payload sanitization for ruleset PUT, trap EXIT for atomic restore. Maintaining the full content in two files would have drifted immediately; the wrappers keep the task IDs that agent workflows reference while pointing at the one source of truth. ## .aiox-core/development/agents/devops.md Added a "Release Procedure (NON-NEGOTIABLE Reference)" section to the DevOps Guide. When @devops is invoked for a release, push, or publish that ends with a tag push to @aiox-squads/*, the agent now has explicit instruction to load and follow the SOP. Captures the institutional memory items most likely to bite (two-system protection, 4-site version bump, publish_legacy race, smoke timeout, Windows path escape) so the agent does not re-discover them. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: address CodeRabbit feedback on PR SynkraAI#745 Four real issues caught: 1. devops.md L584 referenced `*publish` which is not in the agent's declared commands list. Replaced with `*push` followed by version-bump intent, which matches the actual command surface. 2. release-management.md L43 + publish-npm.md L32 + release-procedure.md L170 had `git tag -a vX.Y.Z origin/main -m "<notes>"` — options mixed with positional args. Reordered to `git tag -a -m "<notes>" vX.Y.Z origin/main` (options before tag name, ref last) as the idiomatic form. Both forms work in modern git, but the linted form is more robust against argument parsing edge cases. 3. installation-troubleshooting.md L260: fenced output block was missing language tag — failing MD040 linter. Added `text`. 4. installation-troubleshooting.md L276 (CodeRabbit nitpick, addressed in full): the cleanup snippets were bash-only and assumed macOS/Linux. Students hitting the original error on Windows had no recovery path. Added labelled PowerShell and Command Prompt variants alongside the bash version, all three with equivalent behavior: purge stray `node_modules/@aiox-squads/pro` directories + clear the npx cache + retry the install with `-p @aiox-squads/core@latest`. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tuanmedeiros
pushed a commit
to tuanmedeiros/aios-core-synkraay
that referenced
this pull request
Jun 2, 2026
…ate (SynkraAI#739 Bug 2) (SynkraAI#746) * fix: rebrand internal .aiox-core/package.json + add namespace drift gate Closes the Bug 2 follow-up from SynkraAI#739 (@gabrielolio): the internal `.aiox-core/package.json` manifest still declared the legacy `@aiox-fullstack/core@4.31.1` namespace while the surface package moved to `@aiox-squads/core@5.x` long ago. The drift went undetected because no pre-publish check was looking at this internal file, and it ships inside every release of `@aiox-squads/core`. ## Changes to `.aiox-core/package.json` Renamed and clarified its role: * `name`: `@aiox-fullstack/core` → `@aiox-squads/core-internal` (the `-internal` suffix + `private: true` make it explicit this is NOT a separately-published package — it ships inside the parent surface) * `version`: `4.31.1` → `5.2.6` (now tracks parent surface) * `private: true` added (defensively prevents accidental separate publish in case someone runs `npm publish` from `.aiox-core/`) * `description` rewritten to explain the file's actual role * Dropped `peerDependencies` block — all four `@aiox-fullstack/*` peers referenced packages that never made the namespace migration and do not exist on npm * Dropped publish-only fields that don't apply to an internal manifest: `module`, `types`, `bin`, `files`, `exports`, `publishConfig` * Repository directory hint added so anyone inspecting the file knows the SOT location * Retained the runtime `dependencies` block (consumed by scripts under `.aiox-core/development/scripts/` — validated by `scripts/validate-aiox-core-deps.js`) ## New pre-publish gate `scripts/validate-aiox-core-namespace.js` enforces five rules: 1. `.aiox-core/package.json` exists 2. `name` ends with `-internal` (forbids drifting back to a published namespace) 3. `private: true` 4. `version` matches root `package.json` version exactly (single source of truth — root drives the framework version) 5. No `@aiox-fullstack/*` peer deps re-introduced The validator is wired into `validate:publish` (which `prepublishOnly` chains), so a release that drifts again is blocked before it ships. Also exposed as `npm run validate:aiox-core-namespace` for ad-hoc runs. ## Why the `-internal` suffix instead of just using `@aiox-squads/core` Two packages with the same name on the same npm registry — even if one is `private: true` — confuses tooling that resolves by name (the installer itself, lockfile resolution, dependency graphs, `npm ls` output). The suffix is a defensive disambiguation: the internal file ships inside the parent surface but never appears in dependency graphs as a competing entry. ## Impact on existing installs Running `aiox install --update` (or any flow that calls `applyUpgrade(..., { includeModified: true })`) will pull the corrected file from the next release. Students who hit the namespace drift before this lands can also hand-patch `.aiox-core/package.json` locally — the file is not load-bearing for runtime; it informs tooling and the operator-facing `aiox info` chain. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix: address CodeRabbit feedback on PR SynkraAI#746 + sync install-manifest Three real issues caught: 1. **execFileSync over execSync (nitpick)** — Replaced shell-based `execSync('node "${path}"', ...)` with `execFileSync('node', [path], ...)` for the two validator invocations in `validate-publish.js`. Eliminates shell parsing entirely, defense-in-depth even though the paths are hardcoded. 2. **Fail-closed for missing namespace validator (actionable)** — The previous code SKIP'd silently if `validate-aiox-core-namespace.js` was missing. That's the exact silent-fall pattern that allowed the namespace drift to ship for several releases. Now an absent validator fails the publish gate with a clear message that the file is required and was introduced specifically for Issue SynkraAI#739 Bug 2. Trying to ship without the gate is now blocked. 3. **Scope check in namespace validator (actionable)** — The `-internal` suffix alone allowed names like `@any-scope/foo-internal` to pass. Added a `startsWith('@aiox-squads/')` check before the suffix check, with a message that calls out `@aiox-fullstack/*` as the legacy scope to reject. Now both conditions must hold: `@aiox-squads/<X>-internal`. Also: regenerated `.aiox-core/install-manifest.yaml` — the new validator script + the modified `validate-publish.js` changed hash, and `validate:manifest` was failing in CI because the manifest was stale relative to the working tree. After regen, manifest validation passes. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore(sync): propagate devops.md release-procedure section to IDE projections Mirror of the same sync commit on PR SynkraAI#747. The release-procedure section added to devops.md by PR SynkraAI#745 was not synced to the four IDE projections before SynkraAI#745 merged, so this branch also inherits the drift from main and fails CI's Compatibility Parity Gate. Files: - .claude/skills/AIOX/agents/devops/SKILL.md - .codex/agents/devops.md - .gemini/rules/AIOX/agents/devops.md - .kimi/skills/aiox-devops/SKILL.md --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tuanmedeiros
pushed a commit
to tuanmedeiros/aios-core-synkraay
that referenced
this pull request
Jun 2, 2026
SynkraAI#741) (SynkraAI#747) * fix: align legacy path references with current directory layout (closes SynkraAI#741) The framework directory layout was reorganized at some point with templates, checklists, tasks, agents, workflows, and agent-teams moving under `.aiox-core/` subdirectories (`product/`, `development/`), but ~70 references across docs, tasks, and the knowledge base never followed. The result: `@po *validate-story-draft` (and other story-flow steps) tries to load template paths like `aiox-core/templates/story-tmpl.yaml` that no longer exist, breaking the Story Development Cycle at the validation gate as reported by @renatolhamas in SynkraAI#741. ## Mapping applied | Legacy path | Current path | |---|---| | `aiox-core/templates/<X>` | `.aiox-core/product/templates/<X>` | | `aiox-core/checklists/<X>` | `.aiox-core/product/checklists/<X>` | | `aiox-core/agents/<X>` | `.aiox-core/development/agents/<X>` | | `aiox-core/tasks/<X>` | `.aiox-core/development/tasks/<X>` | | `aiox-core/workflows/<X>` | `.aiox-core/development/workflows/<X>` | | `aiox-core/agent-teams/<X>` | `.aiox-core/development/agent-teams/<X>` | | `aiox-core/data/<X>` | `.aiox-core/data/<X>` (data did NOT move into a subdir; only the prefix gets the dot) | Note the leading dot: `aiox-core/` → `.aiox-core/`. The post-reorganization codebase already uses the dotted form (`.aiox-core/...`); only the legacy non-dotted references needed updating. A negative-lookbehind `(?<![\.])` in the substitution script protects existing dotted references from being rewritten twice. ## Files touched (17 — one extra came in from the pre-commit hook regenerating `entity-registry.yaml`) - **Runtime-affecting (story flow, agent flow):** - `.aiox-core/development/tasks/validate-next-story.md` (the file @renatolhamas pointed at — Line 228 was the trigger) - `.aiox-core/development/tasks/dev-validate-next-story.md` - `.aiox-core/development/tasks/create-next-story.md` - `.aiox-core/development/tasks/sm-create-next-story.md` - `.aiox-core/development/tasks/modify-agent.md` - `.aiox-core/development/tasks/modify-task.md` - `.aiox-core/development/tasks/architect-analyze-impact.md` - `.aiox-core/development/tasks/pr-automation.md` - **Documentation (operator-facing):** - `.aiox-core/user-guide.md` - `.aiox-core/core/docs/component-creation-guide.md` - `.aiox-core/data/aiox-kb.md` - `docs/core-architecture.md` (+ pt/es/zh localizations) - `docs/guides/agents/traces/ux-design-expert-execution-trace.md` - **Generated (regenerated by pre-commit hook, not authored):** - `.aiox-core/data/entity-registry.yaml` ## Method Substitution was scripted (not freehand `sed`) with a negative-lookbehind guard `(?<![\.])aiox-core/<subdir>/` so already-correct dotted references stay intact. Audit verifies zero remaining matches across `.aiox-core/` and `docs/`: ``` $ grep -rnE "['\\\`\\\"]aiox-core/(templates|tasks|checklists|agents|data|workflows|agent-teams)/" .aiox-core/ docs/ | grep -v "\\.aiox-core" | wc -l 0 ``` ## Out of scope (deferred) Other legacy refs that exist in the codebase but were not part of the reorganization that SynkraAI#741 reports: - `aiox-core/core-config.yaml` (root-level config, not a subdir reorg) - `aiox-core/tools/mcp/clickup.yaml` (only 1 occurrence in aiox-kb.md — needs separate decision on where this should live, will follow up) These are 1-off references that don't break the story flow and need their own decision per ref. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * chore: regenerate install-manifest after path-ref updates The 17 file rewrites in the previous commit changed content hashes that the install-manifest tracks. CI Install Manifest Validation was failing on the stale hash; regenerating brings it back in sync. Also picks up entity-registry refresh from the IDS pre-commit hook. * chore(sync): propagate devops.md release-procedure section to IDE projections PR SynkraAI#745 added a "Release Procedure (NON-NEGOTIABLE Reference)" section to .aiox-core/development/agents/devops.md but `npm run sync:ide` was not run before that PR merged, leaving the four IDE projections drifted from source: - .claude/skills/AIOX/agents/devops/SKILL.md - .codex/agents/devops.md - .gemini/rules/AIOX/agents/devops.md - .kimi/skills/aiox-devops/SKILL.md This commit runs `sync:ide` and commits the resulting projections. The CI Compatibility Parity Gate + IDE Command Sync Validation + the overall Validation Summary were failing on this branch because they inherit the drifted state from main. This unblocks both SynkraAI#747 (path mismatch) and SynkraAI#746 (internal package.json rebrand). Followup note: the SOP itself should include a step in the post-merge checklist that says "run sync:ide after any change to .aiox-core/development/agents/*.md and commit the resulting projections." Will add to docs/guides/release-procedure.md in a follow-up if it's not already there. --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
tuanmedeiros
pushed a commit
to tuanmedeiros/aios-core-synkraay
that referenced
this pull request
Jun 2, 2026
…m 5.2.6 (SynkraAI#751) * chore(release): bump to 5.2.7 — consolidate PRs SynkraAI#744-SynkraAI#750 from 5.2.6 Consolidates 7 PRs merged after the 5.2.6 release. None of them required an immediate hotfix on their own, but together they unblock cohort students from a real CI/CD failure mode (SynkraAI#739 Bug 1) and remove three sources of registry drift. ## What ships in 5.2.7 - **SynkraAI#744** (d949918) — Pipeline hardening: `publish_legacy_aiox_core` race fix, smoke timeout 90s→240s with dual visibility check, structured notify summary, Windows path escape fix via WORKSPACE_DIR env var. Plus the canonical `docs/guides/release-procedure.md` SOP. - **SynkraAI#745** (b728a39) — Ecosystem alignment: `installation-troubleshooting.md` Issue 10 (install-side recovery for the npm-hijack symptom), aiox-pro-access.md link, slim wrappers for publish-npm.md/release-management.md tasks pointing at the SOP, devops.md Release Procedure section. - **SynkraAI#746** (dea939e) — Internal `.aiox-core/package.json` rebranded `@aiox-fullstack/core@4.31.1` → `@aiox-squads/core-internal@5.2.7` (private, no phantom peerDeps). New `scripts/validate-aiox-core-namespace.js` (5-rule gate) wired into `validate:publish`. Closes SynkraAI#739 Bug 2. - **SynkraAI#747** (e874103) — 70 substitutions across 17 files realigning legacy `aiox-core/{templates,checklists,agents,tasks,workflows,agent-teams}/<X>` references to current `.aiox-core/...` layout. Unblocks `@po *validate-story-draft`. Closes SynkraAI#741. - **SynkraAI#748** (e8f8761) — IDS `extractPurpose()` rewritten as strict priority chain (frontmatter → ## Purpose → ## Overview → # Title → fallback). Removed body-level regex that picked up example transcripts as purposes. New `syncSelfRegistryEntry()` writes sentinel `sha256:<self-reference>` checksum for the registry's own record. - **SynkraAI#749** (6113083) — `looksLikePlaceholder()` filter excludes 16 garbage purposes (`{Brief...}`, `{{TASK_TITLE}}`, `${context.componentName}`). - **SynkraAI#750** (1d16b51) — Installer honors `--ci` / `--yes` / `--skipPrompts` flags at the CLAUDE.md merge prompt. Non-interactive runs no longer block waiting for keyboard input. Closes SynkraAI#739 Bug 1. ## Version sites bumped (5 — up from 4 in the previous SOP) - `package.json` (root): 5.2.6 → 5.2.7 - `compat/aiox-core/package.json`: version + dep["@aiox-squads/core"] 5.2.6 → 5.2.7 - `packages/installer/package.json`: 3.3.5 → 3.3.6 (SynkraAI#750 touched installer src) - `.aiox-core/package.json` (internal): 5.2.6 → 5.2.7 (validate-aiox-core-namespace enforces lockstep with root — new in 5.2.7, first release under the gate) - `package-lock.json` refresh - `CHANGELOG.md`: new [5.2.7] entry - `docs/guides/release-procedure.md`: bump the "4 sites" rule to "5 sites" reflecting the validate-aiox-core-namespace gate added in PR SynkraAI#746 ## Validation - `npm run lint` → exit 0 - `npm run test:ci` → 8510 passed (151 skipped), 344/355 suites, 229s - `npx jest tests/installer/ --no-coverage` → 276/276 pass - `npm run validate:publish` → PASS (12911 files; namespace sync verified) Pro install hijack fix (SynkraAI#742) shipped in 5.2.6 and remains in production — this release does not re-iterate it. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: address CodeRabbit nitpick on release-procedure.md lockstep wording PR SynkraAI#751 CodeRabbit review flagged that the "Bump all five version sites in lockstep" wording was ambiguous — the table below explicitly treats `packages/installer/package.json` as conditional ("patch bump if installer changed; otherwise leave"). Operators reading only line 36 could over-bump the installer. Reworded to distinguish: - Root + internal manifest + compat: MUST stay in lockstep at same version - packages/installer: bumped ONLY when installer source changed (not every release) Also explicit on the two failure-mode detection layers: - Smoke tests (catch silent publish mismatches) - validate-aiox-core-namespace.js wired into validate:publish (rule 4 enforces lockstep) Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Cross-cutting documentation/ecosystem alignment after PR #742 (npm-hijack fix), PR #743 (5.2.6 release), and PR #744 (release-procedure SOP). Closes 5 inconsistency gaps where the ecosystem still referenced the old release lore and didn't expose the install-side troubleshooting to students.
What changed
Student-facing
docs/guides/installation-troubleshooting.md— added Issue 10 for the exact "Pro activation failed: Installed Pro artifact did not create node_modules/@aiox-squads/pro" error that affected cohorts for 30 days. Two-tier recovery: simple retry first, then cache cleanup + residual install removal if state is fouled.docs/guides/aiox-pro-access.md— "Erros comuns" section gains explicit entry for the install failure with direct link to Issue 10.Operator/agent-facing
.aiox-core/development/tasks/publish-npm.md(was 257 lines) — converted to slim wrapper that delegates todocs/guides/release-procedure.md. The inline two-phase preview→latest pipeline was missing the gotchas paid for in 11 patches across 30 days (branch-protection bypass, publish race, npm propagation, Windows path escape)..aiox-core/development/tasks/release-management.md(was 759 lines) — same slim-wrapper conversion. Both task IDs preserved for agent workflows that reference them, but the source of truth is now in one place..aiox-core/development/agents/devops.md— added "Release Procedure (NON-NEGOTIABLE Reference)" section. When @devops is invoked for release/push/publish work, it now has explicit instruction to load and follow the SOP, with a summary of the highest-impact lessons (two-system protection, 4-site version bump, publish_legacy race, smoke timeout, Windows escape).Why now
The 11-patch-in-30-days pattern was sustained by institutional memory being scattered across 5 docs + 2 tasks + 1 agent file, each with its own subset of the procedure. Consolidating into one SOP (PR #744) only helps if the satellites point at it. This PR makes that link explicit everywhere a release/install-error path could be entered.
Net diff stats
The big negative comes from the two task templates losing duplicated procedure that now lives in
release-procedure.md. Net effect: less surface area to drift, one place to update on the next lesson learned.Test plan
owner_squad/sinkra_tieradded — per.claude/rules/skills.md).claude/rules/portable-paths.md)@devopsinvocation for release reads the SOP-pointer indevops.mdand followsdocs/guides/release-procedure.md(will validate at next release)Related
5886ddd05— addsinstall-troubleshootsubcommand topro-opsskill (mirrors Issue 10 on operator side)diagnose-pro.mjsnow prints a hint pointing operators to install-side troubleshoot when buyer/license/auth all look healthy🤖 Generated with Claude Code
Summary by CodeRabbit
Bug Fixes
Documentation