---
name: eck:restore-project
version: "0.7.4"
description: Restore an archived project in the global registry, reactivating it for monitoring and health tracking.
disable-model-invocation: false
---

# Restore Project

Restore a previously archived project in the global registry. Sets the project state back to `managed` and resets `audit_status` to `pending` so a fresh health check runs on next audit.

---

## Visual Framework

Follow these conventions for all terminal output displayed to the user via the Bash tool.

### Output Mode Awareness

Before producing output, read the user's preferred output mode:

```bash
cat $ECK_HOME/user-preferences.json 2>/dev/null
```

Extract the `outputMode` field and adapt verbosity:

- **guided** — Add explanatory prose after key steps. Describe what is happening and why.
- **standard** (default) — Balanced. Show steps with brief context for non-obvious decisions.
- **concise** — Steps and summary box only. No prose, no explanations.

If the file is missing or `outputMode` is absent, use **standard**.

### ANSI Colors

Declare these variables at the top of **every** Bash tool call (shell state does not persist between calls):

```bash
source $ECK_HOME/colors.sh
```

Every color sequence **must** end with `${RESET}`. No exceptions.

### Stage Banners

Mark major stage transitions with a banner. One blank line before and after.

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}STAGE NAME${RESET}"
echo ""
```

### Status Symbols

| Symbol | Meaning          | Color       |
| ------ | ---------------- | ----------- |
| `[*]`  | Active / running | `${CYAN}`   |
| `[x]`  | Completed        | `${GREEN}`  |
| `[!]`  | Error            | `${RED}`    |
| `[-]`  | Skipped          | `${DIM}`    |
| `[>]`  | In progress      | `${YELLOW}` |
| `[ ]`  | Pending          | `${DIM}`    |

No emoji in output. Use only these bracket symbols for status.

### Summary Boxes

Display at checkpoints and at the end of the skill. One blank line before and after.

```bash
echo ""
printf '%b\n' "${ORANGE}${BOLD}Title${RESET}"
echo ""
printf '%b\n' "Label: Value"
echo ""
```

### Error Format

```bash
printf '%b\n' "${RED}[!]${RESET} Error message here"
printf '%b\n' "    ${DIM}Recovery guidance here.${RESET}"
```

### Spacing Rules

- One blank line before and after stage banners and summary boxes.
- No blank lines within step lists.
- Maximum output line width: 70 characters.

### Statusline Stage Updates

At the **start** of each stage, update the statusline:

```bash
bash $ECK_HOME/update-stage.sh "{Statusline text from table}"
```

At **skill completion** (success or error), reset:

```bash
bash $ECK_HOME/update-stage.sh
```

---

## Task Registration

| Stage | Subject          | Active Form        | Statusline    |
| ----- | ---------------- | ------------------ | ------------- |
| 1     | Stage 1: Lookup  | Looking up project | Lookup (1/3)  |
| 2     | Stage 2: Restore | Restoring project  | Restore (2/3) |
| 3     | Stage 3: Summary | Generating summary | Summary (3/3) |

## Usage

```bash
/eck:restore-project {PROJECT_KEY}     # Restore by project key
```

A project key is required — restore does not auto-detect from the current directory since archived projects may have been relocated.

---

## Stage 1: Lookup

### Inputs

- `PROJECT_KEY` argument (required)
- `$ECK_HOME/registry.yaml`

### Activities

1. If no `PROJECT_KEY` argument provided:

   ```bash
   printf '%b\n' "${RED}[!]${RESET} PROJECT_KEY is required"
   printf '%b\n' "    ${DIM}Usage: /eck:restore-project {PROJECT_KEY}${RESET}"
   printf '%b\n' "    ${DIM}Run /eck:project-status to see archived projects.${RESET}"
   ```

   STOP.

2. Load `$ECK_HOME/registry.yaml`. If the registry does not exist:

   ```bash
   printf '%b\n' "${RED}[!]${RESET} Registry not found at $ECK_HOME/registry.yaml"
   printf '%b\n' "    ${DIM}Run: npx @evolvconsulting/evolv-coder-kit --global${RESET}"
   ```

   STOP.

3. Look up `projects.<PROJECT_KEY>`.
   If no matching entry found:

   ```bash
   printf '%b\n' "${RED}[!]${RESET} Project '{PROJECT_KEY}' not found in registry"
   printf '%b\n' "    ${DIM}Run /eck:project-status to see all projects.${RESET}"
   ```

   STOP.

4. If the project's `state` is NOT `archived`:

   ```bash
   printf '%b\n' "${YELLOW}[>]${RESET} Project '{PROJECT_KEY}' is not archived (state: {state})"
   printf '%b\n' "    ${DIM}Only archived projects can be restored.${RESET}"
   ```

   STOP.

5. Validate the state transition: `archived` → `managed` is valid per `ops:registry-update` state machine.

6. Check if `project_path` still exists on disk:

   ```bash
   ls -d "{project_path}" 2>/dev/null
   ```

   If path does not exist, warn but allow restore:

   ```bash
   printf '%b\n' "${YELLOW}[>]${RESET} Project path not found: {project_path}"
   printf '%b\n' "    ${DIM}The project directory may have been moved.${RESET}"
   printf '%b\n' "    ${DIM}Update project_path in the registry after restore.${RESET}"
   ```

7. Display the project summary for confirmation:

   ```bash
   source $ECK_HOME/colors.sh

   echo ""
   printf '%b\n' "${ORANGE}${BOLD}Restore Project${RESET}"
   echo ""
   printf '%b\n' "${CYAN}[*]${RESET} Project:       {project_name}"
   printf '%b\n' "${CYAN}[*]${RESET} Key:           {project_key}"
   printf '%b\n' "${CYAN}[*]${RESET} Path:          {project_path}"
   printf '%b\n' "${CYAN}[*]${RESET} Archived:      {last sync_history entry with action='archive' date}"
   printf '%b\n' "${CYAN}[*]${RESET} Last Audit:    {last_audit.date or 'never'}"
   printf '%b\n' "${CYAN}[*]${RESET} Health:        {last_audit.health_grade or 'N/A'}"
   echo ""
   printf '%b\n' "${YELLOW}[>]${RESET} Restoring will:"
   printf '%b\n' "    - Set state to 'managed'"
   printf '%b\n' "    - Reset audit_status to 'pending'"
   printf '%b\n' "    - Include in active project counts"
   printf '%b\n' "    - Re-enable health monitoring"
   printf '%b\n' "    - NOT modify any project files"
   echo ""
   ```

### Outputs

- Project entry loaded into memory
- Project summary displayed to user
- Path existence check performed

### Exit Criteria

- Project entry found with `state: "archived"`
- User has seen the project summary

---

## Stage 2: Restore

### Inputs

- Project entry from Stage 1
- User confirmation

### Activities

1. Ask for explicit user confirmation using AskUserQuestion:
   - Question: "Restore project '{project_name}' to managed state?"
   - Options: "Yes, restore it", "No, cancel"

   If user cancels:

   ```bash
   printf '%b\n' "${DIM}[-]${RESET} Restore cancelled"
   ```

   STOP.

2. **Reference:** `ops:registry-update` primitive for the canonical read-modify-write procedure.

3. Read `$ECK_HOME/registry.yaml`.

4. Update the project entry:
   - Set `state: "managed"`
   - Set `audit_status: "pending"` (force re-audit after restoration)
   - Set `last_modified_at` to current ISO-8601 date

5. Append `sync_history` entry:

   ```yaml
   - date: "{DATE}"
     action: "restore"
     performed_by: "/eck:restore-project"
     summary: "Restored to managed state, audit_status reset to pending"
   ```

6. Recompute `project_summary` per the `ops:registry-update` primitive.

7. Copy `registry.yaml` to `registry.yaml.bak`.

8. Atomic write: write to `registry.yaml.tmp`, then rename to `registry.yaml`.

### Outputs

- Registry updated with `state: "managed"`, `audit_status: "pending"`
- sync_history entry appended
- project_summary recomputed

### Exit Criteria

- Project state is `managed` in registry
- audit_status is `pending`
- project_summary reflects the change (active_projects incremented)

---

## Stage 3: Summary

### Inputs

- Updated registry state from Stage 2

### Activities

1. Display completion summary:

   ```bash
   source $ECK_HOME/colors.sh

   echo ""
   printf '%b\n' "${ORANGE}${BOLD}Project Restored${RESET}"
   echo ""
   printf '%b\n' "Project: {project_name}"
   printf '%b\n' "Key: {project_key}"
   printf '%b\n' "State: managed"
   printf '%b\n' "Audit Status: pending"
   printf '%b\n' "Active Projects: {updated_active_count}"
   echo ""
   printf '%b\n' "${GREEN}[x]${RESET} Restore complete"
   echo ""
   printf '%b\n' "${YELLOW}[>]${RESET} Next steps:"
   printf '%b\n' "    1. Run /eck:audit-current-project for a health check"
   printf '%b\n' "    2. Run /eck:pull-from-global-catalog for latest updates"
   echo ""
   ```

2. Reset statusline:
   ```bash
   bash $ECK_HOME/update-stage.sh
   ```

### Outputs

- Summary displayed to user
- Statusline reset

### Exit Criteria

- User has seen the completion summary with next steps
- Statusline is cleared

---

## Error Handling

Reference: `output:error-handler` primitive for standardized error formatting.

| Error               | Recovery                                        |
| ------------------- | ----------------------------------------------- |
| Registry not found  | Direct user to install global infrastructure    |
| Project not found   | Suggest `/eck:project-status` to list projects  |
| Not archived        | Explain only archived projects can be restored  |
| Path not found      | Warn but proceed; user can update path manually |
| Atomic write failed | Log error, original registry remains intact     |

---

## Related Documents

- [/eck:archive-project](../archive-project/SKILL.md) — Archive a managed project
- [/eck:project-status](../project-status/SKILL.md) — View project registry dashboard
- [/eck:audit-current-project](../audit-current-project/SKILL.md) — Run health check after restore
- [ops:registry-update primitive](../../../project/primitives/core/ops/registry-update.md) — Canonical registry write procedure
