feat(profile): single-source-of-truth sin-profile.md + per-agent renderers (issue #175) (#202)

Co-authored-by: SIN CI <ci@opensin-code.local>

Author: Delqhi

.github/workflows/ceo-audit.yml

@@ -224,3 +224,66 @@ jobs:
           sarif_file: ${{ github.workspace }}/ceo-audit-output/report.sarif
           category: ceo-audit
         continue-on-error: true
+
+  # ─── Profile mirror drift gate (issue #175) ────────────────────────────
+  # Builds the Go binary from the same commit under audit and runs
+  # `sin-code profile verify`. If the on-disk per-agent mirrors under
+  # .claude/, .codex/, .cursor/, .github/, etc. have drifted off the
+  # single source `docs/agent-profiles/sin-profile.md`, the job fails
+  # the same way the verify-gate fails in `internal/verify` (M3).
+  #
+  # CEO audit (above) runs concurrently because both jobs share no
+  # state. This job does NOT intend to gate on per-machine Python
+  # skills — it strictly mirrors the byte-stable contract of
+  # internal/profile.Verify.
+  profile-verify:
+    name: Profile verify (issue #175)
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Go
+        uses: actions/setup-go@v5
+        with:
+          go-version: '1.25'
+          cache: true
+
+      - name: Build sin-code
+        run: go build -o /tmp/sin-code ./cmd/sin-code
+
+      # Render the mirrors if absent or stale. `render all` is
+      # idempotent (byte-identical on unchanged source), so the
+      # call is also a self-test for the byte-stable contract.
+      - name: Render per-agent profile mirrors
+        run: /tmp/sin-code profile render all
+
+      - name: Verify mirrors match source SHA
+        run: |
+          /tmp/sin-code profile verify
+          STATUS=$?
+          if [ $STATUS -ne 0 ]; then
+            echo "::error::sin-code profile verify failed (exit=$STATUS); mirrors drifted off docs/agent-profiles/sin-profile.md"
+            exit 1
+          fi
+          echo "::notice::Profile mirrors byte-stable; verify gate passed."
+
+      - name: Upload rendered mirrors as artifact
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: profile-mirrors-${{ github.run_id }}
+          path: |
+            .claude/skills/sin-code/SKILL.md
+            .codex/rules/sin-code.md
+            .config/opencode/skills/sin-code/SKILL.md
+            .cursor/rules/sin-code.mdc
+            .gemini/skills/sin-code/SKILL.md
+            .windsurf/rules/sin-code.md
+            .clinerules/sin-code.md
+            .github/copilot-instructions.md
+          retention-days: 14
+          if-no-files-found: warn

AGENTS.md

@@ -240,7 +240,7 @@ SIN-Code/
 ├── go.mod                     ← module github.com/OpenSIN-Code/SIN-Code
 ├── .goreleaser.yaml
 ├── .github/workflows/
-│   ├── ceo-audit.yml          ← n8n delegation (mandate M1)
+│   ├── ceo-audit.yml          ← n8n delegation (mandate M1) + profile-verify job (issue #175)
 │   ├── sin-code-release.yml   ← goreleaser + brew tap
 │   └── ecosystem-sync.yml     ← prevents registry/permission/ECOSYSTEM drift
 ├── install.sh                    ← 27-line curl|bash shim → `sin-code install` (issue #170)
@@ -252,7 +252,9 @@ SIN-Code/
 │   ├── HOOKS.md
 │   ├── LEARNING.md
 │   ├── WEBUI.md                ← WebUI-v2 backend contract
-│   └── mcp.json.example
+│   ├── mcp.json.example
+│   └── agent-profiles/
+│       └── sin-profile.md      ← v3.18.0: single-source-of-truth per-agent profile (issue #175)
 │
 ├── cmd/
 │   ├── sin-code/              ← MAIN BINARY (40 subcommands — v3.18.0)
@@ -280,6 +282,10 @@ SIN-Code/
   │   │   ├── compress_cmd.go       ← v3.18.0: sin-code compress subcommand (plan/apply/rollback, issue #172)
   │   │   ├── permission_defaults.go ← C4: default rules + MCP prefix policy
 │   │   └── internal/          ← 17 packages (v3.8.0)
+│   │   ├── install_cmd.go       ← v3.18.0: sin-code install (issue #170)
+│   │   ├── profile_cmd.go       ← v3.18.0: single-source-of-truth profile renderer (issue #175)
+│   │   ├── permission_defaults.go ← C4: default rules + MCP prefix policy
+│   │   └── internal/          ← 18 packages (v3.18.0)
 │   │       ├── agentloop/     ← PLAN→ACT→VERIFY→DONE loop
 │   │       ├── session/       ← SQLite-backed resumable sessions
 │   │       ├── permission/    ← allow/ask/deny engine
@@ -299,6 +305,8 @@ SIN-Code/
 │   │       ├── summary/       ← v3.13.0: deterministic session summary builder
 │   │       ├── install/       ← v3.18.0: pure-stdlib release install + SHA256 verify + atomic place (issue #170)
 │   │       ├── mcpcompress/   ← v3.19.0: ponytail-tag compressor for `serve --compress-tools`
+│   │       ├── install/       ← v3.18.0: pure-stdlib release install + SHA256 verify (issue #170)
+│   │       ├── profile/       ← v3.18.0: single-source-of-truth per-agent renderer (issue #175)
 │   │       ├── llm/           ← provider layer
 │   │       ├── style/         ← v3.17.0: verbosity / compression mode system-prompt renderer (issue #167)
 │   │       ├── orchestrator/  ← DAG, critic, adversary, governor, ...
@@ -518,6 +526,7 @@ Core:      discover, execute, map, grasp, scout, harvest, orchestrate,
            ibd, poc, sckg, adw, oracle, efm
 Agents:    chat, sessions, mcp, goal, daemon, skill, superpowers,
            vane, stack, gh, install
+           vane, stack, gh, install, profile
 Frontend:  serve, tui, webui
 Lifecycle: memory, knowledge, todo, notifications, orchestrator_run,
            orchestrator_agents, orchestrator_plan, update
@@ -526,6 +535,42 @@ Utility:   read, write, edit, lsp, plugin, index, security, sbom,
 ``` (v3.18.0: 40 subcommands; `install` is the v3.18.0 single-binary installer from issue #170)
            config, self-update, hub, ledger, summary, compress
 ``` (v3.18.0: 40 subcommands, up from 39 in v3.13.0)
+``` (v3.18.0: 40 subcommands, up from 39 in v3.16.0;
+`install` is the v3.18.0 single-binary installer from issue #170;
+`profile` is the v3.18.0 single-source-of-truth per-agent renderer
+from issue #175.)
+
+### Per-agent profile distribution (issue #175)
+
+`sin-code profile` renders the single in-repo source
+(`docs/agent-profiles/sin-profile.md`, ≤80 lines, KISS) into every
+per-host-agent mirror file. The render is **byte-stable** per
+`(target, source)` pair; the verify gate (`sin-code profile verify`)
+refuses to pass whenever any mirror drifts off the source SHA. Adding
+a target is non-breaking; renaming or removing one is a major bump.
+The single source of truth for the table is
+`cmd/sin-code/internal/profile/target.go` — keep the AGENTS.md row in
+sync if the table moves.
+
+| Target        | Format  | Install path (relative to repo root)                       |
+| ------------- | ------- | ----------------------------------------------------------- |
+| claude-code   | dir     | `.claude/skills/sin-code/SKILL.md`                          |
+| opencode      | dir     | `.config/opencode/skills/sin-code/SKILL.md`                 |
+| gemini        | dir     | `.gemini/skills/sin-code/SKILL.md`                          |
+| codex         | rule    | `.codex/rules/sin-code.md`                                  |
+| cursor        | rule    | `.cursor/rules/sin-code.mdc`                                |
+| windsurf      | rule    | `.windsurf/rules/sin-code.md`                               |
+| cline         | rule    | `.clinerules/sin-code.md`                                   |
+| copilot       | marker  | `.github/copilot-instructions.md`                           |
+
+The four marker-fence outputs (`rule` + `marker`) wrap the body in
+`<!-- SIN-CODE-SKILL-START: sin-code -->` … `<!-- SIN-CODE-SKILL-END:   sin-code -->`
+inside the file. The fence is **byte-identical** to the one
+`internal/skilldist` uses (issue #169): the two systems share the
+same anchor (`SIN-CODE-SKILL`) so a downstream parser finds both
+per-skill bundles and per-profile mirrors with one regex. Profile
+renders are idempotent (rerun with unchanged source = byte-identical
+output), exactly as skilldist demands.
 
 ### Hook events (verified `internal/hooks/hooks.go`, v3.5.0)
 

CHANGELOG.md

@@ -320,6 +320,36 @@ All notable changes to the SIN-Code unified binary will be documented in this fi
 - **Snapshot dir**: `~/.local/share/sin-code/compress-snapshots/`
   (overridable via `SIN_CODE_SNAPSHOT_DIR`). Same form factor as
   lessons.db / ledger.db per AGENTS.md §7.
+### Added — Per-agent profile renderer (issue #175)
+- **Single source of truth** at `docs/agent-profiles/sin-profile.md`
+  (≤80 lines, KISS, hard mandates + working style + subagent contracts +
+  per-agent notes, edits roll out everywhere).
+- **`internal/profile`** package: targets map mirroring AGENTS.md §10
+  (`claude-code`, `opencode`, `gemini`, `codex`, `cursor`, `windsurf`,
+  `cline`, `copilot`); per-format writers (`dir`, `rule`, `marker`); a
+  byte-stable `Render(tgt, body)`; a `Verify(base, body)` SHA-256
+  drift gate; idempotent marker-fence envelopes byte-identical to
+  `internal/skilldist` (issue #169 covenants preserved).
+- **`sin-code profile` subcommand** with four verbs:
+  - `profile show`               — print the source markdown
+  - `profile list`               — print the supported target table (text + `--json`)
+  - `profile render <target|all>` — write one or all mirrors (idempotent;
+    supports `--dry-run` for byte/audit preview without touching disk)
+  - `profile verify`             — CI gate: refuse on missing/drift;
+    surfaces a 12-char-row table or a JSON envelope for `--json`
+- **Permission engine**: `profile__show` / `list` / `verify` are
+  registered as `allow`; `profile__render` is `ask` because it
+  touches per-agent dotdirs (mandate M4).
+- **CI sync**: `.github/workflows/ceo-audit.yml` grew a parallel
+  `profile-verify` job that builds `sin-code`, runs
+  `profile render all && profile verify`, uploads the rendered
+  mirrors as artifacts, and fails the build if any drift surfaces.
+  Mirrors AGENTS.md §6 + §10 — single source of truth in
+  `internal/profile/target.go`.
+- **Test coverage**: 22 race-tested Go tests pinning the byte-stable
+  contract (golden render, marker-fence idempotency, marker-Fence
+  covenant, `Verify` pass / missing / drift, write-after-write SHA
+  equality, replace-not-append for stale mirrors).
 
 ### Added — Loop Engineering (decoupled completion authority)
 ### Added — MCP tool-manifest compression (issue #173, v3.19.0)

cmd/sin-code/internal/permission_defaults.go

@@ -89,6 +89,13 @@ func DefaultPermissionRules() []permission.Rule {
 		{Tool: "compress__plan", Policy: "allow"},     // read-only projection
 		{Tool: "compress__apply", Policy: "ask"},      // rewrites + LLM call
 		{Tool: "compress__rollback", Policy: "allow"}, // restorative — never destructive
+		// v3.18.0: profile renderer (issue #175). Read-only
+		// (show/list/verify/dry-run) is allow; the writing `render`
+		// surface is `ask` because it touches per-agent dotdirs.
+		{Tool: "profile__show", Policy: "allow"},
+		{Tool: "profile__list", Policy: "allow"},
+		{Tool: "profile__verify", Policy: "allow"},
+		{Tool: "profile__render", Policy: "ask"},
 		// Backstop catch-all (mirrors sin_bash default at line 44 for unmatched prefixes).
 		{Tool: "autodev__*", Policy: "ask"},
 		{Tool: "*", Policy: "ask"},

cmd/sin-code/internal/permission_defaults_test.go

@@ -14,14 +14,24 @@ func TestPermissionDefaultRules(t *testing.T) {
 		t.Fatal("expected default rules")
 	}
 	hasRead := false
+	hasProfileRender := false
 	for _, r := range rules {
 		if r.Tool == "sin_read" && r.Policy == "allow" {
 			hasRead = true
 		}
+		// v3.18.0 (issue #175): profile renderer surfaced to agents.
+		// The render verb touches per-agent dotdirs so must default
+		// to "ask"; show/list/verify are pure reads.
+		if r.Tool == "profile__render" && r.Policy == "ask" {
+			hasProfileRender = true
+		}
 	}
 	if !hasRead {
 		t.Errorf("expected sin_read allow rule, got %+v", rules)
 	}
+	if !hasProfileRender {
+		t.Errorf("expected profile__render ask rule (issue #175), got %+v", rules)
+	}
 }
 
 func TestPermissionRulesForAgent(t *testing.T) {

cmd/sin-code/internal/profile/doc.go

@@ -0,0 +1,34 @@
+// SPDX-License-Identifier: MIT
+//
+// # Package profile
+//
+// Profile is the single-source-of-truth rewriter for SIN-Code's
+// per-agent project rules (issue #175). The source is the in-repo
+// markdown at docs/agent-profiles/sin-profile.md; output is one
+// artifact per supported host-agent family:
+//
+//	Claude Code   → <repo>/.claude/skills/sin-code/SKILL.md
+//	opencode      → <repo>/.config/opencode/skills/sin-code/SKILL.md
+//	Gemini CLI    → <repo>/.gemini/skills/sin-code/SKILL.md
+//	Codex         → <repo>/.codex/rules/sin-code.md
+//	Cursor        → <repo>/.cursor/rules/sin-code.mdc
+//	Windsurf      → <repo>/.windsurf/rules/sin-code.md
+//	Cline         → <repo>/.clinerules/sin-code.md
+//	GitHub Copilot → <repo>/.github/copilot-instructions.md
+//
+// (Updates AGENTS.md §10 — same table.)
+//
+// # Why byte-stable
+//
+// Render(tgt, body) is a pure function over (tgt, body). The verify
+// gate (Verify + HashSource) computes the expected SHA-256 of every
+// rendered output and refuses to merge if any on-disk mirror drifts.
+// This is the same shape as the verify-gate in `internal/verify`
+// (M3) — the renderer is a deterministic preprocessor.
+//
+// # Marker-fence covenant
+//
+// RenderBlock / BeginMarker / EndMarker are byte-identical to
+// internal/skilldist's outputs for the same `<skill>` value. See
+// parser.go for the exact ASCII bytes.
+package profile

cmd/sin-code/internal/profile/doc.md

@@ -0,0 +1,88 @@
+# `internal/profile` — single-source-of-truth per-agent project profile (issue #175)
+
+## What this package is
+
+`internal/profile` renders a single in-repo markdown
+(`docs/agent-profiles/sin-profile.md`) into the per-agent mirror
+files that SIN-Code installs into every supported host agent family:
+
+| Agent family | Output path (relative to repo root) | Format       |
+| ------------ | ------------------------------------ | ------------ |
+| Claude Code  | `.claude/skills/sin-code/SKILL.md`    | `dir`        |
+| opencode     | `.config/opencode/skills/sin-code/SKILL.md` | `dir`  |
+| Gemini CLI   | `.gemini/skills/sin-code/SKILL.md`    | `dir`        |
+| Codex CLI    | `.codex/rules/sin-code.md`            | `rule`       |
+| Cursor       | `.cursor/rules/sin-code.mdc`          | `rule`       |
+| Windsurf     | `.windsurf/rules/sin-code.md`         | `rule`       |
+| Cline        | `.clinerules/sin-code.md`             | `rule`       |
+| GitHub Copilot | `.github/copilot-instructions.md`   | `marker`     |
+
+The table is the **single source of truth** in this package. Adding a
+target is non-breaking; renaming or removing one is a major bump per
+AGENTS.md §10. The set is intentionally a mirror of the skilldist
+table so the two packages can be merged later without changing
+public output.
+
+## Why byte-stable
+
+`Render(tgt, body)` is pure: the bytes depend only on (target
+struct, source body). The CLI's `sin-code profile verify` reads
+every on-disk mirror, recomputes the expected render, and refuses
+to merge if any mirror is missing or drift. This is the same shape
+as the verify-gate in `internal/verify` (mandate M3) — the
+renderer is a deterministic preprocessor.
+
+## Marker-fence covenant (issue #169)
+
+Every `rule` / `marker` output is bracketed by a
+`<!-- SIN-CODE-SKILL-START/END -->` fence with the same exact
+ASCII bytes as `internal/skilldist`. A downstream parser that
+scans for one kind also finds the other; a `profile render` call
+is idempotent (rerun with unchanged source = byte-identical
+output). See `parser.go` for the contract.
+
+## Public surface
+
+```go
+type Target struct { Name, DisplayName, InstallPath, Format string }
+var Targets map[string]Target
+func TargetNames() []string
+func MustTarget(name string) Target
+
+func RenderAll(body string) (map[string]string, []string, error)
+func Render(tgt Target, body string) (string, error)
+func Resolve(tgt Target, base string) (string, error)
+func StripFrontmatter(raw string) string
+
+func HashSource(tgt Target, body string) (string, error)
+func Verify(base, body string) ([]Result, error)
+
+func LoadSource(base string) (string, error)
+func WriteAll(base, body string) ([]string, error)
+func WriteSelected(base, body, name string) ([]string, error)
+func ListTable() []ListEntry
+```
+
+## CLI surface
+
+```
+sin-code profile show                  # print current source
+sin-code profile list                  # print target table
+sin-code profile render <target|all>   # write one or all mirrors
+sin-code profile render --dry-run      # preview without writing
+sin-code profile verify                # CI gate
+sin-code profile verify --json         # machine-readable drift
+```
+
+## Tests
+
+`profile_test.go` pins:
+
+- Exact SHA-256 of `Render(tgt, fixture)` for one target per format.
+- Marker-fence idempotency (rerun = byte-identical output).
+- `ParseMarkers` open / close / half-opened-fence roundtrip.
+- `Verify` missing-file → DriftError.
+- `Verify` drift → DriftError.
+- `Verify` pass → nil error.
+
+A new golden test fails the moment the renderer output drifts.