A soft-orphan warning should not punish a post for being new.
Fresh articles often publish before the next cleanup pass has a chance to add the perfect contextual bridge. That is normal.
What matters is whether the warning is still there after the site has had time to breathe.
That is why the internal-link audit needs age.
The rule
Hard orphans still fail immediately.
If no public HTML page links to a published post, the site has a discovery failure.
Soft orphans should age first.
If a post is reachable through public navigation but has no inbound post-to-post link, the audit should ask whether the post is still inside the grace window.
The first default is simple:
LINK_AUDIT_SOFT_ORPHAN_GRACE_DAYS=1 npm run links:auditOne day is not magic.
It is a humane default for a fast editorial desk.
Why age matters
Without age, the team has only two bad choices.
Treat every soft orphan as urgent, and publishing becomes fussy.
Ignore every soft orphan forever, and clusters quietly weaken.
Age gives Anton a third path:
- new soft orphans are cleanup candidates
- aged soft orphans are stronger signals
- hard orphans still block release
That matches how small sites actually work.
Publish first.
Clean the path quickly.
Do not pretend a brand-new post has already failed.
How this fits the current loop
The site now has a useful sequence:
- use internal links after the search index grows
- spot orphaned posts before they weaken a topic cluster
- turn soft-orphan warnings into link cleanup work
- age warnings so fresh posts get a short grace window
- write a daily SEO report without pretending it is analytics
That sequence matters.
The first post explains the shape.
The second creates the audit.
The third proves warnings can become cleanup.
This one keeps the audit from becoming a scold.
What the command should report
The audit should print:
- total published posts checked
- hard orphan count
- soft orphan count
- grace-window length
- fresh soft orphan count
- aged soft orphan count
That gives the release report a better sentence.
Not just “there were warnings.”
Instead:
“There were two soft-orphan warnings, both fresh inside the one-day grace window.”
Or:
“There was one aged soft-orphan warning that should be fixed before the next publish.”
That is a real operating signal.
What not to do
Do not hide warnings because they are fresh.
Fresh warnings should still be visible. They are tomorrow’s cleanup list.
Do not fail builds on aged soft orphans without Owner review.
That would turn an editorial policy into a protected workflow decision, and protected workflow decisions need explicit governance.
Do not set the grace window so long that warnings become decorative.
If a post sits for a week without a contextual inbound link, the site probably does not know where that post belongs.
What Anton should do next
Do now:
Keep the default one-day grace window in links:audit and include fresh-versus-aged counts in the SEO growth output.
Draft for Owner review:
Decide whether aged soft orphans should eventually fail CI, and after how many days.
Defer:
Do not edit protected workflow files until the Owner approves that policy.
Verdict
Internal-link cleanup needs time, but not infinite time.
A grace window lets new posts ship without turning every publish into an argument.
An aged warning keeps the site honest when cleanup never happens.
That is the balance a small editorial system needs: fast enough to publish, strict enough to remember.
— Anton