git-slop 0.9.2

Deterministic repository health and maintenance-pressure analysis for humans and AI agents.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# .slop Directory Policy

Git Slop writes repository-local state under `.slop/`.

```text
.slop/
  config.yaml
  .gitignore
  latest/
    report.json
    report.yaml
    summary.md
    health.md
  runs/
    <timestamp>/
      report.json
      report.yaml
      summary.md
      health.md
  cache/
```

## Commit

Commit these files when the repository intentionally adopts Git Slop:

- `.slop/config.yaml`
- `.slop/.gitignore`

`config.yaml` is the repo-owned detector configuration. `.gitignore` keeps
routine generated state out of source control.

## Do Not Commit Routine Outputs

Do not commit these runtime outputs:

- `.slop/latest/`
- `.slop/runs/`
- `.slop/cache/`
- `.slop/prompt-packs/`
- generated SARIF files
- generated plan JSON
- generated compare JSON

Use CI artifacts or local scratch paths for those files. They are derived from
the repo state and should be regenerated when needed.

The GitHub Action follows a bounded upload policy instead of uploading either
runtime directory:

- default `summary`: `health.md` only
- opt-in `report`: `health.md` and `report.json`
- opt-in `full`: the four allowlisted files from `.slop/latest/`

The default artifact retention is 14 days. Prefer the default unless a machine
consumer needs schema-4 JSON or a reviewer explicitly needs the full bundle.

## Exceptions

Only check in generated-looking artifacts when they are deliberately curated as
examples or fixtures outside the runtime `.slop/` tree. Common examples:

- `tests/fixtures/...`
- documentation snippets with small hand-edited samples
- versioned files attached to GitHub Releases, not committed to Git

If a consumer repo needs stable evidence for review, prefer an uploaded CI
artifact or a link to a GitHub Release asset over committing `.slop/latest/`.

## Cache Notes

`.slop/cache/` is generated state reserved for deterministic performance
optimizations. It is safe to delete and must never be required for correctness.

## Bundle Notes

`find` writes the complete four-file bundle to both destinations. The latest
bundle is replaced atomically so consumers do not observe a partially updated
report set. Timestamped run directories are immutable snapshots of individual
detector runs.

`health`, `show`, `explain`, `plan`, `check`, and `sarif` read an existing
report. `compare` reads two. They do not create another detector run; only
explicit prompt-pack, SARIF output, or redirected command output writes
additional generated files.