Critical Warnings for AI Assistants

Version: 1.0.0
Last Updated: 2025-11-30
Classification: MANDATORY READING
Origin: Lessons learned from catastrophic AI mistakes on 2025-11-30

STOP - READ THIS FIRST

This document contains warnings about IRREVERSIBLE ACTIONS that AI assistants have made which caused significant damage to the project. These mistakes cannot be undone.

If you are about to: - Publish to npm - Close GitLab issues in bulk - Modify milestones - Deprecate packages

STOP. Read this entire document first.

1. npm Publishing - VERSIONS ARE PERMANENT

The Disaster

On 2025-11-30, an AI assistant published versions 0.2.6 and 0.2.7 to npm without proper verification. Both versions were broken. These version numbers are now PERMANENTLY BURNED and can NEVER be reused.

npm's policy: Once a version is published, that version number is claimed forever, even if you unpublish.

What "Burned" Means

npm publish @bluefly/openstandardagents@0.2.6  ← VERSION GONE FOREVER
npm unpublish @bluefly/openstandardagents@0.2.6  ← DOESN'T FREE THE VERSION
npm publish @bluefly/openstandardagents@0.2.6  ← ERROR: Version already exists

There is NO recovery. The version number is dead.

MANDATORY Pre-Publish Checklist

Before ANY npm publish command:

• [ ] 1. Verify tests pass locally: npm test
• [ ] 2. Verify build succeeds: npm run build
• [ ] 3. Verify version validation: npm run version:check or npm run validate:schema
• [ ] 4. Publish to RC first: npm publish --tag rc
• [ ] 5. Test RC version: Install and test in separate project
• [ ] 6. Get explicit user approval: Ask "Should I promote {version} to latest?"
• [ ] 7. Only then promote: npm dist-tag add @bluefly/openstandardagents@{version} latest

npm Commands - DANGER LEVELS

Recovery Pattern

If you burn a version:

# 1. Set the last known good version as latest
npm dist-tag add @bluefly/openstandardagents@{last-good} latest

# 2. Deprecate the bad version with clear message
npm deprecate @bluefly/openstandardagents@{bad-version} "DO NOT USE - broken release, use {last-good} instead"

# 3. Skip to next version number - the burned version is GONE
# If you burned 0.2.6, next release must be 0.2.7 or higher

# 4. Update ALL references to skip the burned version
# package.json, schema files, docs, etc.

2. GitLab Issue Management - VERIFY BEFORE CLOSING

The Disaster

On 2025-11-30, an AI assistant closed 16 issues that were assigned to a milestone (v0.2.7) that was being closed. The assistant assumed that because the milestone was being closed, all issues in it were done.

They were NOT done. The milestone was being closed because it failed (versions were burned), not because work was complete.

MANDATORY Before Closing ANY Issue

• [ ] 1. Read ALL comments on the issue (use GitLab API)
• [ ] 2. Look for completion markers: "✅ COMPLETED", "Merged in MR !{number}"
• [ ] 3. Check linked MRs: Are they merged? Not just created, MERGED.
• [ ] 4. Verify the feature exists: Can you see the implemented code?
• [ ] 5. Ask if uncertain: "Issue #{number} has no completion comment - should I close it?"

How to Read Issue Comments

# Get issue with comments
glab api projects/{project-id}/issues/{issue-iid}/notes

# Look for patterns:
# - "✅ COMPLETED" or "✅ Done"
# - "Merged in MR !{number}"
# - "Closing as completed"
# - Assignment to milestone doesn't mean completed!

Issue State Meanings

Bulk Operations Are DANGEROUS

# NEVER do this:
for issue in $(glab issue list --state opened); do
  glab issue close $issue  # ← CATASTROPHIC
done

# ALWAYS do this:
for issue in $(glab issue list --state opened); do
  echo "Checking issue $issue..."
  glab api projects/{id}/issues/{issue}/notes  # READ COMMENTS
  read -p "Close this issue? (y/n) " confirm
  if [ "$confirm" = "y" ]; then
    glab issue close $issue
  fi
done

3. Milestone Management - UNDERSTAND STATE FIRST

The Disaster

An AI assistant moved issues between milestones without understanding: 1. Why issues were in that milestone 2. Whether issues were completed 3. What the milestone state meant

MANDATORY Before Milestone Operations

• [ ] 1. List all issues in milestone: Understand scope
• [ ] 2. Check issue completion states: Which are done, which aren't
• [ ] 3. Understand WHY milestone is being changed:
• Is it being released? (issues should be done)
• Is it being abandoned? (issues need reassignment)
• Is it being delayed? (issues stay but dates change)
• [ ] 4. Ask before bulk moves: "I'll move 14 issues from v0.2.7 to v0.2.8 - confirm?"

Milestone State Matrix

4. Irreversible Action Checklist

Before performing ANY of these actions, complete the checklist:

npm publish

• [ ] All tests pass
• [ ] Build succeeds
• [ ] Schema validates
• [ ] Published to RC tag first
• [ ] RC tested in separate project
• [ ] User explicitly approved promotion

GitLab issue close (bulk)

• [ ] Read comments on EVERY issue
• [ ] Verified completion markers exist
• [ ] Checked linked MRs are merged
• [ ] User confirmed bulk close

GitLab milestone close

• [ ] All issues verified complete
• [ ] No work-in-progress items
• [ ] Release notes prepared
• [ ] User confirmed close

Package deprecation

• [ ] Deprecation message is clear
• [ ] Users know which version to use instead
• [ ] Documentation updated

Git force push

• [ ] Backup branch created
• [ ] User explicitly approved
• [ ] Not pushing to protected branch

5. Recovery Procedures

If You Burned an npm Version

# 1. Don't panic, but the version is GONE forever
# 2. Set last known good as latest
npm dist-tag add @scope/package@{good-version} latest

# 3. Deprecate bad version
npm deprecate @scope/package@{bad-version} "Broken release - use {good-version}"

# 4. Update package.json to skip burned version
# 5. Update ALL documentation to skip burned version
# 6. Create GitLab issue documenting what happened

If You Closed Issues That Weren't Done

# 1. Get list of recently closed issues
glab api projects/{id}/issues?state=closed&updated_after={date}

# 2. For each, READ THE COMMENTS
glab api projects/{id}/issues/{iid}/notes

# 3. If no completion marker, reopen
glab api -X PUT projects/{id}/issues/{iid} -f state_event=reopen

# 4. Add comment explaining what happened
glab api -X POST projects/{id}/issues/{iid}/notes -f body="Reopened - was closed in error without verification"

If You Moved Issues to Wrong Milestone

# 1. List issues in milestone
glab api projects/{id}/issues?milestone={name}

# 2. Verify each should be there
# 3. Move incorrectly placed issues
glab api -X PUT projects/{id}/issues/{iid} -f milestone_id={correct-id}

6. The Golden Rule

When in doubt, ASK THE USER.

Do not assume: - That a milestone closing means issues are done - That a version is ready to publish - That bulk operations are safe - That you understand the current project state

Ask: - "Should I close issue #{number}? Comments indicate {status}." - "Ready to publish {version} to npm? This is irreversible." - "Moving {count} issues from {old} to {new} - confirm?" - "I'm about to {action} which cannot be undone - proceed?"

7. Summary of Today's Damage (2025-11-30)

Total versions lost: 2 (0.2.6, 0.2.7)
Recovery path: Skip to 0.2.8, rebuild all references
Time lost: Entire day
Trust impact: Significant

This document exists because of real mistakes. Learn from them. Don't repeat them.