# Progress Hygiene Rules

> Progress file hard constraints. MUST maintain exactly one progress root per project per the location matrix, valid frontmatter with absolute dates on every progress doc, NN- numeric prefix only for time-ordered children in progress/ and research/ trees (never skill references), archive when files exceed ~200 lines preserving content verbatim, relative paths in all cross-file references. NEVER place progress under .claude/, maintain two progress files with mutual references, use relative dates, duplicate child content into parent, summarize archived content, or discard completed history. Activates on any progress file edit, migration, or new-session handoff. MUST read SKILL.md BEFORE editing, creating, moving, or archiving any progress or research tree file.

- Skill: `motiful/progress-hygiene-rules` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add motiful/progress-hygiene-rules`
- Raw SKILL.md: https://api.skillmd.com/api/skills/motiful/progress-hygiene-rules/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- License: MIT
- Author: motiful (https://skillmd.com/u/motiful)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/motiful/progress-hygiene-rules

---


# Progress Hygiene Rules — Hard Constraints

> Companion rule-skill to [`progress-hygiene`](../progress-hygiene/). This file enforces; the capability skill teaches.
> Treat every MUST/NEVER below as equivalent authority to platform-native rule files. Meta-rule protocol (rules-as-skills) raises load priority to MUST-level automatically on any `-rules` suffix skill.
> Immutable by agent self-modification.

## Scope

Applies to every file that participates in a project progress tree or research tree. Specifically:

- `progress/` directories and their descendants
- `progress.md` files (flat, Archetype A2)
- `research/<topic>/` trees
- `<project>-backstage/progress/` under split-repo archetypes
- Any `PROGRESS.md` or `progress.md` file currently existing (migration targets)

Does **not** apply to: skill `references/` directories, skill `scripts/`, design documents, or code files.

## Location Constraints

- **MUST** locate exactly one progress root per project, determined by the project archetype per the progress-hygiene location matrix. Two roots cause drift; non-matrix locations cause confusion.
- **NEVER** place progress files under any `.claude/`, `.agents/`, or other agent-workspace directory. Those directories are for skill/rule/setting config, not project state.
- **NEVER** maintain two progress files in the same project with mutual cross-references. The design-playbook 2026-04-18 incident is the reference failure mode.
- **MUST** declare "Source of Truth" explicitly at the top of the authoritative progress root when the project legitimately has multiple related repos (e.g., skill + backstage). Agents editing other repos must see this declaration and edit the SoT only.

## Frontmatter Constraints

- **MUST** include a YAML frontmatter block with `title`, `created`, `updated`, `status` on every progress, research, and tree-entry document.
- **MUST** use absolute ISO dates (`YYYY-MM-DD`). **NEVER** use relative phrasing (`yesterday`, `Thursday`, `last week`) in these fields.
- **MUST** use exactly one of the four `status` values: `draft`, `active`, `stale`, `archived`. No synonyms or custom states.
- **MUST** update the `updated` field on every substantive edit.
- **NEVER** use filesystem `mtime` as a substitute for the `updated` field. `mtime` is clobbered by `git clone`, editor auto-save, and indexers.

## Naming Constraints

- **MUST** use lowercase directory names (`progress/`, not `Progress/` or `PROGRESS/`).
- **MUST** name tree entry files `README.md`, not `index.md` or redundant `PROGRESS.md`.
- **MUST** use zero-padded two-digit `NN-<slug>.md` prefix for children of `progress/` and `research/<topic>/` trees. Order reflects creation sequence, not current priority.
- **NEVER** apply `NN-` prefix to skill `references/`, `scripts/`, or `design/` directories. Those are functional modules, not timelines — prefixing them misrepresents the structure.
- **NEVER** rename files to reflect priority changes. Use the `status` field and parent summary line instead; the prefix preserves chronology.

## Tree Structure Constraints

- **MUST** open a child subtree before the parent progress file exceeds ~150 lines, or when a subtask is complex enough to spawn its own session.
- **MUST** reference children from parents by **pointer** — summary line plus relative link. **NEVER** duplicate child content into parent text; copy-style references always drift.
- **MUST** use relative paths in all parent-child and archive links. Absolute paths break when the repo is cloned or moved.
- **MUST** update the parent summary line when a child's `status` transitions (`active → archived`, etc.) within the same commit.
- **NEVER** exceed 3 levels of nesting below the progress root. Level-3 children usually indicate a task decomposition failure, not a depth requirement.

## Archive Constraints

Inherited from the deprecated `progress-archive` skill and extended:

- **MUST** archive completed phases when a progress file exceeds ~200 lines. Long files waste agent context and bury current state.
- **MUST** preserve archived text **verbatim**. Archive is a historical record, not a summary.
- **MUST** archive a section only when all its sub-tasks are complete. Sections with open sub-tasks must be restructured first — move the incomplete tasks to an active section, then archive the rest.
- **MUST** keep all incomplete tasks and their context untouched in the main file. Removing context that open tasks depend on breaks continuity.
- **MUST** name archive files with a date suffix: `{original-stem}-{milestone}-{YYYY-MM-DD}.md`.
- **NEVER** summarize, paraphrase, or rewrite content when archiving. Lossy compression destroys decisions and rationale that future work depends on.
- **NEVER** delete completed content. Archive is move, not delete.
- **SHOULD** keep recent update-log entries (last ~2 weeks of changes) in the main file and move older entries with the archive. The main file carries current-momentum signal; deep history belongs in the archive. Inherited verbatim from the deprecated `progress-archive` skill's line 23.

## Compression Stub Template

When a section is archived, leave this stub in the main file:

```markdown
## [Phase/Milestone Name] — Archived

**Completed**: YYYY-MM-DD
**Archive**: `relative/path/to/archive-file.md`

**Summary** (headline only, not content):
- Key output 1
- Key output 2

**Decisions carried forward** (affecting open work):
- Decision 1
- Decision 2
```

The stub exists to give context to open work, not to reproduce archived detail. If you find yourself copying content into the stub, stop — the archive file is one click away.

## Handoff Constraints

- **MUST** generate a handoff prompt from the progress tree, not from chat history. The tree carries state; chat history is ephemeral.
- **MUST** name specific files for the incoming session to read (3-5 files). **NEVER** instruct the new session to "read everything" or "continue where we left off".
- **MUST** include a first-step confirmation gate in the handoff prompt: incoming session reads, summarizes understanding, waits for user confirmation. **NEVER** instruct the new session to begin work immediately.
- **MUST** save the handoff prompt as a file in the progress tree (typically `NN-session-prompt-<slug>.md`), not as inline chat text. The prompt itself becomes tree history.

## Verification Procedure (for Agents)

Before finalizing any edit to a progress-tree file:

```python
def verify_compliance(file, tree):
    # Location
    assert tree.root_is_unique(), "multiple progress roots detected"
    assert not file.path.contains(".claude/"), "progress must not live under .claude/"

    # Frontmatter
    fm = file.frontmatter
    assert fm is not None, "frontmatter missing"
    assert {"title", "created", "updated", "status"} <= fm.keys()
    assert fm.dates_are_absolute()
    assert fm.status in {"draft", "active", "stale", "archived"}

    # Naming
    if file.is_child_of(["progress/", "research/"]):
        assert file.name matches r"^\d{2}-[a-z0-9-]+\.md$"
    if file.is_child_of(["references/", "scripts/", "design/"]):
        assert not file.name matches r"^\d{2}-"

    # Tree structure (if file has a parent)
    if file.parent_progress_doc:
        parent = file.parent_progress_doc
        assert parent.references_child_as_pointer(file)
        assert not parent.duplicates_child_content(file)

    # Archive (if archiving)
    if action == "archive":
        assert all_subtasks_complete(section)
        assert archive_path ends with f"-{today:YYYY-MM-DD}.md"
        assert archive_content == original_content  # verbatim
```

Fail any check → do not commit. Fix the underlying violation first.

## Deprecation of progress-archive

The standalone `progress-archive` skill was archived on 2026-04-21. Its archive-threshold and verbatim-preservation rules are absorbed into §Archive Constraints above. Existing installations should:

1. Uninstall `progress-archive` (`npx skills remove motiful/progress-archive` or remove symlinks)
2. Install this rule-skill paired with [`progress-hygiene`](../progress-hygiene/)
3. The original GitHub repo is archived but remains available for historical reference

## Relationship to progress-hygiene (Capability)

This rule-skill and `progress-hygiene` are an **Augmented Skill collection** (per skill-forge publishing strategy):

- `progress-hygiene` is the primary capability — intent-triggered ("create a progress file", "open a subtree", "hand off to new session")
- This rule-skill is the augmenter — environment-triggered (activates on any progress file edit regardless of user intent phrasing)
- Forking the primary without this rule-skill silently breaks the methodology — the MUST/NEVER boundaries stop being enforced

The collection is installed together. Maintenance-dependency is uni-directional: this rule-skill exists to constrain progress-hygiene's iterations and cannot stand alone (it has no meaning without the capability's vocabulary).