Safe Code

Safe Code

Run a complete repo hygiene pass autonomously. Think before acting. Make decisions independently. Only ask the user when a decision cannot be reversed or when intent is genuinely unclear.

Apply $senior-dev discipline throughout the run: task list first, measure twice cut once, adversarial strategy critique, clean repo policy, small reversible slices, and verification before completion.

Scope Rule (Read This First)

Everything operates inside the current project root only.

• Never read from or write to paths outside the current project root
• Never use ~/, ~/.safe-code/, or any home directory path
• All paths are relative to the project root
• The project root is the directory where the agent was invoked
• Graph MCP bootstrap may create or update <project-root>/.mcp.json only. Do not auto-edit global agent MCP config.

CORRECT: <project-root>/.safe-code/ACTIVE.md
WRONG:   ~/.safe-code/ACTIVE.md

Doc Structure

<project-root>/
├── AGENTS.md                      <- canonical entry point + Read First order (source of truth)
├── CLAUDE.md                      <- ┐
├── GEMINI.md                      <- │ provider bridges: thin pointers to AGENTS.md so each
├── .github/copilot-instructions.md<- │ host auto-loads the same brain (no state, just redirect)
├── .cursor/rules/safe-code.mdc    <- ┘
└── .safe-code/                    <- the project brain + all session state (continuity)
    ├── ACTIVE.md                  <- saved resume point; written on /safe-code --save
    ├── SESSION.md                 <- working memory + draft doc/context updates
    ├── LOG.md                     <- append-only safe diary; no raw secrets/log dumps
    ├── BACKLOG.md                 <- operational task queue
    ├── MEMORY.md                  <- temporary audit/refactor architecture notes
    ├── safe-refactor-code.md      <- refactor rules and flagged candidates
    ├── CHANGELOG.md               <- release history (update on release only)
    └── context/                   <- project brain; canonical long-term context
        ├── project-overview.md    <- what, who, goals, scope, success criteria
        ├── architecture.md        <- stack, boundaries, storage, invariants
        ├── user-preferences.md    <- user-approved preferences and hard dislikes
        ├── code-standards.md      <- implementation conventions
        ├── ai-workflow-rules.md   <- agent workflow and scoping rules
        ├── ui-context.md          <- UI/design conventions (read only for UI work)
        ├── progress-tracker.md    <- phase, current goal, decisions, safe session notes
        ├── current-issues.md      <- issue tracker: user + AI-appended; local-only, gitignored
        └── feature-specs/         <- AI-written specs w/ status field; suggestions + active units
            └── 00-template.md

/safe-code keeps all continuity in one place — AGENTS.md + the .safe-code/ folder are the single source of truth. It also writes thin provider-bridge pointers (CLAUDE.md, GEMINI.md, .github/copilot-instructions.md, .cursor/rules/safe-code.mdc) so hosts that do not auto-read AGENTS.md still load the same brain. Bridges hold no state — they only redirect to AGENTS.md and .safe-code/. Never store session/context docs in .codex/, .claude/, .cursor/, .windsurf/, or .agents/ — those are legacy layouts that get migrated into .safe-code/ and removed (the bridge pointers above are not session state and are preserved).

Everything lives in one shared .safe-code/ folder at the project root, regardless of which agent (Codex, Claude, Cursor, Windsurf, Copilot, Gemini) is running — continuity belongs to the project, not the tool. (Per-host bridge mechanics are defined once in the Provider Bridge section, Step 1.)

The six session files (ACTIVE.md, SESSION.md, LOG.md, BACKLOG.md, MEMORY.md, safe-refactor-code.md) sit directly inside .safe-code/. .safe-code/context/ is canonical project context; the six session files are operational session state.

Loading Layers

Layer 1 — Entry (every session)

AGENTS.md                         — root instructions and Read First order
.safe-code/context/project-overview.md       — product/project definition
.safe-code/context/architecture.md           — system boundaries and invariants
.safe-code/context/user-preferences.md       — user-approved preferences and hard dislikes
.safe-code/context/code-standards.md         — coding conventions
.safe-code/context/ai-workflow-rules.md      — workflow rules
.safe-code/context/ui-context.md             — only for UI/design work
.safe-code/context/progress-tracker.md       — Current Phase, Current Goal, Next Up, Open Questions only
ACTIVE.md                         — Before/Current/Next blocks only, if present
SESSION.md                        — Carry Forward + draft updates only, if present
LOG.md                            — last 3 typed entries only, if present

Do not read .safe-code/context/current-issues.md during normal work. Read and append to it when the user reports an issue — trigger phrases like "fix this", "failed", "got error", "bug", "crash", "tak jalan", "rosak", or a pasted stack trace — or when the user references that file. See the Issue Tracking Rule.

Layer 2 — Resume (/safe-code --continue or auto-continue)

.safe-code/context/progress-tracker.md       — full content
ACTIVE.md                         — full content
SESSION.md                        — full content
LOG.md                            — full content if Last Session.status = saved

/safe-code must auto-use Layer 2 when saved unfinished state exists, even if the user forgot --continue.

Layer 3 — Detail (triggered only)

.safe-code/context/feature-specs/<active>.md — feature/refactor work contract
.safe-code/context/architecture.md           — audit/refactor/debug impact checks
MEMORY.md                         — old/migrated architecture notes or audit detail
safe-refactor-code.md             — cleanup/refactor candidates and guardrails
BACKLOG.md                        — operational queue sync
.safe-code/CHANGELOG.md                      — releasable changes only

Do not load detail files unless the trigger condition is met.

Project Context vs Session State

.safe-code/context/current-issues.md is special: safe-code creates the template and gitignores it. Both the user and the agent write it — the user pastes raw context, and the agent appends/updates issue entries on error triggers (see the Issue Tracking Rule). It stays gitignored and may contain raw errors, URLs, or secrets, so never copy its raw content into committed docs; a sanitized one-line summary of a fixed bug goes to LOG.md instead.

.safe-code/context/user-preferences.md captures explicit, durable user preferences from conversation. Add only when the user clearly says they want/avoid something, or repeats a preference. Draft changes in SESSION.md and apply on /safe-code --save.

Source-of-Truth Ownership

Avoid duplicate truth. Each fact has exactly one canonical home:

When two files disagree, prefer executable repo evidence first, then canonical home, then session notes. Record mismatch in SESSION.md and fix canonical home on /safe-code --save.

Command Recognition (Read Before Parsing Any Command)

Different hosts wrap skill invocation differently. Treat all of the following as the same safe-code invocation, then parse the trailing argument (if any) to pick the mode:

/safe-code            /skill:safe-code        /skills safe-code
/skill safe-code      /skill safe-code        $safe-code
@safe-code            safe-code               run safe-code

Normalization rule:

1. Strip any host prefix or wrapper (/, $, @, skill:, skill , skills , run ) and the safe-code name.
2. Whatever remains is the argument. Map it to a mode:
   • empty -> /safe-code (setup / auto-resume / fresh pass)
   • --continue, continue, -c, resume -> continue mode
   • --save, save, -s, finish, end -> save mode
   • --explain, explain, explain my project, what does my app do, apa projek -> explain mode (read-only briefing)
   • fresh pass, fresh setup, ignore saved state -> force a fresh pass
3. The canonical forms are /safe-code, /safe-code --continue, /safe-code --save, /safe-code --explain. Use them in your own output, but accept any wrapper the host produced.

If the argument is unrecognized, default to plain /safe-code behavior and note which form you received. Never refuse a run just because the host used a different prefix.

Command: /safe-code

Run setup, auto-resume, or a fresh hygiene pass.

Behavior:

1. Locate project root and the single .safe-code/ folder.
2. If saved unfinished safe-code state exists, automatically behave like /safe-code --continue and print: Saved safe-code session found; resuming automatically. Say "fresh pass" to ignore saved state.
3. If no saved state exists, initialize/reconcile doc structure.
4. If any legacy layout exists (.codex/agents/, .claude/agents/, .cursor/agents/, .windsurf/agents/, v3 .agents/, or safe-code-managed root context/), run Legacy Layout Migration: move content into .safe-code/, patch old config to the new paths, remove the emptied legacy folders.
5. Explore repo facts and select the safest profile: Orientation, Audit, or Cleanup.

Start a truly fresh pass only when no saved state exists or user explicitly says fresh pass, fresh setup, or ignore saved state.

Command: /safe-code --continue

Resume an existing safe-code session with full context loading. Use this in a new chat, new day, or after /safe-code --save. /safe-code auto-enters this mode when saved state exists.

First, detect old setup config (legacy folders, old .gitignore entry, old AGENTS.md paths). If found, run Legacy Layout Migration before loading anything — saved state may still live in the old location.

Before doing work, read:

1. AGENTS.md
2. .safe-code/context/progress-tracker.md
3. ACTIVE.md
4. SESSION.md
5. LOG.md
6. active .safe-code/context/feature-specs/<file>.md if resuming a feature
7. MEMORY.md / safe-refactor-code.md only if audit/refactor/debug resumes

Do not guess previous context. If saved state contradicts repo evidence, trust executable repo evidence and record the mismatch in SESSION.md.

Command: /safe-code --save

End the session safely.

Save does these things:

0. Detect old setup config (legacy folders, old .gitignore entry, old AGENTS.md
   paths) — if found, run Legacy Layout Migration first so the save lands in
   .safe-code/ on the new version
1. Review SESSION.md draft updates
2. Apply approved context/doc updates
3. Update .safe-code/context/progress-tracker.md with safe summary only; set
   last_synced_commit to current HEAD and context_synced_at to today (Context Freshness Check)
4. Update ALL SIX session files (Six-File Save Rule below):
   - ACTIVE.md            -> Last Session block + next_action
   - SESSION.md           -> wipe to clean carry-forward template
   - LOG.md               -> append safe typed summary + a `plain:` one-line recap
                            a non-coder can read (then apply trim rule)
   - BACKLOG.md           -> sync queue from SESSION.md drafts
   - MEMORY.md            -> apply drafted audit/refactor notes
   - safe-refactor-code.md -> apply flagged candidates and guardrail changes
5. Update .safe-code/CHANGELOG.md only for releasable changes
6. Ensure local git repo exists when allowed by current repo state
7. Split the session into atomic commits (Atomic Commit Split Rule below)
8. Report commit hashes + types + local-only status + next action

Do not push.

Atomic Commit Split Rule

/safe-code --save turns the session's one save into several atomic commits grouped by logical change. The commit gate is unchanged: this still happens only at --save, stays local-only, and never pushes.

Split procedure (best-effort):

1. Read SESSION.md completed tasks and each task's recorded touched paths + commit type (Task Annotation, Measure Twice section).
2. Order commits: code/behavior tasks first in task order, then ONE final bookkeeping commit for the .safe-code/ session files + context/ updates.
3. For each group, stage only that group's paths (git add <paths>) and commit with a conventional type: subject message derived from the task. Never use --no-verify.
4. The six session files + context/ updates are ALWAYS the last commit, never mixed with code: docs: sync .safe-code session files.
5. Do not re-run verification between commits — each task was already verified per-slice during the run (Step 6). The split is a staging/commit operation over already-good changes. If a task's changes cannot stand alone, merge it with its dependency into one commit rather than emit a broken commit.

Commit type mapping:

Fallback (degrade to single commit):

if hunks overlap across tasks, the task list is thin/unannotated,
or changes cannot be cleanly separated:
  -> stage everything, make ONE local commit (today's behavior)
  -> append LOG.md note: "atomic split skipped: <reason>"

The save never fails or blocks because of splitting. Atomic splitting can only ever improve a save, never break one.

Six-File Save Rule

Every /safe-code --save MUST update all six session files in .safe-code/ — no exceptions, no "nothing changed" skips:

If a file has no new content this session, still refresh its date stamp so all six files provably reflect the last save. A save that leaves any of the six files untouched is an incomplete save — verify all six are in the commit diff before reporting done.

Draft-Until-Save Rule

During normal work, draft updates to .safe-code/context/*.md, AGENTS.md, .safe-code/CHANGELOG.md, and continuity docs in SESSION.md. Apply final persistent doc/context updates on /safe-code --save.

Exceptions:

• Create missing scaffold files/folders needed for safe operation.
• Add /.safe-code/context/current-issues.md to .gitignore during setup.
• First-Run Population (see Step 1): on the first /safe-code run, populate empty scaffold AGENTS.md + evidence-derivable context files immediately, so agents have real context without waiting for --save.
• Append/update issue entries in .safe-code/context/current-issues.md on error triggers (see the Issue Tracking Rule). This file is local-only/gitignored, so it is never part of a commit.
• Write a feature spec (including a status: suggested idea) before implementation, or whenever a new feature is proposed (see the Feature Suggestion Rule).
• Update code files as required by the user task.

The agent may append issue entries to .safe-code/context/current-issues.md, but must never copy its raw content (secrets, stack traces, private URLs) into any committed file.

Command: /safe-code --explain

Read the project brain back to the user in plain language. Read-only: make no edits, no commits, no save, and run no hygiene pass. This is for a non-technical user who wants to remember what their own project does.

Behavior:

1. If .safe-code/context/ is missing or empty -> say there is no project brain yet and suggest running /safe-code first, then stop.
2. Otherwise load project-overview.md, architecture.md, and progress-tracker.md, and brief the user in plain language — no jargon dumps, no raw file contents:

What it does:   <one or two sentences, and who it's for>
Built with:     <stack in plain terms>
Where it's at:  <current phase / what works now>
In progress:    <current goal / next up>
Open questions: <unknowns from progress-tracker, if any>

3. If the brain conflicts with executable repo evidence, trust the repo and say so briefly.

Do not load Layer 3, run helpers, audit, or touch git. --explain answers a question; it never changes the repo.

Deprecated Command Forms

• /safe-code save -> print: "Use /safe-code --save."
• /safe-code continue -> print: "Use /safe-code --continue."

How to Make Decisions

Before every action, reason explicitly. Do not guess. Do not skip this.

Measure Twice, Cut Once Policy

Every run must maintain a visible task checklist in SESSION.md. The checklist is the working plan and progress tracker.

HARD RULE: Keep the codebase clean, no tmp files, no dead code, no dead files. Stay organized all the time. No unnecessary folders, subfolders, or files.

Rules:

• Create or refresh SESSION.md ## Task List before Step 3.
• Every meaningful task starts as [ ].
• Mark a task [~] while actively working on it.
• Mark a task [x] only after the action and its verification are complete.
• Add newly discovered work as a new task instead of doing it invisibly.
• Draft unrelated or deferred tasks for BACKLOG.md in SESSION.md; do not hide them in prose.
• On /safe-code --save, migrate unfinished checklist items into ACTIVE.md Last Session.pending and next_action.
• Do not claim completion unless the checklist, verification output, and final summary agree.
• If verification fails, keep the task [~] or [ ], add the failure note, and route to $debug-issue when appropriate.
• When marking a task [x], annotate it with the paths it touched and its commit type, so /safe-code --save can map each task to one atomic commit (Atomic Commit Split Rule). Record paths while the info is fresh; never reconstruct at save time. A missing annotation is a thin task list — the split falls back to a single commit.

Task annotation format:

- [x] remove unused dateUtil  · type: refactor · files: src/utils/dateUtil.ts

Default checklist:

## Task List
- [ ] Locate project root and `.safe-code/` folder
- [ ] Initialize or reconcile AGENTS.md, context, and session docs
- [ ] Detect saved state or legacy layout migration need
- [ ] Load required context for this command
- [ ] Check context freshness (drift vs last_synced_commit)
- [ ] Draft or update active feature spec if needed
- [ ] Check git state and rollback safety
- [ ] Check or bootstrap graph support when useful
- [ ] Explore repo facts before context backfill
- [ ] Run context self-test after backfill (verify brain is sufficient)
- [ ] Audit dead code and stale files only when in scope
- [ ] Audit agent config trust artifacts when in scope
- [ ] Decide run profile and execution mode
- [ ] Execute scoped code changes if requested
- [ ] Review changes and test coverage
- [ ] Debug verification failures, if any
- [ ] Draft docs/context updates in SESSION.md
- [ ] Save final docs/context updates on /safe-code --save

Decision Framework

1. What are the 2-3 options?
2. What does each risk or preserve?
3. Which is safest given what I know?
4. Can this be undone?
5. What am I assuming? → verify from codebase first; ask only if cannot verify

If assumption is about user intent (not a technical fact) → verify from codebase first. If assumption cannot be verified from codebase → stop and ask.

If (4) = no → stop, show options to user before acting. If (4) = yes → proceed with safest option, log reasoning.

Act Autonomously When

• Action is reversible (git tracked)
• Confidence is High (zero references, no dynamic risk)
• Decision is technical, not about user intent
• Answer is discoverable from the codebase

Stop and Ask When

• Action is irreversible (no git, no backup)
• Confidence is Low
• Unexpected scope change (blast radius > 10 files)

Never ask about Medium confidence candidates — apply auto-promotion rule instead.

Reasoning Format

Reasoning:
  Options: <list>
  Risk: <list>
  Decision: <chosen>
  Why: <one sentence>
  Reversible: yes/no
  Assumptions: <list — or "none">

Step 0: Locate Project Root

Session state lives in a single agent-agnostic folder at the project root:

safe-code folder = <project-root>/.safe-code/

No agent detection is needed. Codex, Claude, Cursor, and Windsurf all share the same .safe-code/ folder so continuity belongs to the project, not the tool. Create <project-root>/.safe-code/ if it does not exist.

HARD RULE: never create .codex/, .claude/, .cursor/, .windsurf/, or .agents/ folders for session state. If any of them exist with safe-code docs inside, run Legacy Layout Migration (Step 1) — migrate their content into .safe-code/ and remove them. Exception: the Provider Bridge (Step 1) may write a thin read-pointer in a host's native config location (e.g. .cursor/rules/safe-code.mdc, .github/copilot-instructions.md); these hold no state, only a redirect to AGENTS.md/.safe-code/, and are never treated as legacy.

Step 1: Initialize Doc Structure

Create only the scaffold needed for safe operation before reading the codebase. Do not populate long-term context with guesses.

Create missing folders/files:

AGENTS.md
CLAUDE.md                        (provider bridge — pointer only)
GEMINI.md                        (provider bridge — pointer only)
.github/copilot-instructions.md  (provider bridge — pointer only)
.cursor/rules/safe-code.mdc      (provider bridge — pointer only)
.safe-code/CHANGELOG.md
.safe-code/context/
.safe-code/context/project-overview.md
.safe-code/context/architecture.md
.safe-code/context/user-preferences.md
.safe-code/context/code-standards.md
.safe-code/context/ai-workflow-rules.md
.safe-code/context/ui-context.md
.safe-code/context/progress-tracker.md
.safe-code/context/current-issues.md
.safe-code/context/feature-specs/
.safe-code/context/feature-specs/00-template.md
.safe-code/ACTIVE.md
.safe-code/SESSION.md
.safe-code/LOG.md
.safe-code/BACKLOG.md
.safe-code/MEMORY.md
.safe-code/safe-refactor-code.md

Rules:

• If a file exists, do not overwrite it.
• Create missing context files with templates only.
• Add /.safe-code/context/current-issues.md to .gitignore if absent.
• The user owns .safe-code/context/current-issues.md; the agent only appends issue entries on error triggers (Issue Tracking Rule) and never copies its raw content into committed files.
• For project facts, inspect repo evidence first.
• On the first run (empty scaffold), populate evidence-derivable context files immediately (First-Run Population below). On later runs, draft updates in SESSION.md and apply on /safe-code --save unless a scaffold file or active feature spec is required now.

Existing Project Backfill

If the repo already has code, docs, manifests, routes, schemas, tests, or configs:

• Treat the repo as source of truth.
• Backfill .safe-code/context/*.md from evidence only.
• Put unverifiable product or architecture facts into .safe-code/context/progress-tracker.md Open Questions.
• Generate feature specs for upcoming work, active bugs, refactors, or missing documentation units; record new feature ideas as status: suggested specs (Feature Suggestion Rule).
• Do not create fake historical specs for completed features unless the user asks.

First-Run Population

The whole point of the first run is that any agent can read real context afterward and not hallucinate. So on the first /safe-code run — when the target file is still an empty scaffold — write context immediately instead of waiting for --save:

Rules:

• This immediate-write exception applies only while a file is an empty scaffold. Once it holds real content, later edits revert to Draft-Until-Save.
• Never invent facts. Anything not provable from repo evidence is an Open Question, not a populated claim.
• Still draft this session's ongoing changes in SESSION.md; First-Run Population is about seeding empty context, not about live edits.
• After populating, run the Context Self-Test to verify the brain is sufficient; fill or flag any gaps it finds.

Provider Bridge

AGENTS.md + .safe-code/ are the source of truth, but not every host auto-reads AGENTS.md. So safe-code writes thin pointer files in each major host's native config location, so a fresh chat in any provider loads the same brain without the user invoking safe-code:

Rules:

• Bridges are pointers, not state — each is a few lines that redirect to AGENTS.md + .safe-code/context/. Never duplicate project facts into them.
• Never overwrite an existing host file. If it exists and does not already point at AGENTS.md/.safe-code/, append one clearly-marked <!-- safe-code:bridge --> block; if it already points there, leave it.
• Bridges are scaffold/pointer files — write them immediately (like AGENTS.md), not draft-until-save.
• Preserve bridges during Legacy Layout Migration; they are not legacy session state.
• Read fallback shapes from references/doc-templates.md (Provider Bridge Files).

Legacy Layout Migration

Older safe-code versions left other folders and config in the repo. Detect them on every safe-code command — /safe-code, /safe-code --continue, and /safe-code --save — and migrate immediately (this is a scaffold operation — it does not wait for --save):

Pre-v3 layout:  .codex/agents/  .claude/agents/  .cursor/agents/  .windsurf/agents/
                .codex/memory/  .claude/memory/  .cursor/memory/  .windsurf/memory/
v3 layout:      .agents/  (six session files)  +  root context/  +  root CHANGELOG.md
                created by safe-code (gitignore entry /context/current-issues.md is the marker)

Migration steps (per legacy location found):

1. Move every safe-code *.md into its new home — git mv when tracked, plain move otherwise:
   • session docs (ACTIVE.md, SESSION.md, LOG.md, BACKLOG.md, MEMORY.md, safe-refactor-code.md) -> .safe-code/
   • root context/ -> .safe-code/context/
   • root CHANGELOG.md -> .safe-code/CHANGELOG.md (skip if the repo never had safe-code manage it and the user objects)
2. Never overwrite: if the destination file already exists, keep the legacy file in place, report the conflict, and let the user merge.
3. Patch old config to the new version wherever the repo uses it:
   • .gitignore: replace /context/current-issues.md with /.safe-code/context/current-issues.md
   • AGENTS.md: rewrite Read First paths and any context/, .agents/, .codex/agents/ references to .safe-code/ paths
   • any other repo doc safe-code wrote that points at old paths
4. Remove each legacy folder once it is empty — including a now-empty .codex/, .claude/, .cursor/, or .windsurf/ parent. Never remove a folder that still holds unmigrated or non-safe-code files; report what was left behind instead.
5. Log the whole migration as one typed decision entry in LOG.md.

Content mapping when old continuity docs are thin or pre-date context/:

• MEMORY.md -> draft candidate facts for .safe-code/context/architecture.md
• BACKLOG.md -> draft Next Up / Open Questions for .safe-code/context/progress-tracker.md
• ACTIVE.md -> draft Current Goal / In Progress for .safe-code/context/progress-tracker.md
• LOG.md -> safe decision summaries only
• existing AGENTS.md -> preserve verified rules and add Read First section

Migration rules:

• File moves and config patches happen now; content rewrites (mapping above) are drafted in SESSION.md and applied on /safe-code --save.
• Do not copy raw logs, secrets, stack traces, private URLs, or current-issues.md content into context files.
• Mark uncertain migrated facts as Open Questions.
• After migration, .safe-code/context/ is canonical project context; the six session files in .safe-code/ remain session state.

Doc + Session Templates (loaded on demand)

Do not inline template bodies here. When creating or reconciling scaffold files in Step 1, read the fallback shapes from the skill's references/ folder and apply them only to missing files:

• references/agents-md-authoring.md — AGENTS.md template and the canonical AGENTS.md authoring rules. This is the single source of truth for how to write AGENTS.md; helper skills defer to it when run under safe-code.
• references/doc-templates.md — fallback shapes for .safe-code/CHANGELOG.md, every .safe-code/context/*.md file, and every .safe-code/*.md session file (ACTIVE, SESSION, BACKLOG, LOG, MEMORY, safe-refactor-code), including the Flagged Dead Code entry format.
• references/examples.md — worked end-to-end examples of correct runs (Orientation / Audit / Cleanup profiles and --save), plus anti-patterns. Read it when unsure what the shape of a good run looks like.
• references/agent-config-audit.md — scope, scan patterns, and High/Medium/Info classification for the Step 4b Agent Config Trust Audit. Read it only when that step runs.

Rules when applying templates:

• Never overwrite a file that already exists; create missing files with the template shape only.
• When creating, populating, or reconciling AGENTS.md, follow the authoring rules in references/agents-md-authoring.md instead of filling the template blindly.
• Draft real content in SESSION.md and finalize on /safe-code --save, except scaffold files and active feature specs.

1c. Confirm Initialization

Project root: <path>
Safe-code folder: <project-root>/.safe-code/

Root:    AGENTS.md - <created|exists|populated>
Bridges: CLAUDE.md / GEMINI.md / copilot-instructions.md / cursor rule - <created|exists|appended|skipped>
Folder:  .safe-code/ - <created|exists|migrated>  |  CHANGELOG.md - <created|exists>
Context: context/ - <created|exists|migrated>     |  feature-specs/ - <created|exists>
         current-issues.md - <created|exists|gitignored>
Session: ACTIVE.md - <created|exists>             |  SESSION.md - <created|exists>
         BACKLOG.md - <created|exists>            |  LOG.md - <created|exists>
         MEMORY.md - <created|exists>             |  safe-refactor-code.md - <created|exists>
Legacy:  <none found | migrated + removed: <list> | conflicts left for user: <list>>

All paths inside project root. Proceeding.

Step 2: Load Context + Detect Session Mode

2a. Load Layer 1 (always, every session)

Load the Layer 1 — Entry file set defined in Loading Layers above, reading only the indicated slice of each file. Do not keep a second copy of the list here (single source of truth).

Do not read .safe-code/context/current-issues.md during normal work. Read and append to it on issue triggers ("fix this", "failed", "got error", pasted stack trace) or when the user references that file (Issue Tracking Rule).

2b. Detect saved session from ACTIVE.md

This step is mandatory for both /safe-code and /safe-code --continue.

if Last Session.status = "saved" and pending/next_action exists:
  -> Auto-continue, even for plain /safe-code
  -> Load Layer 2: .safe-code/context/progress-tracker.md full + ACTIVE.md full + SESSION.md full + LOG.md full
  -> Print: "Saved safe-code session found; resuming automatically. Say 'fresh pass' to ignore saved state."
  -> Print: "Pending: <pending> | Next: <next_action>"
  -> Skip completed slices
  -> Resume from next_action directly

if Last Session.status = "completed":
  -> Load Layer 1 only
  -> Start new pass unless user asks to inspect previous work

if Last Session.status = "none" or block missing:
  -> Load Layer 1 only
  -> Start setup/orientation

If the user explicitly says fresh pass, fresh setup, or ignore saved state, do not auto-continue. Record this in SESSION.md.

2c. Create or Update Task List

Before Step 3, write SESSION.md ## Task List.

if /safe-code with no saved state:
  -> create fresh default checklist
  -> mark completed setup items [x] as they finish

if /safe-code auto-continues or /safe-code --continue:
  -> load unfinished items from ACTIVE.md Last Session.pending
  -> merge them with default checklist
  -> keep completed items visible only if needed to avoid repeated work

if /safe-code --save:
  -> read current checklist
  -> migrate unchecked or active items into ACTIVE.md Last Session.pending
  -> set next_action to first unfinished task

Use the canonical Default checklist from the Measure Twice, Cut Once Policy section above as the base — do not maintain a second, divergent copy here (single source of truth). Then adapt it per the mode block above (fresh / resume / save).

Update checklist after every major step. Never wait until final summary to mark progress.

Last Session block (written by /safe-code --save)

## Last Session
status: saved
saved_at: <ISO timestamp>
completed:
  - <slice>
pending:
  - <slice>
next_action: <what to do on resume>

After all pending done, reset to:

## Last Session
status: completed
saved_at: <ISO timestamp>
completed: all
pending: []
next_action: none

LOG.md Trim Rule

Check LOG.md line count on every /safe-code --save.

if LOG.md > 200 lines:
  -> Collect all entries older than 7 days
  -> Summarize them into one block at the bottom:

  ## Archived Summary [<oldest date> - <7 days ago>]
  - <bullet summary of what happened in that period>

  -> Keep last 7 days of entries as-is above the archive block
  -> Never delete any information — only compress old entries
  -> Append new entries above everything as usual

This keeps LOG.md scannable without losing history.

Context Checkpoint Rule

Long runs lose context to compaction. Unsaved state must never be the casualty.

A checkpoint = update SESSION.md now (task list states, draft updates, current slice) so auto-resume from ACTIVE.md/SESSION.md works even if the session dies right after.

Checkpoint triggers:

- A run phase completes: orientation done, audit done, config audit done,
  each execute slice verified
- Scope grows unexpectedly mid-run
- The host warns about context pressure/compaction, or own output starts
  referring to stale facts

If context pressure is high mid-run: checkpoint first, then suggest the user run /safe-code --save and resume with /safe-code --continue in a fresh session. Do not push through with degraded context.

Context Freshness Check

A fresh chat must read current context, not a stale brain. safe-code stamps the commit it last synced context to, and checks drift on every run.

Stamp: .safe-code/context/progress-tracker.md carries last_synced_commit: <hash> and context_synced_at: <date>, written on /safe-code --save.

On /safe-code and /safe-code --continue, after loading context:

1. last_synced_commit missing -> context was never synced; treat empty files as First-Run Population and flag populated-but-unstamped files for a refresh check.
2. last_synced_commit == current HEAD -> brain is fresh; no refresh needed.
3. They differ -> run a quick drift scan on signal files in last_synced_commit..HEAD:
   • dependency manifests/locks (package.json, *-lock*, requirements*.txt, pyproject.toml, go.mod, Cargo.toml, Gemfile, …)
   • top-level folder add / remove / rename
   • build/test/run scripts and config (tsconfig, linter/formatter, CI, framework config)
   • AGENTS.md / .safe-code/context/* themselves
4. Signal files changed -> mark the affected context sections possibly stale, refresh them from current repo evidence (draft in SESSION.md, apply on --save), and note it in the summary. Only unrelated files changed -> context stays vali

…(truncated)