Progress hygiene rules

Progress Hygiene Rules — Hard Constraints

Companion rule-skill to 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:

## [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:

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
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).